Overview

The priint:comet InDesign Desktop Preview panel can be used to show alternative content for placeholders or items selected in the Product panel.

A preview statement is provided for each Java method of a PubServer Plug-In deployed on the server and annotated as PluginMethod.MethodType.PREVIEW_STATEMENT. Preview methods must follow certain conventions regarding the method signature and return type.

This documentation shows how to implement preview statement methods.

Requirements

To implement preview statements, you need

If you installed a full devstack including Eclipse workspace and plug-in examples, a demo project for preview statements should already exist in your workspace called DemoPreviewStatements, if not, a copy of this project can also be found on the documentation site, see here.

HelloWorld

Step by step

To demonstrate the principle of implementing custom preview statements, we start with a simple step by step example.

  1. open an existing priint:publishing server plug-in library project or create a new plug-in library project
    If unsure, how to create or use a plug-in library project, please refer to the How to create a plug-in library guide.
  2. add an priint:publishing server plug-in class to this project, e.g. 
    package com.priint.pubserver.comet.previewstatement;

@Stateless(mappedName="com.priint.pubserver.comet.previewstatement.HelloWorld")
@LocalBean
@PubServerPlugin
public class HelloWorld extends PluginControlDefault {

}
  3. create a new priint:publishing server method like shown below: 
    @PubServerMethod(
    type=PluginMethod.MethodType.PREVIEW_STATEMENT,
    label="Weekdays",
    description="All weekdays in the specified locale")
@CometPreviewStatementProperties(selectionTarget=SelectionTarget.NONE)
public List<Preview> getLocalizedWeekdays(
    @PubServerMethodParameter String modelId,
    @PubServerMethodParameter Context context,
    @PubServerMethodParameter String entityId,
    @PubServerMethodParameter String recordId,
    @PubServerMethodParameter String recordGroupId,    
    @PubServerMethodParameter String entityClass,
    @PubServerMethodParameter String searchLocale,
    @PubServerMethodParameter String searchUnused) throws CometException {
  try {
    List<Preview> result = new ArrayList<>();

    String locale = searchLocale != null && !searchLocale.isEmpty() ? 
                          searchLocale : context.getLanguage();
    if (locale == null || locale.isEmpty()) {
        locale = "de";
    }
    DateFormatSymbols symbols = new DateFormatSymbols(new Locale(locale));
    String[] shortNames = symbols.getShortWeekdays();
    String[] longNames   = symbols.getWeekdays();

    for (int i = 1; i < shortNames.length; ++i) {
        TextPreview p = new TextPreview();
        p.setId(1);
        p.setId2(0);
        p.setId3(0);
        p.setStringId(shortNames[i]);
        p.setName(shortNames[i]);
        p.setDescription("The name of day #" + i + 
            " of week in locale '" + locale + "'");
        p.setText(longNames[i]);
        result.add(p);
    }
    return result;
  }
  finally {
  }
}
  4. export the plug-in library to an EJB jar file and deploy it on your PublishingServer
  5. login with InDesign Desktop and open the preview panel. You should now see a new find statement like shown in this screenshot:
  6. By selecting the entry "Weekdays" or clicking the search button, the weekdays are shown using the default locale or locale set as "searchValue1"

Conclusion

Preview statements / Java method details

Java preview statement methods must meet the following requirements:

Parameters

The method signature of Preview Statements isn't declared in a Java interface (as the method name is subject to the Plugin developer), but the parameter number and order must be exactly as follows:

All parameters must be annotated as @PubServerMethodParameter

The modelId parameter is set to the identifier of the entity model associated to the Comet project, the current session is connected to.

The context parameter is initialized according to the product panel configuration.

The entityId, recordId, recordGroupId and entityClass parameters are set from the calling environment, i.e.: selection in the InDesign document or Product panel (if applicable).

The two search... parameters are set to the values entered by the user in text input fileds 1 to 2. Empty fields will result in an empty String, the value will never be null.

Return Type

Return type must be java.util.List. The list elements must be either

In the first case, the standard data mapping (or the data mapping configured for this project) for previews is used to map the result to the appropriate type for the InDesign Desktop Preview panel, in the second case, you can control the mapping in the preview statement itself.

Preview Statements Decorations

You can use the @PubServerMethod respective @PubServerMethodParameter attributes to control certain aspects of the Preview panel UI

Statement Label

The statement label (as shown in the drop down menue for available preview statements) is set by the @PubServerMethod label attribute. 

@PubServerMethod(
    type=PluginMethod.MethodType.PREVIEW_STATEMENT,
    label="Get text alternatives"
    )
public List<Text> getTextAlternatives(
     @PubServerMethodParameter String modelId,
     @PubServerMethodParameter Context context,
     // ...

Search Field Labels

Search fields cannot be disabled, they are always visible and editable in the panel. If no label is defined for the search field parameters, default labels (e.g. Suchfeld 1) are shown.
By using the @PubServerMethodParameter name attribute, the label of search input fields can be defined: 

@PubServerMethod(
    type=PluginMethod.MethodType.PREVIEW_STATEMENT,
    label="Get text alternatives"
    )
public List<Text> getTextAlternatives(
     @PubServerMethodParameter String modelId,
     @PubServerMethodParameter Context context,
     // ...
     @PubServerMethodParameter(name="Locale") String locale,
     @PubServerMethodParameter(name="<0x200A>") String unused) 
    throws CometException { 
  // etc. ...

The second search field is not used for this preview statement. Since an empty string would result in the default value ("Search field 2"), we use the Unicode hairspace sign <0x200A> to make the label somewhat "hidden".

Note: the space for labels is very limited in the InDesign Preview panel, only about 7 to 10 characters can be shown. The full label is always shown in the tooltip, when the mouse pointer is moved over the label text field.

Preview Behaviour (@CometPreviewStatementProperties)

The @CometPreviewStatementProperties annotation allows to control the behaviour of a preview statement (in our first example you may already have noticed the @CometPreviewStatementProperties selectionTarget property).

The attributes applicable for the @CometPreviewStatementProperties annotation are described in the following.

selectionTarget

selectionTarget controls, whether the statement is dependent on the document, the product panel, both or no selection. Possible values are:

In the example above, we use selectionTarget=NONE, because we return a static list of weekdays (not dependent on any calling context). In this case, the entityId, recordId, recordGroupId and entityClass parameters are always empty (not null), no matter, if items in the document or product panel are selected or not.

needsSelection

Defines, whether this statement requires a selection or not. In case of selectionTarget=NONE, the attribute value has no effect.
Possible values:

useParent

Just like placeholders, preview statements can be configured to use the parent IDs (record, entity, group, class) rather than the ID of the record itself.
Possible values:

Result Properties (@CometPreviewResultProperties)

The @CometPreviewResultProperties annotation allows to control some of the basic result properties when using EntityData return types and standard mapping.

linkScriptLabel

The label of a CometPreviewLinkScript.

When using standard mappings for the results of a preview method call, the ID of this script is used for all result objects.
If a script with this label does not exist or isn't a CometPreviewLinkScript, an exception will be raised.

linkScriptId

ID of a CometPreviewLinkScript.

When using standard mapping for the results of a preview method call, the ID of this script is used for all result objects.

Note: if linkScriptLabel and linkScriptId are defined, the linkScriptLabel attribute takes precedence over the linkScriptId attribute.

priceProperty

The priceProperty attribute allows easy control, which property of a price entity is used for the result values.

Possible values are:

useMediaProxy

Use proxy for MediaAsset data.

If set to true, media preview and data will be requested from PubServer. This requires, that the media files are accessible from the server file system.
If set to false, media assets are accessed directly from InDesign and previews are calculated on the client. This requires, that the media files are accessible from the client file system.

Possible values:

Preview Processing Properties (@CometPreviewProcessingProperties)

The @CometPreviewProcessingProperties annotation allows deeper control, how result data is mapped and processed.

dataMappingPlugin

Mapped name of a Plugin to map results from a preview method call.

This value can only be set in combination with dataMappingMethod(). If defined, results from a preview method call will be mapped to com.priint.pubserver.comet.bridge.entitydata.Preview objects using this method rather than the standard mapping.
Mapping methods must match these requirements:

More values from the request context can be accessed by declaring [2..n] parameters and using one of the following defaultValues:

dataMappingMethod

Name of a method to map results of a preview method call.

This value can only be set in combination with dataMappingPlugin, see the dataMappingPlugin documentation for further information.

dataProcessingPlugin

Mapped name of a Plugin to post process results of a preview method call.

This value can only be set in combination with dataProcessingMethod. If defined, results from a preview method call will be passed to this method.
Processing methods must match the following requirements:

More values from the request context can be accessed by declaring [2..n] parameters and using one of the following defaultValues:

dataProcessingMethod

Name of a method to post process results of a preview method call.

This value can only be set in combination with dataProcessingPlugin, see the dataProcessingPlugin documentation for further information.

usePlaceholderDataProcessing

Use placeholder data processing for all results.

If set to true and the statement is run from a placeholder context, all result data is processed using the same instructions like this placeholder.

Possible values

Resources

Examples for preview statements for each EntityData type (Text, Price, MediaAsset etc.) including mixed results and results not bound to entities (like the HelloWorld example above) can be found in the DemoPreviewStatements project available on the documentation site.

Standard DataMapping methods for previews are implemented in the CometDataMapping Plugin and can be referred via the com.priint.pubserver.comet.bridge.datamapping.DataMappingToPreviewLocal interface defined in the PubServerSDK

The result types com.priint.pubserver.comet.bridge.entitydata.Preview and derived types com.priint.pubserver.comet.bridge.entitydata.TextPreview, com.priint.pubserver.comet.bridge.entitydata.ImagePreview and com.priint.pubserver.comet.bridge.entitydata.SnippetPreview are also defined in the PubServerSDK.