Working With Store Elements

Client plug-ins that are present in the user interface of either SiteArchitect or ContentCreator usually operate within the context of one or more specific store elements. For example, SiteArchitect context menu items may be associated with a multitude of store elements, while button items in SiteArchitect's editorial toolbar receive information about the store element whose form is currently shown in the editorial pane. Report plug-ins are not associated with store elements.

All functionally relevant methods of user interface extension interfaces receive a context object through which the currently associated store element(s) may be retrieved. In order to gain access to and display store elements not associated directly with the plug-in instance (pending user permissions during run-time), the FirstSpirit APIs provide several agents that may be used to request store and store element objects as well as to display and retrieve additional information about them.

Accessing Contextual Store Elements

public String getLabel(@NotNull InlineEditContext context) {
    final IDProvider storeElement = context.getElement();
}

Accessing Other Store Elements

Preview Elements and User Interface Information (ContentCreator Only)

WebeditUiAgent webeditUiAgent = context.requireSpecialist(WebeditUiAgent.TYPE);

// Get the store element (a page reference or dataset) upon which the current preview is based.
IDProvider previewElement = webeditUiAgent.getPreviewElement();

// Get the project language currently shown in the preview
// (i.e. the language version of the page element referenced by the page reference).
Language previewLanguage = webeditUiAgent.getPreviewLanguage();

// Get the editorial language used to render element information in the ContentCreator user interface.
Language displayLanguage = webeditUiAgent.getDisplayLanguage();

Stores and Store Elements

In order to gain access to store and store elements by type or reference name, respectively, FirstSpirit offers two agents that aid in obtaining stores and store elements based on various criteria.

StoreAgent

The StoreAgent provides the root object of a specified store. This store object may represent the selected store in its current, working version (containing all edits, regardless of whether they have already been released or not) or limit store access to elements in their most recently released revision.

final StoreAgent storeAgent = context.requireSpecialist(StoreAgent.TYPE);

// Obtain Media Store in its current version, including unreleased changes.
final Store mediaStoreLive = storeAgent.getStore(Store.Type.MEDIASTORE);

// Obtain Media Store in its latest release version.
final Store mediaStoreReleased = storeAgent.getStore(Store.Type.MEDIASTORE, true);

StoreElementAgent

The StoreElementAgent provides access to individual store elements in programmatic form, based on specific criteria.

final StoreElementAgent storeElementAgent = context.requireSpecialist(StoreElementAgent.TYPE);

// Obtain the menu item "FirstSpirit" of a project
// (Site Store folder "FirstSpirit (Realisation)") in its latest revision, even if not released yet.
final IDProvider firstspiritPageRefFolder = storeElementAgent.loadStoreElement(
    "firstspirit",
    IDProvider.UidType.SITESTORE_FOLDER,
    false
);

Loading Site Store Elements

The class DisplayElementOperation that can be accessed by using the OperationAgent provides functionality to load Site Store elements in either the editorial pane (SiteArchitect) or the preview (ContentCreator).

In SiteArchitect, all store elements may be displayed.

In ContentCreator, store elements that may be displayed are limited to the following:

• Page reference
  The web page corresponding to the combination of page reference and page elements will be displayed if the page reference is linked to a Page Store element.
• Site Store folder
  ContentCreator identifies the correct page reference element, marked as a start page, to display in the preview. If necessary, child Site Store folders marked as start folders will be stepped into to determine the appropriate page reference.
• Dataset
  The preview loads the page reference that is configured as the preview page for the dataset's table template and displays a view of the dataset.

final StoreElementAgent storeElementAgent = context.requireSpecialist(StoreElementAgent.TYPE);

// Obtain the menu item "FirstSpirit" of a project
// (Site Store folder "FirstSpirit (Realisation)") in its latest revision, even if not released yet.
final IDProvider firstspiritPageRefFolder = storeElementAgent.loadStoreElement(
 "firstspirit",
 IDProvider.UidType.SITESTORE_FOLDER,
 false
);

final OperationAgent operationAgent = context.requireSpecialist(OperationAgent.TYPE);
final DisplayElementOperation displayElementOperation = operationAgent.getOperation(DisplayElementOperation.TYPE);

// Display the web page corresponding to menu item "FirstSpirit" in the preview.
if (firstspiritPageRefFolder != null && firstspiritPageRefFolder instanceof PageRefFolder) {
 displayElementOperation.perform(firstspiritPageRefFolder);
}

Note that in ContentCreator, DisplayElementOperation provides different functionality from that available in SiteArchitect. While the operation type is able to display forms of all store element types in SiteArchitect, DisplayElementOperation in a ContentCreator context will intentionally allow only navigation to the current revision of a page reference, a page reference folder or a specific dataset (which will be displayed on the preview page selected in its table template) due to this client's different, preview-centered interaction design.

Loading Store Element Forms

Element Forms

The FirstSpirit Developer API provides a special operation, OpenElementDataFormOperation, which allows plug-in developers to display the form of a specific store element. In SiteArchitect, the form will be displayed in the editorial pane, while in ContentCreator, an Edit dialog will display the requested element form. All client-specific features of the form, including switching between project languages and performing validation, are available.

Special to this operation, plug-in logic must specify which project language should be displayed as the form is initially drawn, and contents of form fields may be overridden by providing a custom form data object. Loading and storing of the store element's form data is handled internally. As opposed to the standard Edit dialog functionality built into ContentCreator, this operation will, by default, draw a read-only dialog in that client; if editing functionality is desired, the operation must be configured accordingly.

This operation can only be used with store elements that are based upon a template that have a form definition (e.g. page and section elements in the Page Store).

OpenElementDataFormOperation supports the following configuration options:

• Project Language (required)
  determines which project language should be shown initially as the store element's form is displayed.
• Custom Form Data
  allows overriding some or all contents of input components in the store element's form.
• Edit Mode
  allows creation of an editable dialog that will handle saving modified form contents. Without explicitly setting edit mode, the form will be shown in a read-only fashion, and only a "Close" button will be offered.

Within an interactive client plug-in, an OpenElementDataFormOperation object may be acquired by using the context object's methods:

final OpenElementDataFormOperation editDialog = context.requireSpecialist(OpenElementDataFormDialogOperation.TYPE);
editDialog.perform(context.getElement());

Metadata Dialogs

The operation OpenElementMetaFormOperation may be used to display the specialized metadata form for a specific store element. This operation object may be acquired using the same procedure as described for OpenElementDataFormOperation.

In order to use OpenElementMetaFormOperation with a particular store element type (e.g. a Page Store section or a Site Store page reference) in the ContentCreator, a named metadata entry for that store element type must be defined in the project's ContentCreator settings of ServerManager.

Loading Store Elements in the Preview / Refreshing the Current Preview

FirstSpirit also provides a PreviewOperation, obtainable via the OperationAgent in both ContentCreator and SiteArchitect client session contexts, that supports loading a given store element in the preview. In general, supported elements are

• page references (type PageRef) and
• store elements that are viewable in the preview by way of page references, such as
  • pages (type Page) that are referenced by at least one page reference in the project and sections (type Section) of such pages, as well as
  • datasets (type Dataset) based on a table template that is configured with a “preview page”.

If the PreviewOperation is configured to load an element that cannot be displayed in the preview, such as a medium, the method #setElement(IDProvider) will throw an exception. In that case, the method #perform() will act as if no store element were explicitly set for the operation, thereby causing a refresh of the current preview (see below).

Example: Load a specific store element in the preview (Beanshell)

import de.espirit.firstspirit.agency.OperationAgent;
import de.espirit.firstspirit.ui.operations.PreviewOperation;
import de.espirit.firstspirit.agency.StoreAgent;
import de.espirit.firstspirit.access.store.Store;

// Error handling (try/catch and null checks) omitted in most cases.

// Obtain OperationAgent and PreviewOperation objects.
operationAgent = context.requireSpecialist(OperationAgent.TYPE);
previewOperation = operationAgent.getOperation(PreviewOperation.TYPE);

// Obtain StoreAgent object and a store element object.
storeAgent = context.requireSpecialist(StoreAgent.TYPE);
siteStore = storeAgent.getStore(Store.Type.SITESTORE);
// Note: Use a long ID that actually exists in the current project.
storeElement = siteStore.getStoreElement(11235);

// Configure the preview operation with the obtained store element and perform.
// Use try/catch to handle accidental configuration with a store element
// which cannot be displayed in the preview.
try {
    previewOperation.setElement(storeElement);
    previewOperation.perform();
} catch (Exception e) {
    // Handle the exception, e.g. notify the user via a RequestOperation.
}

As a special case, the PreviewOperation supports refreshing the current preview. This is achieved by performing the operation without specifying a store element.

Example: Refresh the current preview (Beanshell)

import de.espirit.firstspirit.agency.OperationAgent;
import de.espirit.firstspirit.ui.operations.PreviewOperation;

// Error handling (try/catch and null checks) omitted.

// Obtain OperationAgent and PreviewOperation objects.
operationAgent = context.requireSpecialist(OperationAgent.TYPE);
previewOperation = operationAgent.getOperation(PreviewOperation.TYPE);

// Don't explicitly set an element, just perform the operation.
previewOperation.perform();

Requesting Client URLs (Deep Linking)

FirstSpirit provides an agent that allows queries for deep-link URLs. These URLs can be configured to start either ContentCreator or SiteArchitect, load a specific project and display a store element in the preview and (specific to SiteArchitect) the form view. A deep-link URL may be shared or used as an "Edit" link in the generated version of a project's web pages; if necessary, FirstSpirit will require authentication with appropriate credentials before starting the client.

Client URL Builders

The ClientUrlAgent provides two specific URL builder objects, one geared towards obtaining SiteArchitect deep-link URLs, the other specific to obtaining ContentCreator deep-link URLs. Both URL builders allow the specification of a project, a store element, a project language and a user interface locale.

ContentCreator-Specific Limitations

Because of ContentCreator's composite preview paradigm, the ContentCreator URL builder should be used only to create addresses pointing towards page references, site store folders and datasets. Any other use of the ContentCreator URL builder is not supported.

SiteArchitect-Specific Options

The SiteArchitect URL builder also allows the specification of a connection type (HTTP or UNIX socket) in order to determine the communication methodology between SiteArchitect and FirstSpirit server.

Creating Client URLs

Specific to the ContentCreator, the following example code will build a ContentCreator deep-link URL that will cause the client to load the page reference currently displayed in the preview, using the same project language as well as the same user interface language that are active at the time this code is run:

final IDProvider storeElement = context.requireSpecialist(WebeditUiAgent.TYPE).getPreviewElement();

if (storeElement instanceof PageRef || storeElement instanceof SiteStoreFolder) {

    final Project project = storeElement.getProject();

    final Language previewLanguage = context.requireSpecialist(WebeditUiAgent.TYPE).getPreviewLanguage();
    final Language displayLanguage = context.requireSpecialist(WebeditUiAgent.TYPE).getDisplayLanguage();

    final ClientUrlAgent clientUrlAgent = context.requireSpecialist(ClientUrlAgent.TYPE);
    final ClientUrlAgent.WebeditUrlBuilder webeditUrlBuilder = clientUrlAgent.getBuilder(ClientUrlAgent.ClientType.WEBEDIT);

    webeditUrlBuilder.project(project);
    webeditUrlBuilder.element(storeElement);
    webeditUrlBuilder.language(previewLanguage);
    webeditUrlBuilder.locale(displayLanguage.getLocale());

    context.logInfo("Element URL: " + webeditUrlBuilder.createUrl());

}

Obtaining Store Element Icons (SiteArchitect only)

The UIAgent provides a method that will return a store icon for a given store element (IDProvider). The icon will be provided in the form of an ImageIcon object.

This ImageIcon object may be used to specify icons in SiteArchitect client plug-ins as well as SiteArchitect implementations of report plug-ins.