Standard Plugins » Web Publisher » Interface

Interface

Context

There are a few functions that can be used on the context object.

function setPagePartOptions(pagePartName, options)

Set the page part options for the given pagePartName, this can also be set on the publication if the options are more general and don’t require information from the context. The same page part can also be provided with different options using this function alongside aliases.

Arguments:

pagePartName	The API code style name of the page part
options	The options to be passed to the pagePart deferred render property function

function publishedObjectUrl(object)

Returns the Url for the given object’s publication page, formatted with the hostname as a full hyperlink, e.g. https://example.org/item/88888/example-item

function publishedObjectUrlPath(object)

Returns the Url for the given object’s publication page, formatted as just the path elements after the hostname, e.g. /item/88888/example-item

Features

function feature(name, feature)

A web publication feature is a function(publication, spec) that can be used between publications for some shared/common code to prevent duplication, essentially the same as Features however these are defined exclusively for web publications and contain a reference to the publication to enable declaration of handlers and other publication interface methods.

Arguments:

name	API code style name of the feature
feature	function(publication, spec) to define the feature

Example usage:

P.webPublication.feature("example:publication:common:feature", function(publication, spec) {
    publication.pagePart({
        //Page part definition
    });
});

These can be used throughout different publications, it should be noted that any publication using a feature will use everything inside of that feature including any request handlers and page parts.

function featureImplemented(name)

Utility function to determine whether a feature is available for use in the current publication. Returns true if the given feature name is implemented.

Arguments:

name	The API code style name of the feature

function use(name, spec)

Adds the given feature name to the publication, optionally passing it spec.

Arguments:

name	The API code style name of the feature
spec	An object of arguments to pass to the feature, can be anything to influence in the functionality of the feature

Publication

function setPagePartOptions(pagePartName, options)

Used to pass options to the page parts of a publication, can also be set on a per-request basis in context.

function urlPolicyForTypes(types, policy)

Sets the url policy for the given types.

Arguments:

types	The types to apply the policy to, e.g. [T.Book, T.Project]
policy	An object with property slugLength which decides the length of the last path element to display as the path

Publication.urlPolicyForTypes(T.Book, {
    slugLength: 0
});

function urlForFileDownload(fileOrIdentifier, options)

Returns the url to download the file through this publication. This handler will return the download URL for the file. Plugins are expected to check whether the requesting user has permission to access the URL.

The options object can have properties:

transform

The transform to be applied to the file

function respondToExactPath(path, handlerFunction)

Creates a request handlers similar to a GET Request but doesn’t allow for extra parameters in the same way. If further data is required to be sent via the url respondToDirectory should be used instead.

Arguments:

path	The path to respond to
handlerFunction	The response to the request and should be a function of the form function(E, context) where context is an object with details about the publication in its current state

Example usage:

publication.respondToExactPath("/example",
    function(E, context) {

        //Usual request handling code

        E.render(view, "example");
    }
);

function respondToExactPathAllowingPOST(path, handlerFunction)

Exactly the same as respondToExactPath however the path also accepts POST requests.

Example usage:

publication.respondToExactPathAllowingPOST("/example",
    function(E, context) {

        //Usual request handling code
        if(E.request.method === "POST") {
            //Some data changing actions
        }
        E.render(view, "example");
    }
);

function respondToDirectory(path, handlerFunction)

Similar to respondToExactPath however this creates a request handler that responds to all requests to a given directory beyond the hostname, for example path /item would pick up all requests to a path beyond that such as /item/category, further path elements can be extracted using E.request.extraPathElements property.

Example usage:

Publication.respondToDirectory("/researchers",
    function(E, context) {
        let letter = (E.request.extraPathElements[0] || "A").toUpperCase();
        if(letter.length != 1) { letter = 'A'; }
        let results = //get all researchers whose name begins with letter
        E.render({results: results});
    }
);

function respondToDirectoryAllowingPOST(path, handlerFunction)

Exactly the same as respondToDirectory however the path also accepts POST requests.

function respondWithObject(path, types, handlerFunction)

Similar to respondToExactPath however takes an additional types argument, which is used to determine the types of objects this handler will display.

Each path provided has an implicit assumption that the first argument beyond the path will be the Ref of the object to be displayed, if the object for that ref does not match any of types then the publisher will display a 404.

Publication.respondWithObject("/example-objects",
    [T.ExampleObject],
    function(E, context, object) {
        context.hint.objectKind = 'example-object';
        E.render({
            object: P.webPublication.widget.object(object)
        });
    }
);

For more on the object widget see Widgets.

function searchResultRendererForTypes(types, renderer)

Specifies how to display search results for items of a specific type. Useful for displaying additional information in results such as including key attribute values.

Arguments:

types	An array of types to use the renderer for e.g. T.Book
renderer	The handler function(object, context) to which should return a deferredRender for the given object

Example Usage:

publication.searchResultRendererForTypes(publication.DEFAULT, 
    function(object, context) {
        var template = context.publication.getReplaceableTemplate("hres:repo-publication-common:search-result:default");
        return template.deferredRender({object:object});
    }
);

For more information on replaceable templates see Rendering.

function objectValueRendererForTypes(types, renderer)

Set custom rendering of objects when they’re rendered as values by widgets.

renderer	Called as renderer(object, href, desc, publication)
	href may be undefined if the object doesn’t have a page in this publication
	desc may be an alias

Useful for altering values into context appropriate links, e.g. rendering copyright licenses as links to their terms & conditions.