[Blue Header]

Pharser Admin Manual


What is Pharser?

Pharser 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.

Pharser 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 Pharser 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 pharser.

Pharser 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 pharser are the menu files. These are small files with entries which tell pharser such things as the title of the directory, and what things to link to whenever files in this directory are displayed in pharser. Whenever invoked, pharser 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 Pharser

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:

Placing files into sane locations

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

Designating an extension

By convention, ".ptml" is used for pharser-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 pharser 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/pharser.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 pharser at different config files by using SetEnv in apache. E.g. add the following to your mydomain.com virtual domain:
SetEnv PHARSER_CONFIG /etc/pharser/mydomain.conf

Pharser config file

Pharser 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:

[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 pharser 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 pharser 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, pharser 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 pharser 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 pharser-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 PHARSER_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 PHARSER_ATSYMBOL [at]" in their .htaccess file.

[tweaks]

There isn't much here at the moment. Pharser 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 pharser.inc and essentials.inc. To do that, run the following commands:

grep -v '_debug' pharser.inc > pharser.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, pharser will look for the config in /etc/pharser/pharser.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, pharser 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.