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.