Back to the extension listing.

Webgen::SourceHandler::Virtual

Summary

This source handler operates on paths that match one of the following path patterns (see the path pattern documentation for more information): **/virtual, **/*.virtual

Description

This source handler uses files in Webgen Page Format which are used to specify virtual paths. Virtual paths don’t really exist as source paths but are useful nonetheless. For example, they allow to include links to external content in automatically generated menus. They are never written out since they define no real content!

The content block of the source path is used and its content needs to be a hash in YAML format. The keys are relative or absolute source paths names and the values meta information for them. Any meta information can be set on a virtual path but one meta information key is special: url. This meta information specifies, relative to the directory in which the source file is in, the output path for the virtual node. If no url meta information is specified, the source path itself is used as output path.

Following is a sample virtual source files with explanations afterwards:

\--- !omap
- /documentation/:

- /documentation/index.html:
    routed_title: Documentation

- download_and_installation.html:
    in_menu: true
    sort_info: 25
    url: index.html#download__installation

- /documentation/api.html:
    title: API Reference
    url: http://myhost.com/api

The example does not use a normal hash but an ordered YAML map. This ensures that the virtual nodes are created in the order they appear in the file.

The first entry specifies that a directory /documentation should be created. The virtual file handler recognizes this because the given path ends in a slash!. Then a virtual index file for the virtual directory is created. This would be done, for example, when the documentation directory is created by an external program.

The third entry specifies a virtual file that should in the menu and should have a certain sort information. When this virtual file is referenced, the path given by the url key is returned. This example shows how to make a single link to a fragment appear in automatically generated menus.

And the fourth entry specifies another virtual file whose output path is an URL pointing to http://myhost.com/api.

Back to the extension listing.