Startseite / Plugin-Entwicklung / Entwicklung und Bereitstellung / Verwendung der FirstSpirit-APIs / Drag-and-Drop
Drag-and-Drop
The content on this page is specifically geared towards ContentCreator use of FS_BUTTONs, as drag-and-drop interaction with such buttons becomes more complex in preview situations. |
Drag-and-drop offers interactive data reference and transfer capabilities within the ContentCreator interface.
Using drag-and-drop, it is possible to transfer data from a custom report's results list onto an FS_BUTTON instance displayed in the preview. In this constellation, data is always transferred as a plain-text character sequence; ContentCreator plug-in developers may devise custom formats that will allow transfer data to be multi-faceted.
Providing Data for Drag-and-Drop
Custom Reports
Report plug-ins may define data transferable via drag-and-drop operations in their own implementation of TransferHandler, as described in Reports: Code Example: Transfer Handler.
A report's transfer handler class may register a number of data suppliers which provide data conforming to specific commodity types. For example, a report may register one supplier with a plain-text commodity type which holds string data as well as another supplier with a commodity type based on a custom data format which contains complex information (e.g. formatted text, image data, etc.). When a report entry object is dropped on an FS_BUTTON instance, for example, that button's drop handler script or executable may access either of these commodity types.
This enables report plug-in developers to provide drag-and-drop data in formats that are compatible with both input components common to FirstSpirit as well as custom input components and FS_BUTTON drop handler scripts and executables provided in FirstSpirit modules.
Drop Handling
The primary means of receiving inbound transfer data in drag-and-drop operations is an FS_BUTTON instance displayed in a ContentCreator preview page.
FS_BUTTON actions are implemented using native Java classes or Beanshell scripts. Both of these execution types gain access to the same context information:
Context Information | Object Type | Description | Access in Java Class (Type Executable) | Access in Beanshell Script |
---|---|---|---|---|
Button Context | allows access to agents and other FirstSpirit information | call | variable context | |
Button Properties | provides all properties (also called parameters) defined for this FS_BUTTON in the template form or output channel | call | variable properties | |
Context Element | provides the store element that is associated with a button instance (i.e., in whose template the FS_BUTTON is defined) | call | variable element | |
Context Element Language | indicates the project language of the form or preview the action was started in | call | variable language | |
Drop Indicator | indicates whether the current action handles a click (false) or a drop action (true) | call | variable drop | |
Drop Data | provides the object that was dropped onto the button instance; this object data will be obtained by requesting a specific content type | call | variable dropdata | |
A Beanshell Script Drop Handler
As shown in the table above, Beanshell scripts are set up with all available information items instantiated as variables.
In order to determine if a drop action has occurred, it is necessary to check the drop variable:
if (drop) {
In order to obtain a specific type of drop data, a TransferAgent object, which provides internal objects that indicate a transfer type and accompanying information, should be used:
TransferAgent transferAgent = context.requireSpecialist(TransferAgent.TYPE);
Now, the drop data in the desired flavor can be obtained:
String plainTextDropData = dropdata.get(transferAgent.getPlainTextType());
}
When used to handle drag-and-drop operations using custom report snippets as a data source, the transferred data will always be made available as a plain-text type (MIME type "text/plain"). The CommodityContainer method get() should be called with the TransferAgent method getPlainTextType() as a parameter. |
A Java Executable Drop Handler
Java classes intended to handle FS_BUTTON click and drop events must implement the interface Executable.
The method execute() receives a context object that is a simple map with a String key. All information items listed in the table above are obtainable using the method context.get().For example, in order to determine if the code is being executed due to a drop action, it is necessary to check the drop variable:
if ((Boolean) context.get("drop")) {
The CommodityContainer dropdata may be obtained likewise and can contain several different representations ("flavors") of the transferred object at the same time. For example, if a text segment with HTML formatting is dropped onto a button, both HTML and plain-text representations may be available and used depending on the code's needs.
In order to obtain a particular representation of drop data, it is necessary to obtain and use a TransferAgent object, which provides internal objects that indicate a transfer type and accompanying information.
BaseContext baseContext = (BaseContext) context.get("context");
TransferAgent transferAgent = baseContext.requireSpecialist(TransferAgent.TYPE);
Now, drop data can be handled using this transfer agent.
CommodityContainer dropData = (CommodityContainer) context.get("dropdata");
if (!dropData.get(transferAgent.getPlainTextType()).isEmpty()) {
baseContext.logInfo("Received drop data that has a String representation.");
} else if (!dropData.get(transferAgent.getExternalType()).isEmpty()) {
baseContext.logInfo("Received drop data from an external source (e.g. a file).");
} else if (!dropData.get(transferAgent.getMediaType(Picture.class)).isEmpty()) {
baseContext.logInfo("Received a FirstSpirit media element of type Picture.");
}
}