Start page / Plug-In Development / Universal Extensions / Input Components / SiteArchitect / Swing Gadget Aspects

Swing Gadget Aspects

Gadget aspects extend the functional abilities of an input component within SiteArchitect's user interface and interaction scheme.

For example, an input component may

implement the functionality of the aspect Editable to support SiteArchitect's edit mode handling,
implement the aspect DifferenceVisualizing to support highlighting of the input component's value in a comparison view if that value has changed between two store element revisions, or
provide the abilities to supply or accept data via drag-and-drop by implementing the aspects TransferSupplying or TransferHandling, respectively.

Providing Aspects

The aspect provisioning process differs depending on the Swing gadget class' implementation style:

Direct implementation of SwingGadget:
A method getAspect(...) must be implemented and provide an object which implements the requested aspect if available.
Extension of the abstract class AbstractValueHoldingSwingGadget:
The method getAspect(...) is already implemented in the abstract class and cannot be overridden. The abstract class provides a method addAspect(...) through which aspect implementations may be registered.

SiteArchitect occasionally calls the method getAspect(...) with various aspect types as a parameter to identify which input components support a given aspect. If the Swing gadget supports the requested aspect, the method should return an object which implements that aspect; otherwise, it should return null.

Gadget Implementations Using SwingGadget

The Swing gadget class must implement functionality to register aspects whose functionality should be made available in SiteArchitect and to return an appropriate aspect implementation object as requested.

In order to keep track of registered aspects, it is highly recommended that the class AspectMap, available in the FirstSpirit Developer API, be used, as it ensures safe aspect mapping.

In order to provide available aspects to SiteArchitect, the gadget base interface SwingGadget extends the interface Aspectable, which defines the method <T> T getAspect(AspectType<T> aspect). If the input component's Swing gadget is to support the aspect type given as a parameter, the method must return an object implementing the associated aspect.

For example, the following code sample defines a Swing gadget class named ExampleComponentSwingGadget which directly implements the aspect Editable and also supports the aspect ValueHolder, which is implemented by a separate class named ExampleComponentValueHolderAspect.

public ExampleComponentSwingGadget implements SwingGadget, Editable {

    private final AspectMap _aspects;

    public ExampleComponentSwingGadget() {
        // In this example, the SwingGadget implementation implements Editable directly.
        // Register a reference to this object itself for that aspect.
        _aspects.put(Editable.TYPE, this);
        
        // In this example, the aspect ValueHolder<T> is implemented by a separate class.
        // Instantiate and register an object of that type.
        _aspects.put(ValueHolder.TYPE, new ExampleComponentValueHolderAspect());
    }

    // Implement the method getAspect(...) of the interface Aspectable,
    // which SwingGadget extends.
    public <A> A getAspect(final AspectType<A> type) {
        // Return the object implementing the requested aspect, if one has been registered.
        // If no object registered for the aspect type is available, the map object will return
        // "null", and SiteArchitect will not attempt to use that aspect's functionality for
        // the input component.
        return _aspects.get(type);
    }

    // ...
}

Gadget Implementations Using AbstractValueHoldingSwingGadget

The abstract class AbstractValueHoldingSwingGadget already implements methods to safely map aspect objects and to provide them to SiteArchitect. A Swing gadget class which extends this abstract class simply needs to implement aspect interfaces by itself or instantiate an object of a separate type which implements a desired aspect and call the method addAspect(AspectType<A> type, A aspect) in order to register the aspect object of the given type.

Gadget Aspects by Category

Swing Gadget Aspects
Appearance
Aspect	Description	Methods / Notes
Labelable	Indicates that the input component supports display of a label in the form view.	String getLabel() provides the label text. Note: the aspect Editable extends the aspect interface Labelable; however, the Swing gadget class must register the aspect separately if Labelable should be supported.
SingleLineable	Indicates that the input component may be drawn in a single-line layout without a header bar. In a single-line layout, the optional label (see Labelable) will be drawn to the left of the input component's UI.	boolean isSingleLine() indicates if the input component should be presented in a single-line layout without header bar.
LabelHidable	In a single-line layout, this aspect indicates if the component's label should be hidden.	boolean isLabelHiding() determines if the component's label will be hidden (true) or shown (false). Note: this aspect only has effect if the Swing gadget class provides the aspects Labelable and SingleLineable, a label text is provided, and the component is set to be presented in a single-line layout.
Resizable	Provides means to increase or decrease the height of the input component's viewport in form views.	The aspect interface does not define methods. Note: the Swing components delivered by the Swing gadget class should be designed such that changes in the viewport's height are handled appropriately.
WidthFixable	Indicates that the input component's UI has a fixed width which should not be changed by SiteArchitect.	boolean isWidthFixed() specifies whether SiteArchitect should honor the component width set by the Swing gadget component (true) or may modify the component's width according to layout needs (false).
SeparateEditable	Indicates if the input component's Swing UI may be shown in an external window. This aspect is useful for input components that require large viewports to display its data and interaction affordances adequately.	The aspect interface does not define methods. Note: the Swing components delivered by the Swing gadget class should be designed to support varying window sizes.
Hideable	Indicates that the input component may be hidden.	boolean shallInitiallyBeShown() indicates whether the Swing gadget should initially be shown when a form view including this component is presented.
SwingFocusable	Enables a Swing gadget to suggest a suitable inner Swing component to focus on when the Swing gadget receives focus.	void acceptFocus(SwingFocusable.Handler handler) is called when the Swing gadget receives focus. The method's body should determine which inner Swing component should receive focus and submit that component to the handler object by calling handler.focusOn(focusableComponent). Note: as focus awarding may be situational, this method should not use Swing mechanisms directly, but always use the provided handler object.
DisplaySettingsAware	Allows an input component to react to display changes caused by language switching, e.g. replace label texts to observe the new display language.	void onDisplayLanguageChange() is called when the display language is changed (e.g. by switching from one language tab to another in a form view). Note: The current display language may be obtained using the SwingGadgetContext<E extends GomElement> object available to the Swing gadget factory class.
Editing and storing component values
Aspect	Description	Methods / Notes
Editable	Controls whether the input component is editable or not.	void setEditable(boolean editable) should set the input component's UI fields to editable (true) or not editable (false). Note: although the interface Editable extends the interface Labelable, a Swing gadget must treat the aspect Labelable separately in its getAspect(...) implementation if it is to support that aspect.
ValueHolder<T>	Enables storing the component's data using FirstSpirit's persistence functionality and retrieving such data for display in the component.	T getValue() returns the value currently set in the input component. This method is used to persist the component's value (e.g. when saving an element). void setValue(T value) configures the input component to show a stored value; should set the input component's fields to reflect the value provided as a parameter. boolean isEmpty() indicates if the input component is to be considered empty. Note: T must match the input component's value type.
ChangeManaging<T>	Allows an input component to manage changes to its component value, instructing SiteArchitect to let the component's aspect implementation handle change identification itself (instead of SiteArchitect functionality conducting a currentValue.equals(oldValue) comparison on persistence data) as well as setting and clearing the component's value.	boolean hasChanges() indicates if the gadget's value is to be considered "changed". void replaceValue(T value) replaces the gadget's value with the value provided as a parameter. void clearValue() clears the gadget's value. Note: implementation of this aspect is recommended for Swing components whose value type is so complex that repeated .equals() comparisons on the persistence data format would be expensive or which maintain internal change lists (e.g. undo/redo lists) which provide a means of change identification that is much less costly than value equality checks.
ValueLikening<T>	Allows likening of a Swing gadget's current value to another, given value, suppressing SiteArchitect's .equals() comparison on persistence data.	boolean likenTo(T value) indicates if the gadget's current value object and the value object provided as a parameter are alike. Note: this aspect is required for input components whose working data cannot be readily provided as an object of the component value type. For example, an input component that manages address data may not be able to produce a valid Address object (as its component value) until street, house number, postal code and city are available in the component. In this case, a .equals() check on Address objects might fail, and it is safer to implement custom value likening functionality that can handle incomplete data.
IntegrityValidating	Provides a means for the input component's code to validate the component's value before it is saved. This aspect's code may identify a list of problems with can be displayed to the user.	Set<? extends Problem> validateIntegrity() validates the data integrity of the gadget's current value.
Data Visualization
Aspect	Description	Methods / Notes
DifferenceVisualizing	Handles visualization of difference markers (e.g. sets background colors of text sequences which were changed, added, or deleted between two compared revision values of the input component) in the Swing gadget's user interface components. This aspect may be used in the version comparison dialog when two revisions of a store element are compared.	void visualizeDifferences(List<Difference> differences) causes the gadget to visualize the given differences in some manner within its Swing components. Note: requires implementation of the value engineer aspect DifferenceComputing<T> (see Value Engineer Aspects).
SequencesHighlightable	Highlights text sequences in the Swing gadget's user interface components.	boolean highlightSequences(String regExp) is called by FirstSpirit to cause highlighting of text sequences indicated by the provided regular expression.
Drag and drop
Aspect	Description	Methods / Notes
TransferSupplying	Enables a Swing gadget to supply transfer data for drag and drop operations.
TransferValidating	Allows a Swing gadget to check if the transfer data in an ongoing drag and drop operation contains any data that can be processed by the gadget. The gadget can then accept or reject the given drop data, marking the gadget as a valid or invalid drop target, respectively.
TransferHandling	This aspect enables a Swing gadget to receive transfer data of a drag and drop operation completed by a drop action on this gadget, allowing it to process that data.

Print version | Page start