Snaplook Admin Manual

• What is Snaplook?
• How Snaplook Works
• Setting up Snaplook
• Snaplook Config File
• Templates and Includes

---

What is Snaplook?

Snaplook is a small fast template parser written for one purpose -- making the website look uniform, while still making it easy for users to edit their pages. The biggest problem with many other templating engines is that they require special tags to be placed inside the HTML pages, or even worse -- they require special clients or web interfaces in order to add/change data.

Snaplook is a small template parsing engine that will grab the output of the simple HTML file, and add a small header, footer, and navigational menus. No special tags or additional knowledge is required on the user-end in order to edit the pages or create new ones. Most HTML editing software will do the job quite fine. For more information about this subject, see the user guide.

How Snaplook Works

The idea is quite simple -- capture the page output and modify it to give it the uniform look and feel of the website. This is accomplished by using output buffering functions in PHP. As long as you have mod_php installed with apache, you can use snaplook.

Snaplook does not concern itself with the website layout -- it assumes that you do that yourself using a sane directory tree structure to organize your website. A well-designed website directory tree will aide you a lot in other tasks as well, not just templating.

Menu files

The only special bit about snaplook are the menu files. These are small files with entries which tell snaplook such things as the title of the directory, and what things to link to whenever files in this directory are displayed in snaplook. Whenever invoked, snaplook will traverse the entire web tree from docroot and to the current directory. This is the most processing-expensinve part of the script, although disk caching helps a lot. See also the "Tweaks" part in the config-file section.

For more information about the contents of menu files, please see the user manual.

Setting up Snaplook

The idea is to use PHP's output buffering functions to capture the html produced by the user pages, and to wrap them in a unform header and footer. To do that, we will do the following:

• Place files in some sane locations
• Designate an extension to use for snaplook-enabled html files
• Tell PHP to use output-buffering for snaplook-enabled files

Placing files into sane locations

There are only three files in snaplook, so that's not that hard. According to the FHS conventions, main.inc and essentials.inc files go into /usr/share/snaplook, while snaplook.conf goes into /etc/snaplook. I suggest you adhere to this. Remember to copy snaplook.conf as /etc/snaplook/default.conf, otherwise snaplook won't find it.

Designating an extension

By convention, ".ptml" is used for snaplook-enabled pages. Depending on the environment, it can conflict with other ".ptml" pages, as there are plenty of various engines using "ptml" for their needs. The extension for snaplook can really be anything you like, including ".lala".

Placing the config file in place

Copy apache.conf file that comes with the distribution into /etc/httpd/conf.d/snaplook.conf. You might want to edit it if you have changed something from default settings.

Using with virtual servers

Keep your global configs, and just point snaplook at different config files by using SetEnv in apache. E.g. add the following to your mydomain.com virtual domain:
SetEnv SNAPLOOK_CONFIG /etc/snaplook/mydomain.conf

Snaplook config file

Snaplook config file is in the win.ini config file standard, since that is easy to read and edit. What follows are the general conventions of such config files:

• "#" and ";" begin comments, unless they follow a backslash: \# and \; will not be regarded as comments.
• whitespace before the variable name and after the variable name and before the '=' sign will be ignored.
• variable names can contain only aphanumerics and '_'
• whitespace after the '=' sign and before the variable value will be ignored.
• whitespace after the variable value will NOT be ignored, except for newlines.
• variable values should be on one line, unless backslash-newline is used to indicate that the value is continued on the next line.

[server]

webroot

This almost always is your document root in apache. In fact, I can't think of the time when it should be something else.

relroot

When you need to use snaplook not from the top directory of your website, but from a few dirs down, you can specify that in relroot. This is only useful for menufile traversing, though, if you need to enable/disable .ptml files depending on the directory they are in, you will have to define that using Directory directives in httpd.conf. However, if you only want to traverse for menu.inc files starting from /some/path below the webroot, that's what you will pass to relroot.

userspace

Special workarounds are needed for ~user/ mappings. Setting this to on will enable mapping the userspaces in order to correctly traverse the tree for menu.inc files.

userdir

Most commonly public_html. This setting is ignored unless userspace is set to on.

[includes]

This section contains definitions for the header and footer files for snaplook to use. See the section about include files for more information.

header

Where to look for the header template.

footer

Where to look for the footer template.

pheader

Where to look for the special "printer-friendly" header template.

pfooter

Where to look for the special "printer-friendly" footer template.

[menu]

This is where things related to menu files are defined. See the section about menu files in the user manual for more information about the format of the file.

menufile

By convention, the filename for menu files is menu.inc, but depending on your environment, you might want to set it to something else, like .menu.

top_linked_item

Admittedly, snaplook is not a very flexible templating engine. It expects, for example, two things -- that your pages will contain some sort of a "top menu" where the linked hierarchy will be placed with directory titles. It also expects that your template will contain a "side menu" where the contents of menu.inc will go, as well as the reverse directory hierarchy in the "Return To" section. If that confuses you, just look at any of the pages generated by snaplook and you'll see what that means.

Linked items in the top menu lead to the previous dirs in the tree hierarchy. Here is the example entry:
   top_linked_item = <a class="nowrap" href="%%LINK%%">%%TITLE%%</a>:
%%LINK%% will be the link leading to the directory, and %%TITLE%% will be the title of that directory. If you are confused, again, look at the source of the snaplook-generated file for the moment of clarity.

top_title_item

This is where the title of the page being viewed will go. It is not linked to anything since it's currently being displayed. The only template entry it expects is %%TITLE%%.

side_title

The title of the directory currently engaged, and the "Return To" title will be displayed using that mask. The only template entry it expects is %%TITLE%%.

side_menu_item

Similarly to the top_linked_item, this expects %%LINK%% and %%TITLE%% to be both present. It is used to make the side menu entries linking to the items in menu.inc files and the reverse hierarchy.

[defaults]

title

If the page has no title, this will be used instead.

[aliases]

Aliases in Apache confuse the directory traversing in search of menu.inc files, so they have to be specified separately. An example entry would be:

/projects = /usr/project

[filter]

The only filter currently is mail munging, which operates by replacing @ symbols with arbitrary sequences, "[at]" by default.

mailmunge

Can be 'on' or 'off'. Also, users can set it locally by providing <?php $MAILMUNGE="on" ?> somewhere in their page, or per directory by setting "SetEnv SNAPLOOK_MAILMUNGE on" in their .htaccess file.

atsymbol

What to replace '@' symbols with, '[at]' by default. Can be set to something like '@REMOVE.THIS.PART.'. Users can set it per-page by providing <?php $ATSYMBOL="[at]" ?> or per directory by setting "SetEnv SNAPLOOK_ATSYMBOL [at]" in their .htaccess file.

[tweaks]

There isn't much here at the moment. Snaplook is pretty speedy, since there isn't much it needs to do. The most expensive part of the script is traversing the tree and constructing the menus out of menu.inc files. This process can be tweaked to cache some of the values for a speedier retrieval.

There is only one tweak available at the moment -- session tweaking. When on, it will use the php session management to store the arrays with menu values. According to my tests, this helps reduce the processing times by 8-10 msec on consecutive loads.

session

When set to on turns on session tweaking.

[debug]

For speedier processing it's best to completely remove all debugging routines from both main.inc and essentials.inc. To do that, run the following commands:

grep -v '_debug' main.inc > main.inc.new
grep -v '_debug' essentials.inc > essentials.inc.new

The new files will contain no debugging routines and will make the parser speedier.

level

A number from 0 to 2. 0 means off, 1 is normal, 2 adds execution time measurement outputs.

output

Where to put the debugging output.

Default location of the config

By default, snaplook will look for the config in /etc/snaplook/snaplook.conf.

Templating and include files

There are 4 include files used for templating, in two categories -- header files and footer files. When parsing the ptml file output, snaplook will remove anything before <body> (including <body> tag itself) and replace that with the header include file. The footer is added in place of whatever follows </body>, again, including the /body tag itself.

There are several templating entries that can (and should) be used inside the template files.

%%RELROOT%%

This will be replaced with whatever relroot path you defined in the config file (see that for more info).

%%TITLE%%

This will be replaced with the title of the current page, as derived from the <title> tag used in the output.

%%STYLESHEET%%

You can define extra stylesheets in .ptml files, but ONLY if they are externally linked and referenced in the following manner: <link rel="stylesheet" href="/some/path/styles.css">.

%%TOPMENU%%

This is where the dynamically-constructed top menu will be placed. See working sites for examples.

%%SIDEMENU%%

Same as above, except on the side.

%%PAGELOC%%

This is only useful if you are setting up an apache error redirect page using ptml. %%PAGELOC%% will be replaced with whatever Apache passed as the redirected page value.

%%UPDATED%%

This will be replaced with the file modification time of the ptml file currently being viewed.

It is also worth noting that all these template parameters are available for use inside the ptml files as well, not just the include files.