This section will “set the stage” (if you will) for these production enhancements. Only a little actual script is used here. This is about providing the mechanisms whereby specific features (defined elsewhere) can easily and reliably get worked into the production at the appropriate times.

It will help to talk about different locations in the site as “settings.” A setting is a set of locations in the site, usually defined as a matching pattern.

Set changes occur when going from one setting to another. When entering a setting, the script manager will see to the necessary setup, and when leaving a setting, the necessary teardown. That’s it.

Do not confuse preparing with doing. “Loading” a script is like preparing for a production effect. A script should not do anything right away except register the responses to its cues, in other words associate a setup and teardown process with a particular setting.

The teardown routine is responsible for cleaning up the effect established in the setup. If an effect is supposed to be present everywhere, a script can associate itself with the root path (/) and do nothing in the teardown.

Script modules—and, when possible, their setup and teardown routines—should be idempotent; that is, it should be safe to run them multiple times.

The special effects—established in the setup and teardown—can include basically anything else that’s possible to do in a browser.

A couple of notes on performance:

Scripts are never responsible for anything essential to basic usage, so it’s always safe to load them asynchronously. In other words, a script will never block the user from entering.

Because scripts don’t take effect right away, it’s safe to pre-load any script at any time. Pre-loading can be used to reduce delays when going to new settings. (Of course, if it is supposed to be in effect now, then it should already be loaded.)

The “show” only starts once. It proceeds through a number of scenes (the places that the user visits).

For the purpose

A scope is a part of the site defined by one location and all of its descendents.

What’s interesting about scopes? It’s common to define special behaviors that apply only to a certain scope. In such cases, it’s necessary to know when the user enters and exits that scope.

(Two locations are exclusive if their scopes do not overlap (and as such, they can never overlap, even if new descendant locations are added). It’s also common to consider moving between exclusive scopes.)

The simplest case is where you want to do something only once, and never again. You don’t even need a special mechanism for that—just put some code in the module.

The next simplest cases is where you want to do something whenever the location changes at all, in any way. That’s currently handled by navigating.on(change).

The next simplest case is where you want to do something whenever the user enters a certain location. The essential bits that you’d express are a path/context matching function, a setup function, and a teardown function.

bind({
	match: context => /\/some\/special\/location/.test(context.path),
	setup: () => { console.log("do stuff"); },
	teardown: () => { console.log("undo stuff"); }
});

There are also “classes” of scopes, just as there are classes of paths.

The next case is where you want to do something whenever the user enters a certain class of locations. Normally, in such cases, your setup/teardown would recieve the context as an argument.

bind({
	match: context => (/^\/some\/{type}\/location/).test(context.path_pattern),
	setup: context => { console.log("do stuff for type", context.items.type); },
	teardown: context => { console.log("undo stuff for type", context.items.type); }
});

The next—and I think final—case is where you want to handle both sides of a transition at the same time. This may be supported within a class of paths. Only the context would be changing.

bind({
	match: (from, to) => from.items.thing && to.items.thing,
	transition: (from, to) => {
		console.log("do stuff for going from ", from, 'to', to);
	}
});

Note this uses a different key, transition. A setup and teardown wouldn’t make sense in this case.

How would you know that the matching function is expecting two arguments? Maybe it’s always passed two arguments… but in the earlier cases (where you’re ignoring it), then, you’d expect to to be first. That’s a little counter-intuitive for the transitional case, but it’s less common.

The matching function work if you knew that thing were only defined for the target scope. Otherwise, you’d need also to do a path pattern test.

So how could the bind function (or whatever you want to call it) be defined so as to accomplish the above?

Basically, it’s like the register_effect function defined below.

But it assumes a context that contains the path, the path_pattern, and the items (keys from the route match).

That’s really the only difference. But what would it take to get that stuff? Getflow doesn’t expose the router, or push that information in state. The reason for putting the onpushstate wrapper into willshake was to support pushState calls from willshake itself (such as, I think, were done from the audio module). That’s fair enough, but it means that you can’t expect whatever state getflow includes when calling pushState. You’d have to be able to call the router.

The point is that the setup function would only fire when you’re entering that scope, and the teardown function would only fire when you’re leaving that scope.

How would bind detect a change in the case above where path_pattern is used? Because match will return true in both cases. It could compare the keys as well… but how can you make the intention clear? I suppose if you match on a path pattern, the intention is clearly to consider different routes to be different.

But what are the semantics of this? Does this in fact have anything to do with “scopes” as I’m calling them? In other words, is bind (or “register”) supposed to be attaching to a scope as such?

And what about the audio case? This doesn’t allow you to be agnostic about the actual route. I don’t want the audio player to attach to any particular paths (as much as possible), so it has to use the more primitive movement hooks. Right? The audio itself has nothing to do with the route (in principle), and its work depends on information that’s not available from the route context.

There’s just no way to write this in terms of scopes, if you can’t be specific about what those scopes are. So either you’d have to implement audio separately for each place that supports it (which I don’t want to), or—again—use a different mechanism.

I don’t see that there’s a way to generalize this. The audio setup has to be responsible for its own “detection” of whether setup and teardown are necessary.

Well, I suppose that you could have the match function use information from the environment. That sounds like a bad idea.

Of course, like all of willshake’s programs, JavaScript is written as part of these documents. The script blocks are turned into files through the “tangling” process (see the system). And again, JavaScript is delivered as text files. Compared to other ways of shipping software, using scripts in a browser is easy. It’s really just a matter of copying files, and referencing them.

But before getting to the web site, those JavaScript files go through a few “preproduction” stages, for various reasons.

At each stage, you’re still dealing with javascript.

A script is a “piece of writing."⁹

Of course, just about everything in a web page is “a piece of writing,” not least the document itself.

And yet the script in a web document is one of the very things that you don’t see.

The script is the piece of writing that is interpreted by the browser.

“Script” is a term of art in computers, which usually refers to programs that are interpreted from text. And notwithstanding that today’s (and tomorrow’s) JavaScript engines no longer regard JavaScript as “interpreted” in that sense, it retains the spirit of a scripting language since it is almost always delivered as plain text.

In other words, a script is a plan of action. Without scripts, a web page can’t really do anything (except be scrolled). It’s “just a document.” It’s dead. In fact, the original name of the scripting language introduced by Netscape in 1995 was “LiveScript.” (Legend has it that they changed it to “JavaScript” because Java (a completely different language) was the hotness at that time, but I’m staying out of that.)

It’s scripts that make a fluid experience possible. Without any scripts at all, willshake works like a web site from the early 1990’s. Each time you click a link, a new page is loaded. It’s like a series of stills.

Again, willshake works without any scripts at all. So “the show goes on” even without scripts, or script management. It’s just not quite as good of a production.

For the sake of simplicity, this web site is a monolith.

All of the stylesheets and scripts are considered part of one big machine.

Many scripts and stylesheets will be relevant only in some places. But they should not break anything in others. The only reason for breaking them up is for the sake of efficient delivery. Any script (except maybe the first one) can be downloaded (prefetched) and run at any time.

This is even more true with scripts, since, unlike stylesheet links, scripts can’t really be removed after the fact. Removing a script tag won’t change the fact that the script has already run, and whatever change it has wrought on the state of the javascript VM certainly can’t be reversed (not in this world, anyway). Therefore, it must always be safe to load any script. This view is necessary as a consequence of the way that getflow works, but really it makes things much simpler to think about, anyway.