In package com.eden.orchid.api.generators
since: v1.0.0 public abstract
Generators are what create the output pages within Orchid. Generators are run after all Options have been processed as part of a OrchidTask. When a OrchidTask is chosen that builds the output site, it happens in two phases: the indexing phase and the generation phase.
During the indexing phase, Generators should determine exactly the output pages they intend to generate, returning an index of those pages. This index should consist of a JSONArray or JSONObject, wrapped in a JSONElement. The content of either should be JSONObjects (either as a list or as a hierarchy) which contain at least the following properties:
- 'name' - the display name of the page
- 'url' - the url of the target page. This should be absolute using the set baseUrl OrchidOption, which is done automatically by OrchidReference
This JSONElement is then placed into the root JSONObject under the key specified by
getKey(). At generation time,
this index will be used to create deep-links throughout the site, typically through the page navigation or from
manually creating links, either through Javadoc 'see' or 'link' tags, or using an output filter in the main template.
It is important that no pages be written during the Indexing phase. The sites's index is not completed at this point, so it is likely that navigation among pages will not work as expected.
During the Generation phase, Generators can start to write their pages. Typically, this step involves picking a template for an OrchidPage and generating a page according to that template. This template should be provided by the Theme, but if the Theme did not implement the desired template, Orchid will attempt to find a suitable fallback.
It is also worth noting that templates can be provided by OrchidGenerator extensions apart from a Theme, and when using Pebble as the main template engine, can be injected into the site's content by extending one of the Theme's layouts, which should typically be 'templates/layouts/index.peb'.
static int PRIORITY_INIT = 10000final static
Typically used for Generators that produce pages that content pages depend on, like registering global assets.
static int PRIORITY_EARLY = 1000final static
Typically used for Generators that produce content pages.
static int PRIORITY_DEFAULT = 100final static
Typically used for Generators that produce pages based on data contained in content pages or just index content for use in components, menus, or collections.
static int PRIORITY_LATE = 10final static
Typically used for Generators that produce assets or data files.
value="Set the default layout to be used for all Pages from this Generator. Pages can specify their own layouts, which take precedence over the Generator layout.")
value="Improve site generation performance dramatically by rendering the pages from this Generator in parallel. There are currently thread-safety issues that may cause deadlocks, especially when in `serve` mode when build cycles may be executed multiple times. As such this feature should be considered highly experimental and used with caution.")
OrchidGenerator(OrchidContext context, String key, int priority)public
List<E> startIndexing()abstract public
A callback to build the index of content this OrchidGenerator intends to create.
void startGeneration(Stream<T> pages)abstract public
A callback to begin generating content. The index is fully built and should not be changed at this time. The list of pages returned by `startIndexing` is passed back in as an argument to the method.
the pages to render
Get a list of the collections that are indexed by this Generator.