(This is a work in progress. As I learn more I add it.)

A Manakin aspect contributes a self-contained set of features to some set of the pages generated by XMLUI. An aspect is embodied in a Cocoon pipeline. Its implementation consists of a sitemap, and zero or more classes to implement unique components used in the sitemap. (It is possible that all of the components you need are already provided by Cocoon or Manakin. Some aspects, for example, require only XSL transforms, an an XSL transformer is already implemented for you.)

You need a working knowledge of Cocoon to fully understand or to create a Manakin aspect.

The Sitemap

This is a normal Cocoon sub-sitemap. List the aspect's pipelines and
the components that those pipelines use.

Component elements (

transformer

,

action

,

matcher

, etc) are grouped by
type. Each one gives a short name to a Java class which implements its function.

A pipeline expresses a sequence of actions carried out on the DRI
document being constructed. Conceptually, the document passes through
each action on its way to the end of the sitemap. Begin with a

generator

(which accepts the developing DRI document from an earlier
processing stage) and end with a

serializer

(which passes the document
to a later stage). Sandwiched between these are

match

es,

selector

s,

transformer

s,

action

s, and the like, which act on the content of the
document.

Typically a pipeline will need to choose whether it is interested in
processing this particular document, and perhaps how it should treat
the document based on its content. A variety of matchers are
available for this purpose. Common matches are "wildcard" (which
matches wildcard patterns against the application-specific portion of
the URL),

HandleTypeMatcher

(which tests handles as to whether they
represent communities, collections, items, bitstreams, etc.), and

HandleAuthorizedMatcher

(which tests the requesting user's
authorization for types of access to the object represented by a
handle). If none of your pipeline's components matches the current
document, the document should be serialized as-is.

Match operations can be nested to any reasonable depth.

Eventually you reach a point at which you have discovered what you
want to do to the document.

transform

stages apply transformers to
the document, to add to or alter some of its content. You may find
existing transformers that implement some of the operations you
require, but this is the most likely place for you to identify some of
your own code which augments or edits the document.

A start on a
list of the transformers provided by DSpace is available by browsing the
DSpace javadocs.
See the direct known subclasses of

AbstractDSpaceTransformer

.

You also have the use of the stock transformers provided by Cocoon – see
the Cocoon 2.1 documentation for details.

Writing a Transformer

A transformer is a subclass of

AbstractDSpaceTransformer

.
See the javadoc for

AbstractDSpaceTransformer

for the methods you can
override.

Augmenting the DRI document

In particular, you'll want to implement some of

addBody()

,

addOptions()

,

addPageMeta()

, and/or

addUserMeta()

. Each is passed an
object representing the appropriate segment of the DRI document so that
your code can make required additions to it. For example, to augment the body you would override addBody:

public void addBody(Body body) throws ...
{
  String foo = Bar.getFoo();

  body.addDivision("myDivision")
    .addPara("myStuff",null)
    .addContent(foo);
}

This would add a division named "myDivision" containing a paragraph named "myStuff", whose content is whatever was returned by

Bar.getFoo()

.

What elements you add is up to you. Keep in mind that you'll need to
organize the data so that your themes can easily pick them out for
placement in the final page.

Knowing what you're working with

The class

org.dspace.app.xmlui.utils.HandleUtil

is quite useful for discovering what sort of request you are fulfilling and what repository object is in focus.

DSpaceObject theObject = HandleUtil.obtainHandle(objectModel);
if (null != theObject)
{
  int objectType = theObject.getType();
  int objectId = theObject.getID();
}

If

obtainHandle

returns

null

then the current request does not refer to a specific repository object handle.

objectModel

is an attribute of

AbstractDSpaceTransformer

, filled in by its

setup

method, and thus available to you since you are extending that class. The type of a

DSpaceObject

should be one of the small integers defined in

org.dspace.core.Constants

(ITEM, COLLECTION, COMMUNITY, etc.).

Complete Examples

Emetsger__ExampleAspects

Additional Documentation

• Manakin Developer's Guide
• DRI Schema Reference