So let’s start by getting getflow to the web site. On the client side, getflow is distributed as a single script. We just copy it to the web site.

: $(ROOT)/getflow/<client_min> \
|> ^ ship getflow client^ cp %<client_min> %o \
|> $(SITE_SCRIPT)/getflow.js

That’s it. Note that the web server also uses getflow, but this is all that’s needed for client operation (i.e. a browser).

Get the unminified version, too, for development. On the wierd name, see compressing and shipping.

: $(ROOT)/getflow/<client> \
|> ^ ship getflow client (full source) ^ cp %<client> %o \
|> $(SITE_SCRIPT)/getflow.js.src.js

All of the routes and change rules get bundled together into one file, which getflow calls the “blueprints” (or “master plans”). Why? Why not? It’s convenient to have everything in one place. This way, with just two downloads (the getflow client, and this bundle), the web site can start responding right away to any link that is clicked. Yes, additional downloads may be necessary for most locations, but some action can be started immediately, which everyone agrees is healthy for today’s users’ sense of well-being.

: $(ROOT)/change_rules/bundled/bundle.xsl \
  $(ROOT)/program/routes.xml \
  | $(ROOT)/change_rules/<bundled> \
|> ^ bundle blueprints^ xsltproc %f > %o \
|> $(SITE)/getflow.xml $(SITE)/<getflow.xml>

This takes as input the routes definitions. Then it bundles the change rules into the route elements.

What is bundle.xsl? It’s a transform that will “inflate” the routes with the relevant change rules.

<<standard rule transformations>>

We’ll start with an identity template, which copies everything from the input as-is. This is a standard XSL thing, so let’s write it to its own transform.

<xsl:template match="node()|@*">
	<xsl:copy>
		<xsl:apply-templates select="node()|@*" />
	</xsl:copy>
</xsl:template>

And use it in the bundle transform.

<<identity transform>>

And… elsewhere.

<<standard rule transformations>>

Now, when we encounter a route element, we insert the contents of the change rules.

<xsl:template match="route">
  <xsl:copy>
		<!-- Keep all attributes except "to", since we're replacing it with the
		     contets.  In practice, we don't use attributes on route, anyway. -->
    <xsl:apply-templates select="@*[not(name()='to')]" />
    <xsl:apply-templates select="node()" />
    <xsl:apply-templates select="document(concat(@to, '.xml'))/r/node()" />
  </xsl:copy>
</xsl:template>

Each location in the site has a route and a set of change rules. When you add a new location, you create a file with the initial change rules for that location, and you add a route which points to that file. For example, at the /plays path, as it is initially defined, we mark the plays region as active.

But suppose that a feature defined in the future wanted to extend this behavior. In our additive building model, we don’t want to change the existing definition of the rules for /plays—we just want to add to them. Here, we allow any document to add new rules to any set:

# Need a separate copy of this here because it's referenced relatively... ugh.
: $(PROGRAM)/transforms/identity.xsl \
|> !link_from |> $(ROOT)/change_rules/identity $(ROOT)/change_rules/<identity>

service make_change_rules \
: foreach $(ROOT)/change_rules/*.xml \
  | $(ROOT)/change_rules/more/<all> \
    $(ROOT)/change_rules/bundled/<bundler> \
    $(ROOT)/change_rules/bundled/<transform> \
|> ^o group change rules %B^ \
   echo "%<all>" | %<bundler> %<transform> %f > %o \
|> $(ROOT)/change_rules/bundled/%b \
   $(ROOT)/change_rules/<bundled>

So for example, if you want to extend a set of change rules called plays.xml, you can add a file called more/plays--new-feature.xml, and this will be included in the set.

The bundling is done with a little script, which also adds opening and closing tags to make the result usable as an XML document:

transform="$1"
main_file="$2"                                  # project-relative path
file="${main_file##*/}"                 # strip path
name="${file%.*}"                               # strip extension

# Reads the file list from the input to this command.  Sorting is important
# because sometimes filenames are used to control the order, and the list as
# provided by Tup is not sorted.
for more in $(tr ' ' '\n' | sort); do
	more_file="${more##*/}"          # strip path
	more_name="${more_file%--*}" # strip suffix
	if [ $name = $more_name ]; then
		more_for_this="$more_for_this $more"
	fi
done

make_bundle() {
	echo '<r>'
	cat "$main_file" $more_for_this
	echo '</r>'
}

make_bundle | xsltproc "$transform" -

In the process, we also run a transform on those rules. The next section covers the purpose of this.

As we saw earlier, we can actually change the change rules that we’ve written, just by adding templates to that pre-process. This could be useful. Suppose that there were some bit of markup that we wanted to use in a number of places, even with variations. We could add a rule to recognize a shorthand for it, and expand it.

But that shouldn’t stop us from creating our own features! Besides, how could we expect getflow to know what we wanted? In fact, we don’t expect ourselves to know what we might want in the future, when it comes to writing change rules. So here we’re going to try to do something about that.

(Yes, if we were using a Lisp, then we wouldn’t have this problem at all. But we aren’t using a Lisp.)

Shorthand will sometimes be convenient. Let’s make it possible to define some shorthand. Then will define some shorthands. And we’ll make sure that new features can create new shorthands.

: $(ROOT)/change_rules/make_transformer \
  | $(ROOT)/change_rules/transforms/<all> \
|> %f %<all> > %o \
|> $(ROOT)/change_rules/bundled/transform.xsl \
   $(ROOT)/change_rules/bundled/<transform>

Assemble all of the defined macros into one transform, and we’ll throw in some string functions.

echo "<?xml version='1.0' encoding='utf-8'?>"
echo "<xsl:transform version='1.0'"
echo " xmlns:xsl='http://www.w3.org/1999/XSL/Transform'"
echo " xmlns:strings='http://exslt.org/strings'"
echo " extension-element-prefixes='strings'>"
echo "<xsl:output omit-xml-declaration='yes' />"
list="$(echo $* | tr ' ' '\n' | sort)"
cat $list
echo "</xsl:transform>"

I know. That’s XML for ya.

Although getflow has “templates” for most rules, the templates have no processing power of their own (other than to interpolate the result of XPath expressions). Instead, it lets you call an XSL template. Here we copy the transforms to the web site in the expected location.

service ship_transforms : foreach $(TRANSFORMS)/* \
|> !copy_to |> $(SITE_TRANSFORMS)/%b  $(SITE_TRANSFORMS)/<all>

I’m not sure the best place to do this.

“Anchors,” also known as “hashes” and “fragment identifiers,” are a useful (if not absolutely essential) part of URI’s. They let you point to a specific place within a document (provided that the author has given it a unique ID).

Likewise, :target selectors are very useful for highlighting a specific point in the current page.

But when you use pushState to change the page address, :target selectors don’t update to reflect the new target. This has been the case for a long time, and apparently that’s not going to change.²

I agree with Paul Irish that this is how it should work, though.

My first thought is, what if you just set location.hash to itself after a page transition?

Yes, that works, but it jumps to the anchor now. Whereas I have special handling to scroll to an anchor… so you’d have to do it after that, if the scrolling takes place, and immediately, otherwise.