Advanced Concepts

Fragments need not be from your own computer. You can use curl to bring in fragments from the Internet. You can even bring in .sd files from the Internet if you want. We hope that there will be FillPouch projects floating around on the Internet, which you can use directly, and you just add some/all of the missing contents.

If you do not like writing the HTML bold,italic tags, you can write .md files instead of .sd files. FillPouch will send .sd files to the pandoc converter, and bring back the actual content with all the HTML inside.

First steps with curl and pandoc:
"curl" and "pandoc" are NOT included by default in the installed folder. Please download the binary executable files for each, and save them in the folders by the same name in the same folder as fillpouch. i.e. Pandoc should be available as pandoc\pandoc.exe from the FillPouch folder, and curl should be available as curl\curl.exe There is a "README.txt" file in each of those folders which will give more details.

Using Pandoc
You do not have to do anything to run pandoc. FillPouch already knows how to call pandoc to convert .md files and use them. Just make sure that pandoc is present in the aforesaid folder. An ".md" file is a markdown file -- some people find it more easy to write .md files for simple HTML so you don't need to write HTML tags such as <b> and <i>. Instead markdown uses some clever formatting techniques using asterisks for representing bold and italics. Quite a useful method, frankly.

Using curl
Note that the functionality of calling curl is already baked into FillPouch. As stated earlier, the curl executable has to be in the correct folder ('curl') inside the same folder where the FillPouch executable resides.

For actually invoking and using the output of curl, you have to create a file with the extension .crl It should contain all the arguments that curl would need to successfully access a URL with the right method. Curl should also be given other data (if so required; as POST calls would usually need them). Such a .crl file should NOT have the -o argument, as that would be provided by FillPouch.

When FillPouch encounters such .crl files, it would pass that .crl file to curl. When curl returns, FillPouch will use that returned data. Here is an example of such a .crl file: 

    --location 
    --silent
    --url https://somewebsite.com/api/ggg
In the above example; Curl would fetch the data from https://somewebsite.com/api/ggg and give the returned output to FillPouch, which FillPouch will incorporate into the site during the site building process.

Using other external handlers
FillPouch actually can handle other types of such executables -- one that would take a text file, and output another text file. The only condition is that such an executable file should run without interaction from the command-line in Windows. To use such executables, all you have to do is to add a handler instruction in the configuration file of FillPouch.

Universal g(...,...) variables
The name/value pairs are usually defined using a g(...) instruction. However some variables are deemed universal. You do NOT need to write them down as a specific g(...,...) instruction. Instead you can directly use those variables in the v(...) meta-instruction! These are as explained below: 

    v("_c")      The current path  
    v("_y")      Current year
    v("_m")      Current month 
    v("_d")      Current day 
    v("_dw")     Will give an integer for day of week: 0 means Sunday, etc
    v("_hr")     Current hour (local time)  
    v("_mi")     Current minutes (local time)  
    v("_sc")     Current second (local time)
    v("_hd")     Current hundredth of second (local time)

Apart from above, you can write one character variable such as v("-") to mean the character itself. So if you write this pouch [[v("_d"),v("/"),v("_m"),v("/"),v("_y")]] FillPouch will insert the date in d/m/y format.

Environment variables
You can also use environment variables in the v(...) meta-instruction. So if you had an environment variable named "SITE_VERSION" set before calling FillPouch, you can insert v("SITE_VERSION") in a pouch, and FillPouch will insert whatever the value was set for that environment variable.

Advanced command line options
Usually, FillPouch will generate all the files from the project folder in the build folder by giving this command: 
     fillpouch.exe PROJECTFILE.proj

You can also use FillPouch command line to achieve some more objectives, as explained next:

1. Delete backup files
This will delete all *.bak that can exist in the build folders 
      fillpouch.exe clean PROJECTFILE.proj


2. Empty all the generated HTML files
This will delete all *.html that were previously generated in the build folders 
      fillpouch.exe empty PROJECTFILE.proj


3. Sync-Copy files
This will copy existing files from the project folders to the build folders (except .html,.txt,.crl and .sd)
This is useful to copy images and javascript that you may have kept in the project folders to the build. 
      fillpouch.exe copy PROJECTFILE.proj
4. Get help regarding the specific project
A project file can contain the notes(...) instruction. If you give the following option (i.e. -h) it will write out the notes for the project and exit without building. This is very useful when you are creating a project file for someone else, and you want to give some instructions on how that website is to be built or your copyright notice or whatever! 
      fillpouch.exe -h PROJECTFILE.proj


Configuration file for FillPouch
Usually, FillPouch does not need a configuration file as it has quite useful internal default settings. But to specify some advanced settings, you would need one. Please come back here later when we flesh out this in more detail.