Data Assocation

Visualization of page search results in the preview

With data association functionality, it is possible to connect the ContentCreator preview to reports based upon data access plug-ins.

HTML blocks in the preview document which are found to be associated with entries currently shown in the report are highlighted by markers. An HTML block may be associated with several report entries, and the marker shown for that block indicates the number of associated report entries. Furthermore, clicking on a marker in the preview activates a special filter in the report, which may be used to accordingly limit the set of entries shown in the report.

Providing Data Association Functionality in a Data Access Plug-In

A data access plug-in component must implement several classes which handle various facets of data association.

Aspect DataAssociating

FirstSpirit Developer API interface: de.espirit.firstspirit.client.plugin.dataaccess.aspects.DataAssociating
Developer API Documentation: DataAssociating<T, A>

This aspect, provided by a data stream builder class, indicates to FirstSpirit that the data access plug-in is data association-aware.

The aspect interface is parameterized as follows:

• T refers to the data access plug-in's data object type.
• A refers to the data type of association objects.

public class MyDataAssociatingAspect implements DataAssociating<MyDataObject, PageRef> {

    private PageRef _association;

    @NotNull
    @Override
    public DataAssociationHandler.Type<? extends DataAssociationHandler<MyDataObject, PageRef>> getAssociationType() {
        // Use the TYPE constant defined in the data association handler object (see below) to advertise the namespace
        // this data access plug-in supports.
        return MyDataAssociationHandler.TYPE;
    }

    @Override
    public void setAssociation(@NotNull final PageRef association) {
        _association = association;
    }

    // Optionally, define a getter method for the association object ("_association") so that the data stream builder
    // object may access this object and pass it to the data stream object for filtering.
}

Data Association Handler

FirstSpirit Developer API interface: de.espirit.firstspirit.webedit.DataAssociationHandler
Developer API Documentation: DataAssociationHandler<T, A>

This handler object provides services that translate between an association object and a String identifier of one or more of the data access plug-in's data objects.

The interface is parameterized as follows:

• T refers to the data access plug-in's data object type.
• A refers to the data type of association objects.

The data association handler class must be referenced in a separate public component in a FirstSpirit Module's module.xml file.

public class MyDataAssociationHandler implements DataAssociationHandler<MyDataObject, PageRef> {

    // Make a Type object available as a constant and configure it to use the namespace named "myDataAssociation".
    public static final Type<PageRef> TYPE = new Type<PageRef>("myDataAssociation") {};

    private BaseContext _context;

    @Override
    public void setUp(@NotNull final BaseContext context) {
        _context = context;
    }

    @Override
    public void tearDown() {
    }

    @NotNull
    @Override
    public Type<PageRef> getType() {
        return TYPE;
    }

    @Nullable
    @Override
    public Set<PageRef> associate(@NotNull final MyDataObject object) {
        // Analyze the given MyDataObject object and identify if any page reference objects should be
        // considered to be associated with it.
    }

    @NotNull
    @Override
    public String getId(@NotNull PageRef association) {
        // Return a unique identifier for the association object (e.g. the page reference's UID). This identifier
        // may be used later by #getAssociation(String) to retrieve the page reference object.
    }

    @Nullable
    @Override
    public PageRef getAssociation(@NotNull final String identifier) {
        // Retrieve a PageRef object for the given "identifier", e.g. by using a StoreAgent.
    }
}

Preparing a FirstSpirit Template

In order to use data association, the function dataAssociation(...) may be used in HTML output channels in FirstSpirit templates.

The namespace identifier must match that provided by the DataAssociationHandler.Type object specified as a constant in the data association handler.

<div $CMS_VALUE(
    dataAssociation(
        {
            "myDataAssociation":#global.ref.uid
        }
    )
)$>
    DIV content...
</div>