In package com.eden.orchid.api.generators

@Extensible,
@Archetype(
    value=ConfigArchetype,
    key="allGenerators")
public abstract class OrchidGenerator extends Prioritized implements OptionsHolder

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.

Indexing 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.

Generation Phase

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'.

Fields

static int PRIORITY_INIT = 10000 final static

Typically used for Generators that produce pages that content pages depend on, like registering global assets.

static int PRIORITY_EARLY = 1000 final static

Typically used for Generators that produce content pages.

static int PRIORITY_DEFAULT = 100 final 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 = 10 final static

Typically used for Generators that produce assets or data files.

String key final
Field Annotations:
@Getter

OrchidContext context final

String layout
Field Annotations:
@Getter,
@Setter,
@Option,
@Description(
    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.")

boolean parallel
Field Annotations:
@Getter,
@Setter,
@Option,
@BooleanDefault(
    value=false),
@Description(
    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.")

Constructors

OrchidGenerator(OrchidContext context, String key, int priority) public
Constructor Annotations:
@Inject

Parameters:

Methods

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.

Parameters:
  • Stream pages

    the pages to render
List<E> getCollections() public

Get a list of the collections that are indexed by this Generator.