Forrest 1.0 is the first specification of Forrest (the product), intended to be the reference point for developers and users in the road to making a first stable Forrest release.
This section describes the status of this document at the time of its publication. Other documents may supersede this document.
This document is under development, and will not be considered final until Forrest 1.0 is released.
This is the First Public Working Draft of the Forrest 1.0 specification. This document has been produced by the Apache Forrest Project developer community as part of the Apache Forrest Project. The authors of this document are the Apache Forrest Project participants.
Publication as a Working Draft does not imply endorsement by the Apache Forrest Project Membership. This is a draft document and may be updated, replaced or obsoleted by other documents at any time. It is inappropriate to cite this document as other than work in progress.
Comments on this document are welcome. Please send issues to the public mailing list dev@forrest.apache.org (link to archive). It is appropriate to send discussion email to this address. Please note that comments that you make will be publicly archived and available, do not send information you would not want to see distributed, such as private data.
The specification has been written with various modes of presentation in mind. In case of a discrepancy, the online electronic version is considered the authoritative version of the document.
This document uses the terms must, must not, required, shall, shall not, recommended, should, should not, may, and optional in accord with [RFC 2119].
Chapters are arranged by topic.
Throughout this document, the following namespace prefixes and corresponding namespace identifiers are used:
xhtml2: The XHTML 2.0 namespace
my: Any user defined namespace
This is only a convention; any namespace prefix may be used in practice.
The following typographical conventions are used to present technical material in this document.
Examples are set off typographically:
Example: Example item
Example Item
References to external documents appear as follows: [Sample Reference] with links to the references section of this document.
The following typesetting convention is used for non-normative commentary:
Note:
A gentle explanation to readers.
|
Editorial note: Editorial Note Name |
|
|
Editorial commentary, not intended for final publication. |
|
Issue (sample-implementation-issue):
Issue-Name
A specific issue for which input from implementors is requested, for example as part of the Candidate Recommendation phase.
Resolution:
None recorded.
|
Editorial note: TODOs |
|
|
|
This is the conceptual processing pipeline offered by Forrest.
All references to actual source dirs and internal or external formats is generic and are specified elsewhere in this spec.
Forrest has a single conceptual source space, that can initially be thought of as a single directory, the current xdocs dir. Every file that is outside of this directory has to be resolved by a locationmap, so that Forrest sees it all as a single directory in any case.
This source space contains files that a filename and an extension. There should be only one file with a certain name in a certain directory, which will be the main source of our transformation.
For each URL that is requested, there shall be only one source file resolved, which will be our main source.
In the second step, Forrest transforms the main source to the intermediate format, which is XHTML2 (also automatic transforms from XHTML1 and HTML will be supported). Transformations from HTML and XHTML will be done in the core, while all others will be done by plugins (input plugins).
Multiple formats can be asked for the same source: the filename asked will be in the following manner.
name.type.format
Example:
myfile.content.html myfile.javadocs.html myfile.html
This is a new step, that adds navigation, metadata, extra content, functionality and transformations to the content stream.
The filtering stages should use different filtering files to not produce markup that is not needed by the view.
Navigation is the addition of the 'tab' and 'linkmap' information to the stream.
Metadata about a page can be added, like the date, page size, etc.
Nuggets of information can be added based on the URL and on the contents of the main source. For example, newsfeeds about the page being processed.
Fbits should be insert only as placeholder that the view can populate them with the actual functionality
Filtering on the main content can be done, like the automatic creation of links based on the site.xml linkmap or footnote processing.
These filtering steps are to be done by plugins (filtering plugins).
Based on the view specified, the content is transformed in a format that contains presentation information. Example formats are html, fo (formatting objects) and svg.
Note that this part adds functionality implementation to the content. For example, a search item can be displayed, or widgets can be used. These are fbits, or functionality bits, and are different from nuggets, which are extra content.
Note that fbits are view dependant, so that a view can decide to implement them or not. The configuration of these bits are to be done with the new generic skinconf format and a new templating language.
Example of current fbits are the search pane, the page format selector, etc.
This new templating language will be forrest:templates, which contains forrest:view and forrest:template.
The view is creating the html-skelleton that is used for theming. Themes are view dependend but e.g. you can write one theme for x view derivatives. Theming adds colors and general appearance info. In html it's css files for example, or the skinconf color information.
The presentation is transformed to the actual final format with output plugins. For example a fo presentation can be outputted as xhtml, pdf, rtf, doc, ps, etc.
Forrest:templates or short f:t is a templating language to create views on forrest input-data.
Definition - Forrest-View: View = content (nuggets) + functionality (fbit) + design (style)
We will refer to incoming content as nuggets. Nuggets are pure content (without any information about fct., style,...).
fbits can (but do not have to) use nuggets to implemend (or populate) the actual functionality needed in the requested view.
pure fbit (no content just functionality -> IMO very rare, the example tag would as well contain i18n: close-schliessen-cerrar) <forrest:fbit name="close-window"/>
pure fbit *using* nuggets (e.g. profiling data for the actual view.) <forrest:fbit name="searchbox" type="sport"/>
Normally the nuggets and fbits will be implemented in an overall design. The design is a container concept of storing fbits and nuggets in graphical container (template + hooks). Templates can be used to create the overall design in different media (xhtml, fo,...) of the document.
This design state should only use registered contracts for fbits and nuggets but still have absolute controll over the style.
To be added.
To be added.
This document was produced with the participation of current Apache Forrest Project members and of all participants to the public discussion.
Raw content is to be gotten like this:
for single files one can ask for myfile.source.extension
for whole dirs, the thing has to be declared in some sitewide metadata
To be discussed