Auto Links

You may have noticed that this website has proper navigation links at the top. The documentation also has a list of neat links. How are they produced?

FillPouch has the capability to iterate and list all the links from the file(...) instructions in the main project file. These links can be used inside a special pouch containing the "v(...)" meta-instruction.

Auto Links from file(...) instructions

    [[v("~~<a class=\"navbar-item\" href='/%s.html'>%s</a>")]]

Note that the argument for the above "v(...)" meta-instruction starts with two tildes "~~". When I write the above "pouch" inside a .sd file, FillPouch will repeatedly take each of the file(...) it finds in the project file; and transforms the information it found to the correct link. There are 2 sets of "%s" characters in that meta-instruction. The first one is used to create the link. The second one writes a helpful name for that link.

FillPouch is quite intelligent: It can detect the home page, when it finds a reference to the file "index.html" in the root of the site. For other files it detects in the root, it will put name of the file without the extension. For files within a folder, it will use the folder name, if the filename is "index" -- and for other files it will use the name of the file without the extension.

Auto Links from clone(...,...,...) instructions

    [[v("~1<a class=\"navbar-item\" href='/%s.html'>%s</a>")]]

Note that the argument for the above "v(...)" meta-instruction starts with one tilde and a number "~1". This tells FillPouch to collect all the clone(1,...,...) from the project file (i.e. the clone for index 1), and iterate through each one when generating links. That is how the links for the documentation of this site were created.

Text iterations from g(...,...)

    [[v("~blurb<span data-idx='%'>%</span> ")]]

This type of iterations are done on values given in name+value pairs seen in g(...,...) instructions in the main project file. In the above case, it searches for g("blurb",__) and uses its values in the iteration. The formatting string requires two percentage signs. The first one is used for the index number of the iteration (starts with 1) and the 2nd one is the actual string. This is quite useful not just for the way we used in on our website (to attach to blurbs to the footer) but it can also be useful to create image carousels. Note that the index number of the iteration always precedes the variable value in the formatting string (i.e. the text you supply which has the two percentage signs).

Iterate clone links for a specific tag

    [[v("~#1-jan<a class=\"navbar-item\" href='/%s.html'>%s</a>")]]

Say you are using FillPouch for a blog, and you have given the tag "jan" for January articles, and "feb" for February articles, and you want to have a tag cloud only for January and another one for february; then this kind of iteration will help!

In the above example "#1" indicates that this iteration has to be done only for clone(1,...,...) and it will list out only those links which has been tagged by "jan" (case insensitive). Note that it is assumed here that the tags are specified in the said clones as a comma-delimited text with no spaces between one tag and the next.

If you gave 2 hashes like this [[v("~##-jan<...)]] then ALL clones irrespective of its index number will be used for the iteration. Here is an example where it can be quite useful: if you have multiple blogs on your site; each maintained by a different author. And you now want a tag cloud for ALL the blog articles (irrespective of author) which was tagged as "jan"... that is when you use this!

Important!
Please note that in all the aforementioned of iterative generation, you must give two sets of "%s" embedded into the argument given to the "v(...)" meta-instruction else the program will fail! Also note that FillPouch will split the given v(...) text into two parts on the first "<" it encounters, and uses the first part to take a decision. The second part is the formatting string where you have to give 2 percentage signs for FillPouch to enter what it discovered during the iteration.