webgen logo

webgen / static website generator

static website generation made easy!

Latest news

2007-12-31: Minor release with feature enhancements. More...

2007-09-08: Small bug fix release. More...

2007-06-29: Some bug fixes and one small feature enhancement. More...

Links

Generated by webgen

General Information

Plugin name:File/PageHandler (File/DefaultHandler)
Author:Thomas Leitner <t_leitner@gmx.at>
Summary:Plugin for processing page files
Parameters:

defaultLangInFilenamefalse
If true, the output files for the default language will have the language in the file name like all other page files. If false, they wont.

outputNameStyle[:name, [".", :lang], ".html"]
Defines how the output name should be built. The correct name will be used for the :name part and the file language will be used for the :lang part. If defaultLangInFilename is true, the :lang part or the subarray in which the :lang part was defined, will be omitted.

validatornil
The validator for checking HTML files on their validness. Set to an empty string or nil to prevent checking.

Handled paths:**/*.page
Default Meta Information:
useERB: true
blocks: 
- - content
  - textile

Description

Page files are used to specify the actual content for the website. They contain the content for a web page and, optionally, meta information. For information about the format used for page files have a look at the WebPage Format reference. The default values for the content block name and format specifier have been overwritten by setting a default for the blocks meta information!

Conventions

Page file naming

The filename of a page file should be in the following format sothat meta information can be extracted correctly and that referencing a page file works correctly:

[orderInfo.]name[.lang].extension

  • orderInfo
This part is optional and has to consist purely of the digits 0 to 9. It’s value is used for the meta information orderInfo. If not specified, it defaults to the value zero.
  • lang
This part is optional and has to be an ISO-639-1/2 language identifier (two or three characters (a-z) long). If not specified, it is assumed that the page file is written in the default language set via Core/Configuration:lang.
  • extension
This has to be page for now.
  • name
This part is used on the one hand for the title meta information (but with these transformations: ‘_’ and ‘-’ become spaces). On the other hand, the standardized page and localized page names are derived from it. name must not contain any dots. Also: if two page files have the same name part, they should define the same content for different languages as webgen consideres them as “one” page file in two languages. If the name parts and the languages are the same, webgen can’t distinguish the two page files and raises an error.

Following are some examples of page file names:

FilenameParsed meta information
name.page title: Name, language: en, orderInfo: 0
name.de.page title: Name, language: de, orderInfo: 0
01.name_of-file.eo.page title: Name of file, language: de, orderInfo: 1

Notice: The first two examples define the same content for two different languages (en and de) as they have the same name part.

Output file naming

The output name of a page file can be customized using the outputNameStyle parameter (which can be overridden by setting the outputNameStyle meta information). This allows to change the output name so that, for example, Apache’s built in “select HTML file by language” magic can be utilized.

Standardized page names for referencing page files

As described above the name part of the page file filename is used for creating the standardized page name and the standardized localized page name as follows:

  • standardized page name: <name part>.page
  • standardized localized page name: <name part>.<language code>.page

When two page files have the same name part, they have a common standardized page name but different standardized localized page names. As the output name of a page file can be customized, it is not wise to reference a page file by its output file name. Use the standardized page names instead. Therefore if you reference a page file using the standardized page name, you will always get the page file in the current language. If you use the standardized localized page name, you will always get the page file in the specified language. So, all in all, you can reference a page file by (in order of preference): the standardized page name, the standardized local page name and the output name.

These conventions are best shown using examples:

FilenameStandardized page nameStandardized localized page name
hallo.page hallo.page hallo.en.page (if the default language is English)
the_others.de.page the_others.page the_others.de.page
12.documentation.eo.page documentation.page documentation.eo.page

How meta information is set

As meta information can be defined in page files, the following sections explains in more detail what is done in step 4 of the list from the section “Processing order” in Core/FileHandler:

  • Meta information from the filename
Meta information derived from the filename overrides the default meta information. This includes the meta information orderInfo, lang and title.
  • Meta information from the meta information section of the page file
All meta information from this part set previously set meta information, especially the meta information lang, orderInfo and title!

Fragment Nodes

As a page file specifies the content of web page, it normally has sections, subsections and so on (created by the h1h6 HTML tags). Nodes for these sections are created under the page file node sothat they can be used later by webgen plugins. However, there are certain restrictions:

  • Only sections of the block named ‘content’ (the default name for the main block) are added to the page file node
  • Only already existing sections WITH an id attribute are used. This means that sections without and id attribute and sections defined later via webgen tags or ERB are not used!

A plugin using these fragment nodes is MenuStyle/Section which displays an in-page content menu.