Appboard/2.5/tutorials/getting started tutorial: Difference between revisions

imported>Jason.nicholls
imported>Jason.nicholls
 
(45 intermediate revisions by the same user not shown)
Line 3: Line 3:
==Audience==
==Audience==


The audience of this guide is a beginning AppBoard dashboard developer, or anyone interested in learning about the basic capabilities of AppBoard.
This getting started tutorial is aimed at beginner AppBoard administrators. It may also be useful for general users that would like to understand the basics of how AppBoard works to deliver dashboards and interaction.
 


==Overview==
==Overview==


The overall goal of the tutorial is to build an interactive sales dashboard and use this to present an overview of major features within AppBoard. The tutorial is limited in scope and should be possible to complete within 30 minutes, however the underlying data contains more information that is used and will allow for additional exploration beyond the tutorial instruction.
The overall goal of the tutorial is to build an interactive sales dashboard and use this to present an overview of major features within AppBoard. The tutorial is limited in scope and should be possible to complete within 30 minutes, however the underlying data contains more information than utilized and the ''Next Steps'' section at the end covers some suggestions on further exploration.
 


== Prerequisites ==
== Prerequisites ==
Line 15: Line 13:
To complete this tutorial the following is required:
To complete this tutorial the following is required:


# AppBoard installed and running. Refer to the [[appboard/2.5/admin/installation|Installation]] documentation for more information on installing.
# AppBoard installed and running. Refer to the [[appboard/2.5/admin/installation|Installation]] documentation for more information.
# Connectivity to the AppBoard server, and administrator access. Refer to the [[appboard/2.5/admin/accessing_appboard|Accessing AppBoard]] documentation for more information.
# Connectivity to the AppBoard server, and administrator access. Refer to the [[appboard/2.5/admin/accessing_appboard|Accessing AppBoard]] documentation for more information.
# A supported web browser with a supported version of the Adobe Flash Player installed. Refer to the [[appboard/2.5/system_requirements|System Requirements]] for a list of supported browsers and Flash versions.
# A supported web browser with a supported version of the Adobe Flash Player installed. Refer to the [[appboard/2.5/system_requirements|System Requirements]] for a list of supported browsers and Flash versions.
# Internet access to use the Tile Map widget (alternatively use the Vector Map).
# Internet access to use the Tile Map widget (alternatively use the Vector Map).


== Part One ==
== Part One ==
Line 27: Line 24:
In part one of this tutorial the focus will be on bringing up some basic content. This will consist of:
In part one of this tutorial the focus will be on bringing up some basic content. This will consist of:


* Log into AppBoard as an administrator
* Logging in to AppBoard as an administrator
* Setting up some Data Sources
* Setting up some Data Sources
* Creating a Data Collection
* Creating a Data Collection
Line 56: Line 53:
# Select the ''Data Sources'' builder mode
# Select the ''Data Sources'' builder mode
# Click the ''Add'' button to create a new data source:
# Click the ''Add'' button to create a new data source:
## Name: <tt>getting_started</tt>
## ''Name'': <tt>getting_started</tt>
## Select an adapter type: File -> CSV Directory
## ''Select an adapter type'': File -> CSV Directory
## Click the  ''Add Data Source'' button.
## Click the  ''Add Data Source'' button.
# The Data Source Wizard will now display the ''Connect'' step, complete the following fields:
# The Data Source Wizard will now display the ''Connect'' step, complete the following fields:
## Directory: click the magnifying glass and select '''TODO'''
## ''Directory'': click the magnifying glass and select <tt>examples/getting_started</tt>
## Header Meta Delimiter: Asterisk
## ''Header Meta Delimiter'': Asterisk
## Click the ''Next'' button.
## Click the ''Next'' button.
# The ''Explore'' step should now be shown. There should be two entities, <tt>state_counties</tt> and <tt>states</tt>. Expand these out to see the fields and field types. Also take notice of the ''Primary Key'' column. Click the ''Next'' button.
# The ''Explore'' step should now be shown. There should be two entities, <tt>state_counties</tt> and <tt>states</tt>. Expand these out to see the fields and field types. Also take notice of the ''Primary Key'' column. Click the ''Next'' button.
Line 71: Line 68:
# Click the ''Create Sub-Query'' button to create a new sub-query data source:
# Click the ''Create Sub-Query'' button to create a new sub-query data source:
# This launches straight into the Sub-Query Data Source Wizard:
# This launches straight into the Sub-Query Data Source Wizard:
## Name: <tt>getting_started.region_summary</tt>
## ''Name'': <tt>getting_started.region_summary</tt>
## Source: select <tt>getting_started.states</tt>
## ''Source'': select <tt>getting_started.states</tt>
## Click the ''Simple Select'' toggle, it should switch to the green ''Advanced Transform'' state.
## Click the ''Simple Select'' toggle, it should switch to the green ''Advanced Transform'' state.
## Select the ''Transform'' option:
## Select the ''Transform'' option:
Line 79: Line 76:
### Aggregation -> <tt>StateCode</tt> -> Count
### Aggregation -> <tt>StateCode</tt> -> Count
### Aggregation -> <tt>TotalSales</tt> -> Summation
### Aggregation -> <tt>TotalSales</tt> -> Summation
## Click ''Next'' and then ''Finish'' to save the data source.
## Click ''Next'', ''Next'', and then ''Finish'' to save the data source.


That's it. We now have a derived data source with a count of states and a total sales figure grouped by region.
That's it. We now have a derived data source with a count of states and a total sales figure grouped by region.
Line 87: Line 84:
By default a data collection is automatically created for each data source entity using the same name. Select the ''Data Collections'' builder mode to view the data collections and the following should be visible:
By default a data collection is automatically created for each data source entity using the same name. Select the ''Data Collections'' builder mode to view the data collections and the following should be visible:


* getting_started.region_summary
* <tt>getting_started.region_summary</tt>
* getting_started.state_counties
* <tt>getting_started.state_counties</tt>
* getting_started.states
* <tt>getting_started.states</tt>


You can preview the data returned for each of these data collections by clicking the blue icon in the preview column.
You can preview the data returned for each of these data collections by clicking the blue icon in the preview column.


On our dashboard we're going to want a Top 5 chart showing the states with the strongest states. We can create a custom data collection to order and limit the result set:
On our dashboard we want a Top 5 chart showing the states with the strongest sales. Create a custom data collection to order and limit the result set to support this visualization:


# Click the ''Add'' button to create a new data collection.
# Click the ''Add'' button to create a new data collection.
## Name: <tt>getting_started.top5_states</tt>
## ''Name'': <tt>getting_started.top5_states</tt>
## Data Source: <tt>getting_started.states</tt>
## ''Data Source'': <tt>getting_started.states</tt>
## Select the ''Server Side Sort'' option:
## Select the ''Server Side Sort'' option:
##* Use the ''Add'' button to create a sort on <tt>TotalSales</tt> -> Descending.
##* Use the ''Add'' button to create a sort on <tt>TotalSales</tt> -> Descending.
## Select the ''Limit Row Count'' options:
## Select the ''Limit Row Count'' options:
##* Server Side Row Limit: <tt>5</tt>
##* ''Server Side Row Limit'': <tt>5</tt>
# Click the ''OK'' button to close and save this data collection.
# Click the ''OK'' button to close and save this data collection.
# Preview the new data collection.
# Preview the new data collection.


== Part Two ==
=== Stacks & Boards ===


=== Exercise Summary ===
''Stacks'' represent a collection of dashboards and always have at least one top-level dashboard. Stacks also form the top level navigation in AppBoard with stacks presented as tabs along the top of the interface. Provisioning is used to determine what stacks a user may see or access. The administrator has access to all stacks and can control which stacks are visible in the Builder.


In part two the focus is on adding some interaction and building out additional context sensitive content. This will mainly focus on:
''Boards'' are dashboards in AppBoard which consist of a number of visualizations (widgets) and how those widgets are laid out.


* Create widget actions
Create a new stack for the State Sales dashboard:
* Filtering Data Collections via action.


# Select the ''Builder'' builder mode
# Click the ''Add Stack'' quick action:
## ''Title'': <tt>State Sales</tt>
## Click the ''Add Stack'' button to create the new stack.
# 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.


== Exercise Summary ==
Managing stacks and boards in general can also be performed from the ''Stacks & Boards'' builder mode.


In this exercise, you will go through all of the major steps for building a visualization suite in AppBoard:
=== Widgets ===


# Connecting to a data source
AppBoard ''Widgets'' are visualization elements placed and arranged on boards. AppBoard includes a large variety of widgets and includes an API for creating custom widgets. Typically you are working with widgets in the ''Builder'' mode directly on boards. However widgets can also be managed from the ''Widgets'' builder mode.
# Creating a filtered data collection
# Creating a dashboard
# Adding Widgets to a dashboard
# Re-arranging the layout of a dashboard
# Configuring actions to trigger changes to a Widget and launching other dashboards


Let's create several widgets to form our initial sales dashboard:


For this example, two sample data files are provided as part of the AppBoard product installation. One file lists the states in the United States of America and contains data such as population and map coordinates of the state capital.  The other file lists the counties within each state, along with sample data for each county.  This data provides an easy way to get started with AppBoard, without having to spend time gathering database information or connecting to a server.
* A map showing all states with indicators of whether they're on target with sales.
* A bar chart showing the top 5 states by sales
* A pie chart showing a sales by region


Perform these steps to create the map. Please note that Internet access is required for the Tile Map, if this is not possible then you can substitute in the Vector Map instead:


The goals of this exercise are the following:
# Select the ''Builder'' mode, and the <tt>State Sales</tt> stack.
# Click the ''Add Widget'' button on the left:
## The Add Widget Wizard should launch on the ''Data'' step:
##* ''Widget Type'': Maps -> Tile Map
##* ''Data Collection'': <tt>getting_started.states</tt>
##* ''Widget Name'': <tt>State Summary</tt>
##* click the ''Next'' button
## On the ''Visualization'' step:
##* ''Auto Zoom'': toggle switch to green ''Fit to Data'' state.
##* ''Colored Shape Filter'': click the ''Add'' button. We will create a filter to place blue markers for states on target with sales, and red markers for sales behind target:
##** ''Name'': <tt>StateSalesTarget</tt>
##** Click the ''Add'' button to create the following rules:
##*** Color: blue, Property: <tt>OnTarget</tt>, Comparator: <tt>=</tt>, Value: <tt>1</tt>
##*** Color: red, Property: <tt>OnTarget</tt>, Comparator: <tt>=</tt>, Value: <tt>0</tt>
##** Click the ''Close'' button to close the filter editor.
##* ''Colored Shape Filter'': select the new <tt>StateSalesTarget</tt> filter in the drop-down selection.
##* Click the ''Next'' button
## No need to do anything on the ''Links'', ''Overlays'' or ''Options'' steps, just click ''Next'', ''Next'', and then ''Finish'' to save the widget.
# A map widget should now be visible in the builder. Since this is the only widget on the dashboard so far it will use up all the available space. There should be a mix of red and blue dots if everything is working correctly.


# Create a Board displaying a US map, with pins on the state capitals, as well as an associated data grid displaying detailed information about each state
Repeat a similar process for the bar chart:
# Configure an action to filter the pins on the map to only display for Northern states with a large population
# Re-arrange the layout of the Widgets
# Configure an action to launch a new Board when a pin is clicked on the US map, displaying a data grid listing the counties in the state that was clicked


# Click the ''Add Widget'' button.
## The Add Widget Wizard should launch on the ''Data'' step:
##* ''Widget Type'': Charts -> Bar
##* ''Data Collection'': <tt>getting_started.top5_states</tt>
##* ''Widget Name'': <tt>Top 5 States</tt>
##* click the ''Next'' button
## On the ''Visualization'' Step:
##* ''Y-Axis Field'': <tt>State</tt>
##* ''Series'': click the ''Add'' button, and set the ''X-Field'' to <tt>TotalSales</tt>. Format the color and pattern as per your preference. The spinners with the up/down arrows control how transparent the color or pattern is.
##* click the ''Next'' button
## No need to do anything on the ''Presentation'' or ''Options'' steps, just click ''Next'' and then ''Finish'' to save the widget.
# A bar chart widget should now be visible taking up half the space. Re-edit the widget by clicking on the <tt>>></tt> icon in the widget title bar and then the wrench icon. On the ''Presentation'' step add a ''X-Axis Title'' of <tt>Total Sales ($)</tt>.


==Data Sources==
Repeat the same process again for the pie chart:


The first step in creating a dashboard is defining a data source that will be used by the Widgets. The “Data Sources” Builder Mode displays the Data Sources panel, where you can add and edit data sources.
# Click the ''Add Widget'' button.
## The Add Widget Wizard should launch on the ''Data'' step:
##* ''Widget Type'': Charts -> Pie
##* ''Data Collection'': <tt>getting_started.region_summary</tt>
##* ''Widget Name'': <tt>Sales Regions</tt>
##* click the ''Next'' button
## On the ''Visualization'' Step:
##* ''Name Field'': <tt>SalesRegion</tt>
##* ''Value Field'': <tt>sum TotalSales</tt>
##* ''Color Selection'': pick colors and patterns to suit your preference.
##* click the ''Next'' button
## On the ''Presentation'' step:
##* ''Inner Radius'': enable and set to <tt>70</tt>
##* ''Label'': enable and set to ''callout''
##* click the ''Next'' button
## Click the ''Finish'' button to save the widget.
# A pie (well donut!) chart should now be visible using up one third the available space.


Data Sources define connections to data warehouses, such as databases, file systems, web services and system APIs. The basic purposes of a Data Source are to define a connection to the outside data, provide an AppBoard "namespace" for the data, and provide security measures such as filtering the incoming data.
=== Layout ===


In this section, you will create a mapping in AppBoard to a data source file.  The file is a table of comma-separated-values (CSV) that lists the states in the United States of America and contains data such as population and map coordinates of the state capitals.
With three widgets on the dashboard we can re-arrange the widgets and adjust the dividers to improve the look. Try the following and come up with a layout that suits your preference:


'''Action: Click Data Sources to display the Data Sources panel'''
* Use the top-left grab handle in a widget title bar to drag the widget.
** Drag onto another widget and notice the widget will highlight blue indicating a split and place operation, you can split and place vertically or horizontally.
** Drag into the divider space between widgets to place into an existing horizontal or vertical grouping.
** Drag a widget onto the title bar of another widget to place the widgets on top of each other. This is called a stacked widget - although not covered in this tutorial.
* Move the mouse into the divider space between widgets then click and drag to modify the divider position.


=== Conclusion ===


AppBoard supports a variety of data sources. You can also write your own custom data adapters, if needed. In this guide, a sample CSV file will be used as a data source.
The result of part one is we now have a top level state sales summary dashboard with three widgets. It should look something like this, of course the layout, colours, etc... may differ for you:


[[File:appboard-2.5-getting-started-part1.png|frame|center|Result of part one]]


[[File:Datasource.png]] '''Action: Perform the following steps to add a data source:'''
== Part Two ==
# '''Click the Add button'''
# '''In the “Name” box, enter “sample.USA_States”'''
# '''For the adapter type, select “File”'''
# '''Under the file type, select “CSV File”'''
# '''Click the “Add Data Source” button.  The “Connect” screen will be displayed.'''
# '''Under “File Path”, enter “${application.home}/data/pkg/appboard/test/stateCapitals.csv”'''
# '''Click Next.  The “Explore” screen will be displayed with a list of data files found.'''
# '''Under “Primary Key” for the "stateCapitals" folder, click the Edit button and select “StateID”'''
# '''Click OK.
# '''Click Next.  The “Associate” screen will be displayed'''
# '''Click Finish.  On the Data Sources page under the Data Sources panel, confirm that the Data Source “sample.USA_States” is now listed.'''


=== Exercise Summary ===


Associations are logical connections between two pieces of data; often referred to as "foreign-keys" in databases. For example, a collection of records about the individual states within the United States could be associated with a collection of records about the individual counties in each state. The county would have a "stateId" field would define the state in which the county resides. Therefore a one-to-many association can be created between a state and counties.
In part two the focus is on adding interaction and building out additional context sensitive content:


==Data Collections==
* Create widget actions
 
* Filter Data Collections via action
A "Data Collection" is a group of data sources that are available for the Widgets in the system to use.  Every time a Data Source is created, a Data Collection is made using all of the data from the data source.  Creating your own Data Collections allows you to configure filtered data sets from the raw data in a Data Source.  For example, you can create server-side or client-side filters that restrict the data that will go into your Widgets.
* Create a child-board
 
* Add a widget onto the child-board
In this section, you will create a filtered data collection from your raw data source.  The filter will select the states in the Northern part of the USA.
 
[[File:Datacollection.png]] '''Action: Perform the following steps to add a Data Collection:''' 
 
# '''Click Data Collections to display the Data Collections panel''' 
# '''Click the Add button'''
# '''In the “Data Collection Name” box, enter “sample.Northern_States”'''
# '''For Data Source, select “sample.USA_States.StateCapitals”'''
# '''Click the “Configure Client Side” tab at the top.    The “Client Side Filter” screen will be displayed'''
# '''Click the "Add Rule" button and select “Simple Property Comparison”'''
# '''For “Property”, select “Latitude”'''
# '''For the comparison type, select “>”'''
# '''In the “Value” box, enter 40'''
# '''Click OK'''
# '''In the Data Collections panel, confirm that the “sample.Northern_States” collection is listed'''
# '''Click the “Preview” button in the row of the new data collection to launch the data viewer.  Observe that there are 23 rows representing states with latitude greater than 40.'''
# '''Click Close'''
 
==Stacks & Boards==
 
A "Board" represents a dashboard of information.  Each Board will consist of one or more Widgets.  A Board typically displays a suite of information that is related in some meaningful way, and which will be appropriate to present as a visualization to an AppBoard end-user.
 
A "Stack" is a collection of Boards that contain related information. For example, a Stack named "States" might have two boards, one that lists all of the states in the US and another Board that shows only the details of a single state. Stacks are generally used for drill-down purposes. Clicking on a state in the US level Board would reveal the details of that state in the single state details Board.
 
In this section, you will create a Stack (and a Top-Level Board) that will be used for displaying Widgets with information about the states in the USA.
 
[[File:Stack.png]] '''Action: Perform the following steps to create a Stack:'''
 
# '''Click Stacks & Boards to display the Stacks & Boards panel'''
# '''In the left panel, under “Quick Actions”, click the “Add Stack” item'''
# '''Under "Title”, enter “USA_States_Stack”'''
# '''Click the "Add Stack" button'''
# '''Confirm that the Stack “USA_States_Stack” is now listed in the Stacks & Boards panel'''
# '''In the left panel, click “Builder” to display the empty Stack'''
 
==Widgets==
 
A "Widget" is a visual element that can be placed on a Board. For example, the "Data Grid Widget" gives a visual representation of tabular data in a familiar spreadsheet format.  Boards contain one or more Widgets, each displaying part (or all) of the data to be visualized.  Widgets are viewed by the Widget wizard or during the Boards step by the Stacks & Boards wizard. These wizards are invoked via links in the left side tool palette of the Appboard Builder interface.
 
In this section, you will create a map Widget that displays a USA map.  You will place pins on the map where the state capitals are located for the northern states only. 
 
[[File:Widget.png]] '''Action: Perform the following steps to create a Widget:'''
# '''Click Widgets to display the Widgets panel'''
# '''At the top, For “Board”, select “USA_States_Stack”'''
# '''Click the “Add” button to create a new Widget'''
# '''Select the Widget type “Maps” and select “Vector Map”. Click “Use Selected”'''
# '''For “Data Collection”, select “sample.Northern_States”'''
# '''In the “Widget Name” box, enter “Northern_States_Map”'''
# '''Click “Next”.  The “Visualization” screen will be displayed'''
#* '''For "Map Type" select "US"'''
#* '''For “Adornment Label Field”, select “Capital”'''
#* '''For “Latitude Field”, select “Latitude”'''
#* '''For “Longitude Field”, select “Longitude”'''
#* '''Observe that some data points are now displayed in the preview panel'''
#* '''You may change the default pin shape and color here.  You may also add filters that determine the pin appearances.'''
#* '''Click “Next”.  The “Trouble Bubble” screen will be displayed'''
#* '''Click “Next”.  The “Options” screen will be displayed'''
#* '''Click Finish'''
# '''On the main panel, click “Builder” to display the “USA_States_Stack” stack.  Observe the Widget displaying a US map with pins showing the capitals of the Northern states.'''
# '''Click the Edit button to additionally edit the widget colors and other presentation elements'''
 
 
In this section, you will create a data grid Widget to be displayed beneath the map Widget.  It will show details about each state.
 
'''Action: Perform the following steps to create a second Widget:'''
 
# '''Click Widgets to display the Widgets panel'''
# '''At the top, For “Board”, select “USA_States_Stack”'''
# '''Click the “Add” button to create a new Widget'''
# '''Select the Widget type “Lists & Table” and select “Table”. Click “Use Selected”'''
# '''For “Data Collection”, select “sample.Northern_States”'''
# '''In the “Name” box, enter “Northern_States_Info”'''
# '''Click “Next”.  The “Visualization” screen will be displayed'''
#* '''Under “Columns”, click “Add Column”'''
#* '''Under “Data Field”, select “State”'''
#* '''For the "Renderer" column, use the default values (no changes needed)'''
#* '''Repeat steps 7.1-7.3, until all of the fields are added and shown in the Preview panel below'''
#* '''Click Next, and Finish to exit the Widget configuration panels'''
# '''Click Builder and observe that the Board now shows a map Widget and table Widget'''


==Actions==
=== Actions ===


In addition to just visualizing data, Widgets allow you to configure "Actions". For example, you can contextually filter one widget based on a selection in another, or you can Drill Down into a child board that shows details based on an item selected in the parent. The key is knowing that when you click on a Widget, you're actually clicking on the piece of data that's being represented by the widget. Actions allow you to use this piece of data as context to alter client or server side filters for any Data Collection inside AppBoard. This flexibility allows for extremely powerful interactions.
In AppBoard both ''Click'' and ''Hover'' actions are configured per widget and form the basis for interaction with the dashboards. Actions can be coupled together to perform complex behaviour such as drilling down to a child board and filtering the information to suit the item selected.


In this section you will then configure an action to filter the display when one of the pins is clicked, to only show northern states with a total population that is greater than 2,000,000 residents.
As a first step the map would be much more useful if the user could hover over a point to see additional information about that state. Perform the following steps to set this up:


'''Action: Perform the following steps to create an Action:
# In the <tt>State Summary</tt> (map widget) title bar, expand the tool palette on the right side by clicking the <tt>>></tt> icon.
# Click the lightning bolt icon to launch the ''Widget Actions'' dialog:
# Select the ''Hover'' button.
# Click the ''Add Action'' button and select ''Show Data Tip''
#* Drag fields from the left to the right to include them in the data tip. Pick at least the <tt>State</tt>, <tt>SalesRegion</tt>, and <tt>TotalSales</tt> fields.
# Click the ''Close'' button.
# Now hover your mouse over a point on the map, a pop-up data tip will be visible showing the configured fields.


# '''In the upper right hand corner of the "Northern_States_Map" Widget click the arrow to expand the tool bar to show additional options. 
The next thing we want to do is to be able to drill-down on a state to get more information about how that state is performing.
#* '''Click the Actions icon (lightning bolt) to open the Actions editor in the Widget Wizard.
#* '''Click the “Add Action” button and select "Apply a Filter to a Data Collection" from the drop-down list'''
#* '''Next to “On selection of”, make sure "any" and “sample.USA_states.StateCapitals” are selected'''
#* '''For “Filter data collection”, select “sample.Northern_States”'''
#* '''Click the “Add Rule” button and select “Simple Property Comparison”'''
#* '''For “Property”, select “Population”'''
#* '''For the comparison type, select “>”'''
#* '''In the “Value” box, enter 2000000'''
#* '''Add a second Rule in the same manner, setting “Latitude” “>” “40”'''
#* '''Click Close
# '''Click on a pin in the map to activate the event which will filter the map to only display capitals for northern states with a Population > 2,000,000


==Layout==
# Bring up the ''Widget Actions'' dialog again for the <tt>State Summary</tt> widget.
Since you have created a dashboard with two Widgets, you may want to organize how the Widgets are presented on the screen.
# By default the ''Click'' actions will be shown, we want to configure a click action so that's good.
# Click the ''Add Action'' button and select ''Switch to a Board'':
#* ''Board'': click ''Add Board'':
#** ''Title'': <tt>State Summary</tt>
#** ''Parent Board'': <tt>State Sales</tt>
#** Click ''Add Board'' to create the new child-board.
#* ''Board'': select <tt>State Summary</tt>
#* ''User Context Label Field'': enable and set to <tt>State</tt>
# Click the ''Close'' button.
# Now you should be able to click on a point on the map and it will drill down to the <tt>State Summary</tt> board with the context title <tt>State Summary: ''&lt;state_clicked&gt;''</tt>. For now this board is empty.
# To go back to the top-level board, click on the <tt>State Sales</tt> link in the breadcrumb trail under the stack tabs.


There is one more action we need to configure. The <tt>getting_started.state_counties</tt> data collection contains over 3000 records covering all states. When we drill down to the state summary dashboard we only want to show records for the selected state. This can be achieved by performing either a Server Side Filter (SSF) or Client Side Filter (CSF) action. Server side filters are executed on the server and only the results sent to the client. A client side filter is executed on the client and so the client has to receive the full data collection in order to do this. In this case it doesn't matter too much so let's configure a SSF:


[[File:Board.png]] '''Action: Perform the following steps to modify the layout of a Board:'''
# Bring up the ''Widget Actions'' dialog again for the <tt>State Summary</tt> widget.
# '''Grab the upper-left corner of the label bar of the lower Widget and drag the lower Widget above the upper Widget until you observe a change in color.  Release the Widget and observe that the order of the Widgets has been swapped.'''
# Click the ''Add Action'' button and select ''Apply a Server Side Filter to a Data Collection'':
# '''Grab the label bar of the lower Widget and drag the lower Widget to the right of the upper Widget until you observe a change in color.  Release the Widget and observe that the Widgets are now side by side.'''
#* ''Filter data collection'': <tt>getting_started.state_counties</tt>
# '''Drag the Widgets around to any desired layout configuration'''
#* Click the ''Add Rule'' button and select ''Widget Interaction Comparison''
# '''Grab the lower-right corner to make the Widgets bigger or smaller'''
#* ''Selected Data has a property'': <tt>StateCode</tt> <tt>=</tt> ''filtered data property'': <tt>StateCode</tt>.
#* In the above we are filtering rows in the state_counties data collection that match the StateCode clicked on in the map.
#* Click the ''Close'' button.
# For now we can't really test this as we don't have any widgets showing the state_counties data collection, that's the next step.


=== More Widgets ===


==Switching to a Child Board==
We now want to add a table showing counties on our State Summary drill-down. Based on the actions above this table should only show a filtered list of counties that match the state clicked on from the top level dashboard.
Every stack in AppBoard begins with a Top-Level Board, sometimes referred to as a “Parent Board” or “Summary Board”. The Board you created in the exercises above is a Top-Level Board.  You will often want actions on the Top-Level Board to launch "Child Boards".  Child Boards present Widgets containing data that is filtered or more detailed in some way.


In this section, you will modify the action that occurs when the user clicks on a pin in the map. Earlier, you configured the click action to filter the map to only display pins for states with a population greater than 2,000,000 residents. Now you will modify the action so that a new Board is launched when a pin is clicked. The new Board will display a data grid listing all of the counties for the state that was clicked on the map.
# Click a point on the map to get to the drill-down <tt>State Summary</tt> dashboard.
# Click the ''Add Widget'' button:
## On the ''Data'' step:
##* ''Widget Type'': leave as ''Table'' (the default type)
##* ''Data Collection'': <tt>getting_started.state_counties</tt>
##* ''Widget Name'': <tt>Sales by County</tt>
##* click ''Next''
## On the ''Visualization'' step:
##* use the ''Add Column'' button to add the following columns: <tt>County</tt>, <tt>LastYearSales</tt>, <tt>SalesToDate</tt>, and <tt>SalesTarget</tt>.
##* note that by clicking in the ''Renderer'' column it is possible to edit the column heading and spacing, or use alternative renderers.
##* click ''Next''
## Click ''Finish'' on the ''Options'' step to save the widget.


'''Action: Perform the following steps to create an action that will switch to a Child Board:'''
=== Conclusion ===
# '''Click Data Sources and create a new Data Source called “sample.USA_Counties” from the CSV file stateCounties.csv, with Primary Key = “CountyID”.'''
# '''Under "File Path", enter "${application.home}/data/pkg/appboard/test/stateCounties.csv".'''
# '''Click Builder to display USA_States_Stack, containing a map and table Widget'''
# '''On the Northern_States_Map Widget, click the Actions (lightning bolt) icon to open the Actions editor in the Widget Wizard'''
# '''Click “x” to delete all of the existing actions'''
# '''Perform the following steps to define a new action:'''
#* '''Click the “Add Action” button and select "Switch to a Board" from the drop-down list'''
#* '''Next to “On selection of”, make sure you have selected "any" and “sample.USA_states.StateCapitals”'''
#* '''Click the “Add Board” button'''
#* '''For “Title”, enter “County Table”'''
#* '''For “Parent Board”, select “USA_States_Stack”'''
#* '''Click “Add Board” to exit the Add Board dialog
#* '''Select the new board from the “Board” drop-down list
#* '''Check the box next to “Use Context Label Field”, select “StateLabel”'''
#* '''Click the “Add Action” button and select "Apply a Filter to a Data Collection" from the drop-down list'''
#* '''For “On selection of”, select "any" and “sample.USA_States.StateCapitals”'''
#* '''For “Filter data collection”, select “sample.USA_Counties.stateCounties”'''
#* '''Click the “Add Rule” button and select “Widget Interaction Comparison”'''
#* '''Select the following for the Widget interaction properties:'''
#** '''“Selected Data has a Property”: “StateLabel” “=”'''
#** '''“filtered data property”: “StateLabel”'''
# '''Click “Close” to exit the Actions editor in the Widget Wizard'''
# '''Click Widgets and create a new Widget called “County Data Table” on the Board “County Table” and select the "Table" Widget Type under the "Lists & Table" tab'''
# '''Configure the Widget to display one or more fields from the Data Collection “sample.USA_Counties.stateCounties”'''
# '''Click Next and Finish to exit the Widget configuration panels'''
# '''Click Builder to again display USA_States_Stack, containing the map and table Widget'''
# '''Click on a pin in the map, and observe that AppBoard launches a child Board displaying the county data for those counties in the state that you selected'''


The top-level dashboard should look the same except for the mouse-hover data tips on the map. It is also now possible to click on a state in the map and drill-down to a state summary showing a table with sales by county. The table should look something like this, with Washington selected. This table includes an extra status shape renderer showing whether the county is on target with sales or not (as suggested in the  ''Next Steps'' section).


==Conclusion==
[[File:appboard-2.5-getting-started-part2.png|frame|center|Drill-down dashboard from part 2]]


In this exercise, you have connected to data sources, created boards, and configured actions.  This is the essence of AppBoard.  Hopefully you have seen that data visualizations can be easily built and modified using the AppBoard Builder.
== Next Steps ==


Next, you may want to create some data files that replicate the type of data that you will be using to build AppBoard visualizations.  Once you have created some visualizations from sample data, you can then change the data source to be your live data source or feed, and exercise the full capability of AppBoard.
This tutorial is limited on purpose to just cover the basics, however AppBoard provides a lot more capability and we haven't quite exploited the underlying data as much as we could have. We certainly recommend playing around with the components already added as part of the tutorial and here are some additional suggestions:


* Create a filter on the Sales Regions widget to filter the map by region.
* Add mouse-hover data tips to everything.
* Add a Status Shape renderer to the Sales by County table as shown in the screenshot above.
* Explore the widget ''Options'' configuration.
* Try out some other visualizations or play around with the visualization options.


==Next Steps==
Also this tutorial has focused on data and visualizations, the next areas to look at
are:


To create users in the system, and assign the USA States sample stack to those users, refer to the [[appboard/2.5/admin/provisioning|Provisioning Overview]] documentation.
* [[appboard/2.5/admin/provisioning|Provisioning]] to manage users, roles, and assigning content.
* [[appboard/2.5/builder/system_administration/themes|Themes]] to change the overall look and feel of AppBoard.

Latest revision as of 08:14, 23 September 2014

Audience

This getting started tutorial is aimed at beginner AppBoard administrators. It may also be useful for general users that would like to understand the basics of how AppBoard works to deliver dashboards and interaction.

Overview

The overall goal of the tutorial is to build an interactive sales dashboard and use this to present an overview of major features within AppBoard. The tutorial is limited in scope and should be possible to complete within 30 minutes, however the underlying data contains more information than utilized and the Next Steps section at the end covers some suggestions on further exploration.

Prerequisites

To complete this tutorial the following is required:

  1. AppBoard installed and running. Refer to the Installation documentation for more information.
  2. Connectivity to the AppBoard server, and administrator access. Refer to the Accessing AppBoard documentation for more information.
  3. A supported web browser with a supported version of the Adobe Flash Player installed. Refer to the System Requirements for a list of supported browsers and Flash versions.
  4. Internet access to use the Tile Map widget (alternatively use the Vector Map).

Part One

Exercise Summary

In part one of this tutorial the focus will be on bringing up some basic content. This will consist of:

  • Logging in to AppBoard as an administrator
  • Setting up some Data Sources
  • Creating a Data Collection
  • Creating a Stack (top-level dashboard)
  • Adding Widgets

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:

Template-note.png
AppBoard credentials are case sensitive.

Data Sources

The first step in creating a dashboard is defining a data source that will be used by the Widgets. The Data Sources Builder Mode displays the Data Sources panel, where you can add and edit data sources.

Data Sources connect AppBoard to external sources of data such as files, databases, web services, 3rd party connectors, and custom commands. The basic purposes of a Data Source are to define a connection to the outside data, define the sets of data returned by the source (Data Source entities), define associations between different Data Source entities, and other properties such as caching.

In this section you will create a data source for a directory containing comma-separated-values (CSV) files. One file contains US state information, and the other includes a breakdown by counties for each state.

Perform these steps:

  1. Select the Data Sources builder mode
  2. Click the Add button to create a new data source:
    1. Name: getting_started
    2. Select an adapter type: File -> CSV Directory
    3. Click the Add Data Source button.
  3. The Data Source Wizard will now display the Connect step, complete the following fields:
    1. Directory: click the magnifying glass and select examples/getting_started
    2. Header Meta Delimiter: Asterisk
    3. Click the Next button.
  4. The Explore step should now be shown. There should be two entities, state_counties and states. Expand these out to see the fields and field types. Also take notice of the Primary Key column. Click the Next button.
  5. The Associate step can be used to associate one data source entity to another. They can be from completely different data sources. For now leave this blank and click the Finish button.

Let's also create a summary for each sales region. Since this information is not in the CSV files we can use the Sub-Query adapter to perform this function:

  1. Select the getting_started data source just created above.
  2. Click the Create Sub-Query button to create a new sub-query data source:
  3. This launches straight into the Sub-Query Data Source Wizard:
    1. Name: getting_started.region_summary
    2. Source: select getting_started.states
    3. Click the Simple Select toggle, it should switch to the green Advanced Transform state.
    4. Select the Transform option:
    5. Use the Add button to add the following transforms:
      1. Group By -> SalesRegion
      2. Aggregation -> StateCode -> Count
      3. Aggregation -> TotalSales -> Summation
    6. Click Next, Next, and then Finish to save the data source.

That's it. We now have a derived data source with a count of states and a total sales figure grouped by region.

Data Collections

By default a data collection is automatically created for each data source entity using the same name. Select the Data Collections builder mode to view the data collections and the following should be visible:

  • getting_started.region_summary
  • getting_started.state_counties
  • getting_started.states

You can preview the data returned for each of these data collections by clicking the blue icon in the preview column.

On our dashboard we want a Top 5 chart showing the states with the strongest sales. Create a custom data collection to order and limit the result set to support this visualization:

  1. Click the Add button to create a new data collection.
    1. Name: getting_started.top5_states
    2. Data Source: getting_started.states
    3. Select the Server Side Sort option:
      • Use the Add button to create a sort on TotalSales -> Descending.
    4. Select the Limit Row Count options:
      • Server Side Row Limit: 5
  2. Click the OK button to close and save this data collection.
  3. Preview the new data collection.

Stacks & Boards

Stacks represent a collection of dashboards and always have at least one top-level dashboard. Stacks also form the top level navigation in AppBoard with stacks presented as tabs along the top of the interface. Provisioning is used to determine what stacks a user may see or access. The administrator has access to all stacks and can control which stacks are visible in the Builder.

Boards are dashboards in AppBoard which consist of a number of visualizations (widgets) and how those widgets are laid out.

Create a new stack for the State Sales dashboard:

  1. Select the Builder builder mode
  2. Click the Add Stack quick action:
    1. Title: State Sales
    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.

Managing stacks and boards in general can also be performed from the Stacks & Boards builder mode.

Widgets

AppBoard Widgets are visualization elements placed and arranged on boards. AppBoard includes a large variety of widgets and includes an API for creating custom widgets. Typically you are working with widgets in the Builder mode directly on boards. However widgets can also be managed from the Widgets builder mode.

Let's create several widgets to form our initial sales dashboard:

  • A map showing all states with indicators of whether they're on target with sales.
  • A bar chart showing the top 5 states by sales
  • A pie chart showing a sales by region

Perform these steps to create the map. Please note that Internet access is required for the Tile Map, if this is not possible then you can substitute in the Vector Map instead:

  1. Select the Builder mode, and the State Sales stack.
  2. Click the Add Widget button on the left:
    1. The Add Widget Wizard should launch on the Data step:
      • Widget Type: Maps -> Tile Map
      • Data Collection: getting_started.states
      • Widget Name: State Summary
      • click the Next button
    2. On the Visualization step:
      • Auto Zoom: toggle switch to green Fit to Data state.
      • Colored Shape Filter: click the Add button. We will create a filter to place blue markers for states on target with sales, and red markers for sales behind target:
        • Name: StateSalesTarget
        • Click the Add button to create the following rules:
          • Color: blue, Property: OnTarget, Comparator: =, Value: 1
          • Color: red, Property: OnTarget, Comparator: =, Value: 0
        • Click the Close button to close the filter editor.
      • Colored Shape Filter: select the new StateSalesTarget filter in the drop-down selection.
      • Click the Next button
    3. No need to do anything on the Links, Overlays or Options steps, just click Next, Next, and then Finish to save the widget.
  3. A map widget should now be visible in the builder. Since this is the only widget on the dashboard so far it will use up all the available space. There should be a mix of red and blue dots if everything is working correctly.

Repeat a similar process for the bar chart:

  1. Click the Add Widget button.
    1. The Add Widget Wizard should launch on the Data step:
      • Widget Type: Charts -> Bar
      • Data Collection: getting_started.top5_states
      • Widget Name: Top 5 States
      • click the Next button
    2. On the Visualization Step:
      • Y-Axis Field: State
      • Series: click the Add button, and set the X-Field to TotalSales. Format the color and pattern as per your preference. The spinners with the up/down arrows control how transparent the color or pattern is.
      • click the Next button
    3. No need to do anything on the Presentation or Options steps, just click Next and then Finish to save the widget.
  2. A bar chart widget should now be visible taking up half the space. Re-edit the widget by clicking on the >> icon in the widget title bar and then the wrench icon. On the Presentation step add a X-Axis Title of Total Sales ($).

Repeat the same process again for the pie chart:

  1. Click the Add Widget button.
    1. The Add Widget Wizard should launch on the Data step:
      • Widget Type: Charts -> Pie
      • Data Collection: getting_started.region_summary
      • Widget Name: Sales Regions
      • click the Next button
    2. On the Visualization Step:
      • Name Field: SalesRegion
      • Value Field: sum TotalSales
      • Color Selection: pick colors and patterns to suit your preference.
      • click the Next button
    3. On the Presentation step:
      • Inner Radius: enable and set to 70
      • Label: enable and set to callout
      • click the Next button
    4. Click the Finish button to save the widget.
  2. A pie (well donut!) chart should now be visible using up one third the available space.

Layout

With three widgets on the dashboard we can re-arrange the widgets and adjust the dividers to improve the look. Try the following and come up with a layout that suits your preference:

  • Use the top-left grab handle in a widget title bar to drag the widget.
    • Drag onto another widget and notice the widget will highlight blue indicating a split and place operation, you can split and place vertically or horizontally.
    • Drag into the divider space between widgets to place into an existing horizontal or vertical grouping.
    • Drag a widget onto the title bar of another widget to place the widgets on top of each other. This is called a stacked widget - although not covered in this tutorial.
  • Move the mouse into the divider space between widgets then click and drag to modify the divider position.

Conclusion

The result of part one is we now have a top level state sales summary dashboard with three widgets. It should look something like this, of course the layout, colours, etc... may differ for you:

Result of part one

Part Two

Exercise Summary

In part two the focus is on adding interaction and building out additional context sensitive content:

  • Create widget actions
  • Filter Data Collections via action
  • Create a child-board
  • Add a widget onto the child-board

Actions

In AppBoard both Click and Hover actions are configured per widget and form the basis for interaction with the dashboards. Actions can be coupled together to perform complex behaviour such as drilling down to a child board and filtering the information to suit the item selected.

As a first step the map would be much more useful if the user could hover over a point to see additional information about that state. Perform the following steps to set this up:

  1. In the State Summary (map widget) title bar, expand the tool palette on the right side by clicking the >> icon.
  2. Click the lightning bolt icon to launch the Widget Actions dialog:
  3. Select the Hover button.
  4. Click the Add Action button and select Show Data Tip
    • Drag fields from the left to the right to include them in the data tip. Pick at least the State, SalesRegion, and TotalSales fields.
  5. Click the Close button.
  6. Now hover your mouse over a point on the map, a pop-up data tip will be visible showing the configured fields.

The next thing we want to do is to be able to drill-down on a state to get more information about how that state is performing.

  1. Bring up the Widget Actions dialog again for the State Summary widget.
  2. By default the Click actions will be shown, we want to configure a click action so that's good.
  3. Click the Add Action button and select Switch to a Board:
    • Board: click Add Board:
      • Title: State Summary
      • Parent Board: State Sales
      • Click Add Board to create the new child-board.
    • Board: select State Summary
    • User Context Label Field: enable and set to State
  4. Click the Close button.
  5. Now you should be able to click on a point on the map and it will drill down to the State Summary board with the context title State Summary: <state_clicked>. For now this board is empty.
  6. To go back to the top-level board, click on the State Sales link in the breadcrumb trail under the stack tabs.

There is one more action we need to configure. The getting_started.state_counties data collection contains over 3000 records covering all states. When we drill down to the state summary dashboard we only want to show records for the selected state. This can be achieved by performing either a Server Side Filter (SSF) or Client Side Filter (CSF) action. Server side filters are executed on the server and only the results sent to the client. A client side filter is executed on the client and so the client has to receive the full data collection in order to do this. In this case it doesn't matter too much so let's configure a SSF:

  1. Bring up the Widget Actions dialog again for the State Summary widget.
  2. Click the Add Action button and select Apply a Server Side Filter to a Data Collection:
    • Filter data collection: getting_started.state_counties
    • Click the Add Rule button and select Widget Interaction Comparison
    • Selected Data has a property: StateCode = filtered data property: StateCode.
    • In the above we are filtering rows in the state_counties data collection that match the StateCode clicked on in the map.
    • Click the Close button.
  3. For now we can't really test this as we don't have any widgets showing the state_counties data collection, that's the next step.

More Widgets

We now want to add a table showing counties on our State Summary drill-down. Based on the actions above this table should only show a filtered list of counties that match the state clicked on from the top level dashboard.

  1. Click a point on the map to get to the drill-down State Summary dashboard.
  2. Click the Add Widget button:
    1. On the Data step:
      • Widget Type: leave as Table (the default type)
      • Data Collection: getting_started.state_counties
      • Widget Name: Sales by County
      • click Next
    2. On the Visualization step:
      • use the Add Column button to add the following columns: County, LastYearSales, SalesToDate, and SalesTarget.
      • note that by clicking in the Renderer column it is possible to edit the column heading and spacing, or use alternative renderers.
      • click Next
    3. Click Finish on the Options step to save the widget.

Conclusion

The top-level dashboard should look the same except for the mouse-hover data tips on the map. It is also now possible to click on a state in the map and drill-down to a state summary showing a table with sales by county. The table should look something like this, with Washington selected. This table includes an extra status shape renderer showing whether the county is on target with sales or not (as suggested in the Next Steps section).

Drill-down dashboard from part 2

Next Steps

This tutorial is limited on purpose to just cover the basics, however AppBoard provides a lot more capability and we haven't quite exploited the underlying data as much as we could have. We certainly recommend playing around with the components already added as part of the tutorial and here are some additional suggestions:

  • Create a filter on the Sales Regions widget to filter the map by region.
  • Add mouse-hover data tips to everything.
  • Add a Status Shape renderer to the Sales by County table as shown in the screenshot above.
  • Explore the widget Options configuration.
  • Try out some other visualizations or play around with the visualization options.

Also this tutorial has focused on data and visualizations, the next areas to look at are:

  • Provisioning to manage users, roles, and assigning content.
  • Themes to change the overall look and feel of AppBoard.