Appboard/2.5/builder/widgets/diagrammer/tutorial

Overview

The Diagrammer Widget is a powerful tool that allows for the diagramming of nodes and links in custom layouts that are directly referencing data from adapters. The referenced data can be run through filters or rules that provide icons, status icons, colors, and labels. The Diagrammer Widget does not use Data Collections to display data. Instead, it accesses data directly from configured adapters. By accessing the data directly from the adapters the widget can ensure that it gets the exact reference to a row of data that is unaffected by client side sorting, filtering, or grouping.

The Diagrammer widget can only make use of Data Source entities that have a primary key(s) defined. This is because of the way the nodes and links must be uniquely identified for update purposes.

Now that we have an idea of what a Diagrammer Widget is and why we would use one, let's try to create and use one.

Exercise

Exercise Summary

In this tutorial the focus is on the Diagrammer widget, but overall we will need to setup some other pieces to get this going:

• Logging in to AppBoard as an administrator
• Setting up a Data Source
• Creating a Stack
• Adding a Diagrammer Widget

Log into AppBoard

The first step is to log into AppBoard as an administrator. If using a clean install on your local system then the default access and credentials are as follows:

• URL: http://localhost:8080
• User Name: administrator
• Password: administrator
• Domain: System

AppBoard credentials are case sensitive.

Create Data Source

As mentioned above and on the main Diagrammer widget documentation, we will need a data source with a primary key defined for use by the widget. Let's set this up now:

1. Select the Data Sources builder mode.
2. Click the Add button to create a new data source:
   1. Name: sample.USA_States
   2. Select an adapter type: File -> CSV File
   3. Click the Add Data Source button.
3. The Data Source Wizard will now display the Connect step, complete the following fields:
   1. File Path: click the magnifying glass and select examples/getting_started/states.csv.
   2. Header Meta Delimiter: Asterisk
   3. Click the Next button.
4. The Explore step should now be shown. Confirm the Primary Key is set to StateCode, and expand the states entry to view all fields and their types. Click the Next button.
5. Nothing needs to be configured on the Associate step, just click Finish to complete the wizard and save the new data source.

Stack

We'll need a place for the Diagrammer widget so let's create a new Stack, which automatically creates and a top-level board:

1. Select the Builder builder mode
2. Click the Add Stack quick action:
   1. Title: Diagrammer Tutorial
   2. Click the Add Stack button to create the new stack.
3. Since we're in the builder mode, the new stack should automatically become visible as a tab at the top. For now there is no content.

Diagrammer Widget

We have now reached the point where we finally start to create and configure our Diagrammer Widget. A "Widget" is a visual element that can be placed on a Board. In this section, we will create a Diagrammer Widget that will display basic information about state capitals.

1. Click "Widgets" under "Builder Modes" to display the Widgets Administration panel.
2. Click the “Add” button to create a new Widget.
3. In the “Name” box, enter “US_States_Diagram”.
4. For “Board”, select “USA_States_Stack”. Observe the various widget types and widgets that are available.
5. Select the widget type “Diagrammer” and select “Diagrammer”.
6. Click “Add Widget”.
7. Perform the following on the “Configure” panel to configure the widget:
   • Click "Manage Diagrams".
   • On the Manage Diagrams Dialog click the "New" button.
   • A new row is appended to the table with a label of “New Diagram”, double click the row and give the diagram a new name of “MyCoolDiagram”.
   • With “MyCoolDiagram” still highlighted, click the Use Selected button to close the dialog.
   • Click Next.
   • Click Next.
   • Click Finish.
8. Click Builder and observe that the board now shows a diagrammer widget.

Creating a New Node Type

Nodes are a very important aspect of the Diagrammer Widget. Nodes are specific pieces of data pulled from your data source that, in the Diagrammer Widget, are represented by icons and colors to display data in a visually appealing way for organization and comparison.

In this section we will create a new Node Type and drop a new node on the diagram.

1. In the Builder, click the Add New Node Type button (Green + sign beneath the Node Types Palette).
2. Type “State Node” in the Palette Label field.
3. Choose any icon to represent the node.
4. Choose sample.USA_States.stateCapitals as the DataSource to use.
5. Click Next.
6. Observe the "Available Tokens" section. Put “${Capital}” in the label field.
7. Click Next.
8. Press “Add” button next to "Color Filter".
9. In the "Color Filter Rules" window, name the rule set "Population Color Rules".
10. Click the "Add Color" button twice.
11. On the first color rule, pick a red color, pick Population in the green drop down, the greater than symbol ‘>’ in the grey drop down, and type 3000000 as the value.
12. On the second color rule, pick a green color, pick Population in the green drop down, use the less than ‘<’ symbol in the grey drop down, and type 3000000.
13. Close the window. Confirm that the "Population Color Rules" set is selected under "Color Filter".
14. Click Next.
15. Press “Add” button next to "Icon Filter".
16. Now in the "Icon Filter Rules" window, name the new rule set "Latitude Icon Rules".
17. Click the "Add" button twice.
18. Choose Router under "Available Icons", Latitude in the green drop down, > for the operator, and 36 for the value.
19. Choose Server 1 under "Available Icons", Latitude property in the green drop down, < for the operator, and 36 for the value.
20. Close the window. Confirm that the "Latitude Icon Rules" set is selected under "Icon Filter".
21. Click Finish.
22. Drag and drop the “State Node” type to the blank diagram.
23. Choose Montgomery as the item you would like to drop in the popup table.
24. Repeat for Austin, Hartford, Juneau until you get a diagram displaying four nodes with different icons and colors.

Creating Link Types

Links are another important part of the Diagrammer Widget. Links are a way of comparing nodes and displaying data. Basic Links are very simple: they do not have labels or show up in different colors based on a predetermined status rule, they are just arrows you can use to link data and display a visual connection. Custom Links, just like nodes, can be created to display labels and different colors to represent status.

In this section we will learn to use Basic Links and Custom Type Links.

1. Click the Create Link button (the horizontal arrow) on the Toolbar, and choose a link style from the button that appears to the right.
2. Click on the Montgomery node to begin drawing the link, then click on Austin node to complete the link.
3. Create a New Link Type by clicking the green + button.
4. Give the link type a Palette Label of "Custom Link".
5. Choose sample.USA_States.stateCapitals as the DataSource to use.
6. Click Next.
7. Put “${Capital}” in the label field.
8. Click Next.
9. Select the "Population Color Rules" rule set we created in the previous exercise. This will apply the same rules to our link colors.
10. Click Finish.
11. With the Custom Link type selected, click any node and click another node to connect the two with a custom link.
12. Choose any row in the DataSource to associate with the link and you will see the label and color of the link change.

---

Hopefully you have just completed the walk-through without issue, and feel comfortable using the Diagrammer Widget. For more information and specifics on the Diagrammer Widget, visit the Diagrammer Widget page.