NAME

Newcomen::Formatter::RelativePaths - Reference other pages using relative paths.

DESCRIPTION

Formatter backends are usually not called directly. See Newcomen::Formatter for the frontend documentation.

This formatter backend uses the global URL map (see Newcomen::URL) to allow other pages to be referenced inside a piece of content by their relative paths. The format to be used in the source text can be configured freely, see below.

OPTIONS

{
   'formatter'        => {
      'relativepaths' => {
         'open'       => '{rel{',
         'close'      => '}}',
         'separator'  => ',',
         'use_cache'  => 1,
      },
   },
}

These are the default options set by this plugin. They may be overridden by user configuration.

formatter/relativepaths/open and formatter/relativepaths/close specify the opening and closing "tags" for the relative link. The string between these two will be split on the separator character (or string) specified by formatter/relativepaths/separator, and the resulting list will be passed to Newcomen::URL's get() method to retrieve the URL registered for the specified key. The URL (if any) will then be passed to the page's rel() method to convert it to a path relative to the current page. The whole string (including start and stop marker) will then be replaced by this relative path.

For example, the string '{rel{Static,static/styles/style.css}}' will result in this look-up in the URL map (if the default settings are used):

$path = $url -> get (['Static', 'static/styles/style.css']);

The resulting absolute $path will then be converted to the relative path. This example would actually work for a page with the source path static/styles/style.css (relative to the project root) created by the Newcomen::Plugin::Static plugin.

The keys in the URL map are defined by the plugins creating a page, see the appropriate plugin documentation for details. If no URL can be found for a specific key, the whole string will be replaced by an empty string (i.e. the whole string will be deleted from the text). Note that there is no special treatment of whitespace or empty elements, i.e. both whitespace and empty elements will be preserved for the URL look-up, which is usually not what you want.

formatter/relativepaths/use_cache may be set to enable or disable the caching of the formatter results. It is enabled by default. See below for details.

CACHING

Results of this backend may be cached by the formatter frontend. The formatting depends on the backend options, as well as on the page target. For effective caching the same options should be used for all pages. Since the formatting also depends on the page target, this formatter should be included in the formatter chain after formatters whose behaviour is only determined by their options. Note that the caching for this backend is still as effective as possible, by treating all pages with a target at the same directory level equally (e.g. relative paths will be the same for the two targets 'some/path/file_1.html' 'some/path/file_2.html', so if the same content is included on these two pages, the formatted text will be cached and reused).

Caching may be disabled for this backend (see above), it may also be disabled globally (see Newcomen::Formatter).

CLASS AND INSTANCE METHODS

See Newcomen::Formatter::Backend.

VERSION

This is version 2014052501.

AUTHOR

Stefan Goebel - newcomen {at} subtype {dot} de

COPYRIGHT AND LICENSE

This file is part of Newcomen.

Newcomen is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the license, or (at your option) any later version.

Newcomen is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with Newcomen. If not, see <http://www.gnu.org/licenses/>.

Newcomen

Index