Objecteditor

Object Editor #

This page contains the following content:

The ObjectEditor allows the viewing, editing, adding, deletion and filtering of Data Objects and object pools (see Data Objects). Alterations made to the pool or its objects can be written to the Java Data Object or the pool. Additionally, the object or pool can be exported to an XML file. Editing and viewing of the contained objects is facilitated by providing embedded access to the DataObjectEditor and the NESTWorkflowEditor.

⚠️ The editor creates a copy of the ObjectPool or DataObject provided as a parameter during instantiation and applies the modifications made by the user to this copy. To transfer the modifications to the original object, the Save to File action from the File menu has to be used.

Starting the Editor #

To open the editor, an instance of the class ObjectEditor needs to be created with the desired WriteableObjectPool or DataObject as a parameter. The given pool is deeply copied on editor instantiation so changes made with the editor are only applied to the copy at first. Invoking the Save to Object Action writes the changes to the original object.

The editor starts at a fixed size, but the size can be easily adjusted to suit the user’s needs. Additionally, users can activate full-screen mode for an even larger view of the editor. Regardless of the size of the editor, the elements of the user interface will adapt accordingly.

GUI Overview #

gui_overview

Object Tree #

The Object Tree provides a hierarchical view of the objects in the structure, allowing users to easily navigate and access each object and its attributes. Each object is represented by a node in the tree, which can be expanded to reveal its nested elements.

For AggregateObjects, the nested elements are the attributes of the object, which can be expanded to reveal their values. For NESTWorkflowObjects, the nested elements are the nodes and edges of the workflow, which can be expanded to reveal their properties.

The Object Tree supports arbitrarily nested objects, making it easy to navigate even the most complex object structures.

Additionally, the path display is updated when the selection in the pool view is changed. The elements of the path display can be clicked, which causes the selection of the pool view to be set to the corresponding node.

When a node in the tree is selected, the corresponding object is loaded in a suitable editor in the Embedded Editor area on the right. This allows for easy access and editing of each object and its attributes, without the need to navigate to a separate editor window.

Right Click Menu #

Right-clicking a node in the Object Tree opens a popup menu offering several actions (depending on the type of node that was clicked):

  • Add: Adds an object under the selected object into the structure. The data type corresponds with the selection in the tree controls. This makes it easy to create new objects and add them to the structure without needing to navigate to a separate editor window.
  • Delete: Deletes the currently selected object. This allows for easy removal of unwanted objects and streamlines the editing process.

Tree Controls #

This small control section provides functionality to add and delete objects from the Object Tree. To add an object, select a type from the Drop-Down-List and press Add. To delete an object, select it with the cursor and press Delete.

Configuring Labels #

The representation of aggregate object nodes in the tree view can be configured in the composition.xml file in the cake.utils.objecteditor.LabelProviderFactory factory section. The editor uses the implementation class cake.utils.objecteditor.ObjectEditorLabelProvider for generating labels for the tree view nodes that represent an aggregate object. Parameters can be defined to specify which attribute values of an aggregate of a specific class should be incorporated into the label. Multiple attributes for labels are supported by separating them by a comma in the parameter value.

Example:

composition.xml

    <Factory name="label_provider" class="de.uni_trier.wi2.procake.gui.objecteditor.label.LabelProviderFactory">
        <Implementation class="de.uni_trier.wi2.procake.gui.objecteditor.label.AtomicObjectLabelProvider"/>
        <Implementation class="de.uni_trier.wi2.procake.gui.objecteditor.label.NESTGraphItemObjectLabelProvider"/>
        <Implementation class="de.uni_trier.wi2.procake.gui.objecteditor.label.AggregateObjectLabelProvider"/>

        <Implementation class="de.uni_trier.wi2.procake.gui.objecteditor.label.AggregateObjectLabelProvider">
            <Parameter name="dataClassName" value="Cars"/>
            <Parameter name="multiLabelDelimiter" value="newline"/>
            <Parameter name="displayAttributes" value="manufacturer,make,year"/>
            <Parameter name="displayAttributeName" value="false"/>
        </Implementation>
        <Implementation class="de.uni_trier.wi2.procake.gui.objecteditor.label.AggregateObjectLabelProvider">
            <Parameter name="dataClassName" value="AmountType"/>
            <Parameter name="multiLabelDelimiter" value="newline"/>
            <Parameter name="displayAttributes" value="value,unit"/>
            <Parameter name="displayAttributeName" value="false"/>
        </Implementation>
    </Factory>
This causes the editor to look for the attributes named manufacturer, make and year whenever it encounters an aggregate object of the type Cars.

When these options to customize the editor labels do not suffice (e.g. when the pool consists of NESTWorkflowObjects instead of AggregateObjects), the ObjectEditor class offers the possibility to overwrite the getLabel methods responsible for label generation and to provide a custom implementation.

Example:

Wiki_ObjectEditorTest.java

    new ObjectEditor<>(pool) {
      @Override
      protected String getLabel(NESTWorkflowObject nestWorkflowObject) {
        return nestWorkflowObject.getWorkflowNode().getSemanticDescriptorStringValue("source");
      }
    };

This extracts the attribute named source from the semantic descriptor of the workflow node of the NESTWorkflowObjects in the pool to display as the label of the tree nodes. The getLabel method exists for the following parameter types:

  • AtomicObject
  • AggregateObject
  • NESTWorkflowObject
  • NESTGraphObject
  • Map.Entry (Attribute name and value)
  • CollectionObject
  • NESTEdgeObject
  • NESTNodeObject
  • ReadableObjectPool
  • DataObject

Embedded Editor #

In this section, the respective editor for the selected object from the Object Tree is displayed. Users have a choice between the DataObjectEditor and the NESTWorkflowEditor, both of which can be used in the usual way.

In addition to the standard editing options, further options are provided on the Embedded Editor Options toolbar. These options include the to access additional editing functions and options.

Changes made in the Embedded Editor are automatically saved when another object is selected in the Object Tree, or when the respective save function of the current editor is executed. This ensures that changes are not lost and that the editing process is streamlined.

⚠️ The embedded editors manage their own copy of the provided objects. When saved, the changes appear in the Object Tree. To save changes to the original object, which was specified in the parameters during initialization, File -> Save to Object must be executed. Further information can be found in Persisting Changes

Embedded Editor Options #

This toolbar provides options for the respective editor. It is possible to trigger specific actions through the corresponding buttons.

The top section of the editor illustrates the ongoing navigation route and offers the ability to backtrack by clicking on individual components of the path.

Filtering the Pool #

The section below the breadcrumb provides filtering of pool items using a filter expression. The filter input must contain strings that contain words within a searched path. Pressing Enter or clicking the Filter button after entering a filter expression will check the expression against each possible deep path of the pool and hide it from the pool view if it evaluates to false. The first possible path is always displayed. Press Back' or Next’/‘Enter’ to navigate through all other filtered paths. To remove filtering, clear the filter input and press Enter / click on Filter.

Filtering supports expressions containing the object IDs or their labels. Multiple values can be added using the AND operator & to build expressions, e.g: W01 & data_1(customdatanode) & name = bagel.

Editor Actions #

Multiple Editor Instances #

It is possible to open additional editor instances via the View -> Open new editor window menu option, which are initialized with the pool object of the parent editor. This allows users to work on multiple elements of the object simultaneously, and to compare and contrast different elements by arranging the editor windows side by side.

Persisting Changes #

Changes made to the object or its elements can be persisted by executing File -> Save to Object or File -> Export to File.

  • Save to Object: Writes the changes to the object the editor was initially instanced with.
  • Export to File: Serializes the object to XML and prompts for a file the XML should be written to.

By providing both save and export options, users can choose to persist changes directly to the object, or to export the changes as an XML file for use in other applications or contexts. This allows for greater flexibility and control over how changes to the object are managed and utilized.

❗ Although the embedded editor automatically saves changes as a new object is chosen, or are saved manually in the embedded editor, they are not immediately persisted to the original object. In order to persist the changes, users must execute one of the saving functions mentioned above.

Loading Objects #

Via the File -> Open File option, a previously saved XML can be opened and the object can be manipulated again.

Revert Changes #

As long as changes are not saved to the object by executing File -> Save to Object, they can be reverted by the option File -> Load from Object.

NEST Graph Editor #

The object editor provides an embedded editor for visualizing and editing NESTGraphs and NESTWorkflows. The graphical representation can be exported in the SVG or PDF file format. Additionally, an editor for modifying DataObjects attached to NESTGraphItems as semantic descriptions is provided.

GUI Overview #

gui-overview

Inserting Nodes #

New nodes can be inserted into a NESTWorkflow by drag and drop of the desired node from the palette into the canvas area. Another way to insert new nodes is by copy and paste of an existing node. This can be achieved by clicking the copy and paste buttons in the toolbar or by using the standard keyboard shortcuts CTRL-C and CTRL-V while a node is selected. Drag and drop with the left mouse button while holding CTRL also copies a node. The copy of the node gets an own ID and a copy of the semantic description of the original node.

Inserting Edges #

Nodes can be connected with an edge by drag and drop from the source node to the target node with the right mouse button. The editor only allows edge creation between compatible node types and automatically creates edges of the correct type.

Sequence nodes can be dropped upon control flow edges resulting in a “split” of the respective edge and the insertion of the new node into the control flow at that position: The post of the existing edge is set to the new node and a new edge is created linking from the new node to the post of the original edge. The new edge receives a copy of the semantic descriptor of the original edge. Edge splitting works for either existing task nodes (note that any existing controlflow edges connected to that task node will be deleted) or new sequence nodes from the palette.

Editor Controls #

An explanation for each setting/section of the editor controls panel in the left sidebar follows.

Node Visibility #

Here can be chosen which types of nodes should be shown in the canvas area.

Layout Configuration #

Changing any of these parameters will cause a re-layout of the workflow graph with the updated parameters.

  • Orthogonal dataflow edge routing: Routes dataflow edges orthogonally around nodes and keeps the edges from overlapping. Disabling this option causes dataflow edges to be drawn in a straight line without bends from their source to their target nodes which may cause them to intersect with nodes on their way or to be drawn nearly overlapping with other edges.
    • Edge to edge spacing: Spacing in PX between parallel sections of dataflow edges. This is an ideal value that may not always be respected due to restricted space circumstances.
    • Edge to node spacing: Distance in PX for dataflow edges to keep from other nodes.
  • Place data nodes vertically close to their task nodes: Disabling this option places all data nodes in a single dedicated layer below the controlflow nodes.
    • Additionally place above task nodes: Available to additionally use a layer above the task nodes to place data nodes in. The data nodes are distributed in two layers above and below each sequence while minimizing dataflow edge crossings. Note: This setting currently uses a computationally expensive implementation, so be advised to disable this setting if the layouting is too slow.
  • Vertical spacing for nodes: How much vertical space (in PX) should be left between nodes.
  • Horizontal spacing for sequence nodes: How much horizontal space (in PX) should be left between sequence nodes (task nodes / controlflow nodes). Values lower than Controlflow edge label margin are ignored.
  • Controlflow edge label margin: Defines how much space is left in sum in front and behind controlflow edge labels before a sequence node placement occurs. This setting is applied even when the controlflow edge label is empty.
  • Re-layout on edge insertion: Defines whether the layout should be applied whenever a connection between nodes is created.

Cell Labels #

Here the visibility of edge labels can be toggled and whether to prepend the NESTGraphItem ID to the labels.

Misc #

Toggle tooltips for hovering nodes and edges. The NESTGraphItems ID and type in addition to a tabular representation of the semantic descriptor is shown.

tooltip_example

By triggering Refresh NESTWorkflow, the graphical representation of the underlying NESTWorkflow is re-drawn to account for external changes made to the NESTWorkflowObject.

In this section, you can also invoke the NESTWorkflowValidator. It offers several validity checks for the NESTWorkflow and shows a list of detailed error messages when a check fails.

Pressing the Reset NESTWorkflow button resets the state of the currently displayed NESTWorkflow to the state it had on the last save or when no save took place to the state it had on editor instantiation.

Editing Semantic Descriptors #

The semantic description of nodes and edges can be edited by double clicking the node or edge, which causes a SemanticDescriptorEditor window to show:

data_object_editor_example

The dropdown at the top enables you to change the semantic descriptor class. Changing the class causes a new object of the corresponding class to be instantiated and set as the semantic descriptor. To set the semantic descriptor to null, select null from the dropdown (first entry). Clicking Reset changes reverts the semantic descriptor to the state it had when the SemanticDescriptorEditor was opened.

Ordered collections (ListObject) are supported, drag and drop the index label of an element of the collection onto another index label of an element of the collection to move the dragged element in front of the element it was dropped on.

Clicking the x button next to the name of an attribute sets this attribute to null. Attributes with null values can be filled by clicking the + button. A new object of the class defined in the model is created and then can be modified. When multiple classes are possible as the attribute value, a popup with a searchable dropdown menu is presented from which the desired class can be selected.

Configuring Labels #

Attribute names of semantic descriptors to be used as labels for nodes and edges can be set in the composition.xml file for the LabelProviderFactory factory. The editor uses several providers for label generation. Parameters can be defined to specify how a label should be generated (i.e., what information should be incorporated into the label) for a specific data class present in the semantic descriptor of a NESTWorkflowItemObject . Multiple attributes for labels are supported by separating them by a comma in the parameter value.

Example:

composition.xml

    <Factory name="label_provider" class="de.uni_trier.wi2.procake.gui.objecteditor.label.LabelProviderFactory">
        <Implementation class="de.uni_trier.wi2.procake.gui.objecteditor.label.NESTGraphItemObjectLabelProvider"/>
        <Implementation class="de.uni_trier.wi2.procake.gui.objecteditor.label.AtomicObjectLabelProvider"/>
        <Implementation class="de.uni_trier.wi2.procake.gui.objecteditor.label.AggregateObjectLabelProvider"/>

        <Implementation class="de.uni_trier.wi2.procake.gui.objecteditor.label.AggregateObjectLabelProvider">
            <Parameter name="dataClassName" value="WorkflowSemantic"/>
            <Parameter name="multiLabelDelimiter" value="newline"/>
            <Parameter name="displayAttributes" value="**all**"/>
            <Parameter name="displayAttributeName" value="false"/>
        </Implementation>
        <Implementation class="de.uni_trier.wi2.procake.gui.objecteditor.label.AggregateObjectLabelProvider">
            <Parameter name="dataClassName" value="TaskSemantic"/>
            <Parameter name="multiLabelDelimiter" value="newline"/>
            <Parameter name="displayAttributes" value="name"/>
            <Parameter name="displayAttributeName" value="false"/>
        </Implementation>
        <Implementation class="de.uni_trier.wi2.procake.gui.objecteditor.label.AggregateObjectLabelProvider">
            <Parameter name="dataClassName" value="DataSemantic"/>
            <Parameter name="multiLabelDelimiter" value="newline"/>
            <Parameter name="displayAttributes" value="name,amount"/>
            <Parameter name="displayAttributeName" value="false"/>
        </Implementation>
        <Implementation class="de.uni_trier.wi2.procake.gui.objecteditor.label.AggregateObjectLabelProvider">
            <Parameter name="dataClassName" value="AmountType"/>
            <Parameter name="multiLabelDelimiter" value="newline"/>
            <Parameter name="displayAttributes" value="value,unit"/>
            <Parameter name="displayAttributeName" value="false"/>
        </Implementation>
    </Factory>

The examples shows custom configuration of the AggregateObjectLabelProvider for specific data classes. For instance, let’s have a look at fifth configuration with the parameter dataClassName and the value DataSemantic. This causes the editor to look for the attributes name and amount whenever it encounters an aggregate of type DataSemantic and use their values for the generation of labels. Analogously, in the next configuration, the attributes named value and unit will be incorporated into the label when an aggregate of the type AmountType or sub types derived from it are present in the semantic descriptor. It is possible to output the complete semantic descriptor in tabular form (including attribute names) by providing the special keyword **all** as the parameter value of displayAttributes.

How multiple label values are separated in the label can be controlled via the multiLabelDelimiter parameter. newline is a special keyword that inserts a new line (\n) after each label, regular chars or char sequences like “,” or " " or " - " are also possible. The displayAttributeName can be set to true to prefix attribute values with their names.

It is also possible to use property values for labels. For this purpose a parameter displayProperties can be used analogous to displayAttributes.

For a more dynamic and fine-grained label configuration during runtime the Set as label option in the SemanticDescriptorEditor can be used:

label_menu

Double click a node or edge to open the SemanticDescriptorEditor. Now choose an arbitrary attribute, right click its name label and select Set as label from the popup menu. This causes the selected attribute value to be used as the label for every graph item with the same semantic descriptor class it was chosen from.

label_selection_menu

Furthermore, it is possible to fully display the semantic description of selected elements in a tabular form. Right click the selection, choose Label from the popup menu, and then choose whether to show null attributes (FULL_SEMANTIC_DESCRIPTOR_EXCLUDE_NULL) or not (FULL_SEMANTIC_DESCRIPTOR). To revert, select NORMAL in the aforementioned menu.

Export/Import Capabilities #

Saving the changes made to the workflow graph is possible via the Save and Export as actions in the toolbar or the File menu.

The Save action transfers the modifications made to the workflow graph to the NESTWorkflowObject which was given during the instantiation of the editor.

Export as offers to serialize the workflow graph to the chosen XML file or to export the visualization of the graph to an SVG document.

Customization applied to the layout of the workflow graph or the style of graph elements can be persisted to a file and later reloaded and re-applied via the File -> Export / Import graph layout and style options.

Displaying semantic descriptors in separate nodes #

It is possible to display the semantic descriptor of a node in a helper node connected to its corresponding NESTNode via an undirected edge. These nodes are “virtual”: they have no representation in the underlying NESTWorkflow data structure and only exist to aid the visualization of semantic descriptors for the SVG export. To create such nodes, select an arbitrary amount of nodes, right click them and choose Add semantic descriptor node from the popup menu.

For each selected NESTNode, a helper node containing the semantic descriptor is created and placed on top of its corresponding NESTNode. These helper nodes now can be moved arbitrarily to arrange them in a desired way. To help with positioning, a snap-enabled grid can be drawn in the background by clicking View->Grid->Show Grid and View->Grid->Line. The text content of the helper nodes can be freely modified in the text editor opening on double clicking the node.