path_handler.virtual

Description

This path handler uses paths in Webgen Page Format to create virtual nodes.

Virtual nodes act like normal nodes but don’t have any content and are therefore not written to their destination path. They normally refer to URLs which are not generated by webgen. By creating virtual nodes for such URLs, it is possible, for example, to include links to these external URLs in automatically generated menus.

Usage

The ‘content’ block of the path in Webgen Page Format, which needs to be a hash in YAML format, is used to define a mapping from path strings to meta information hashes.

The keys are interpreted as absolute or relative (to the directory containing the path) path names and the values need to be meta information hashes. Any meta information can be set on a virtual node.

The  dest_path meta information should be used to define the link destination for the virtual node. This usually means an absolute URL like http://example.com/link/target. If the dest_path meta information is not set, the path string is used for this purpose instead.

The order of the keys is important because, for example, a virtual directory can’t be created if another key already lead to the creation of a virtual directory.

Example

Here is an example for the possible content of a virtual path:

/documentation/:

/documentation/index.html:
  routed_title: Documentation

download_and_installation.html:
  in_menu: true
  sort_info: 25
  dest_path: index.html#download__installation

/documentation/api.html:
  title: API Reference
  dest_path: http://my.example.com/api

• The first entry specifies that a directory node /documentation/ should be created. The path handler virtual recognizes this because the given path ends with a slash.

• The second entry creates a node that acts as the directory index for the directory that was created. This would be done, for example, when the documentation directory is created by an external program.

• The third entry specifies a virtual node that should be in the menu and should have a certain sort information. When this virtual node is a routing target, the path given by the  dest_path meta information is returned.

• And the fourth entry specifies another virtual node the destination path of which is an URL pointing to http://my.example.com/api.