created:2021-05-14
author:Foobär
top:README:Settings:Hooks
sort:017
title:Hooks

<p>
A hook is a function that is declared in the settings file of a web site. It does not exist in the SBWG script and therefore is not executed if it is not included
in the settings file. No hook is required. There are many hooks that get executed at different points in the generation of a web site. Therefore they can be used to
inject code at certain points of the script for only the web site who's settings file contains the hook. This way the script does not need to be edited for
customisation and different web sites can be customised differently.
</p><p>
Inside a hook all variables that exist at the point at which the hook is executed can be read and changed. Output can be added to the file that is being generated at
that point, additional commands can be executed, and so on. This makes the settings file a very flexible tool for the customisation of a web site and SBWG itself,
and a possible source of errors when not used carefully.
</p><p>
When writing an elaborate new hook (as opposed to copying an example hook or hook from an existing settings file) you will probably not be able to avoid reading at
least some of the SBWG script to see how your goal can be accomplished. There are a couple of helper functions in the script that of course can also be used in
hooks. I will not explain here every part of the code that could possibly be of relevance when writing a new hook. I don't know what you want to do with your hook,
so I wouldn't know what to limit myself to.
</p><p>
The below table lists all hooks that currently exist in SBWG and the local variables that are accesible inside these hooks. Additionally there are a couple of
global variables that are accessible from inside every hook:
</p><p>
<li><code>$shellbase</code> - The path of the input directory - The directory of the web site that is being generated</li>
<li><code>$tmpdir</code> - The path of the temporary directory - This directory will be deleted after the script is done or when it fails.</li>
<li><code>$version</code> - The version of SBWG that is processing the website</li>
<li><code>$options</code> - A string of option letters that are set through command line options</li>
<li><code>$entrylist</code> - An array that contains all entry names that exist on the web site. Only available after the navigation bar has started to be generated.</li>
<li><code>$entrylists</code> - An associative array with all existing tag names as keys and lists of entry names as values. Only available after tagpage preparation.</li>
<li><code>$tagslist</code> - An array that contains all existing tags. Only available after the navigation bar has started to be generated.</li>
<li><code>$gallerylist</code> - An array that contains the names of all galleries on this web site than contain any supported image files. Only available after navbar generation.</li>
<li><code>$desired_entry</code> - The entry name, if one was passed to option -e (or --entry).</li>
<li><code>$desired_page</code> - The page name, if one was passed to option -p (or --page).</li>
<li><code>$desired_tagpage</code> - The name of the tagpage, if one was passed to option -t (or --tagpage).</li>
<li><code>$desired_gallery</code> - The name of the gallery, if one was passed to option -g (or --gallery).</li>
<li>All variables that are declared in the settings file as well as the default values for settings that are not set in the settings file</li>
</p><p>
Because the settings file is sourced in the script after all functions have been declared, you could also overwrite a function to replace it with a custom version
of yours without editing the script file itself.
</p>
