Appboard/2.5/builder/widgets: Difference between revisions

imported>Jfirebau
imported>Jason.nicholls
 
(21 intermediate revisions by the same user not shown)
Line 1: Line 1:
{{DISPLAYTITLE:Managing Widgets}}
{{DISPLAYTITLE:Widgets}}
[[Category:AppBoard 2.5]]
[[Category:AppBoard 2.5]]
[[Image:HeaderFlow05.png]]
[[Image:HeaderFlow05.png]]
== Overview ==


A "Widget" is a visual component placed on a Board. For example, the Table Widget gives a visual representation of tabular data in a familiar tabular format. Boards contain one or more Widgets, each displaying part of the data to be visualized.
''Widgets'' are used to present data in different ways, and are also the primary mechanism to interact with data through the use of ''Actions''. Widgets are arranged onto ''Boards'' that control layout, and Boards are organized into ''Stacks'' that are used as the primary navigation element and also tied to provisioning content.


AppBoard offers a wide variety of widgets along with an API to write custom HTML widgets, and the ability to bring in external web content through enPortal. The screenshot below shows a broad cross section of widgets shipped with AppBoard:


AppBoard uses one or more widgets to present the data objects in a visualization that runs in the Flash Virtual Machine (VM).  AppBoard does not restrict the display to certain types of Widgets. The system designer can present the data objects in whatever format will be of most value to the end-user. Typical types of widgets include the following:
[[File:appboard-2.5-widgets.png|thumb||center|720px|Wall of widgets]]


* Geographical map, displaying data overlaid on a map
== Widget Anatomy ==
* Topological map, representing the structure of a network of devices
* Data grid (Table)
* Chart
* Graph


A widget consists of the visible components, the frame, titlebar, controls, the actual content, and optionally a status-bar which allows for quick data filtering called a ''Quick Filter'' as shown in the screenshot below. The controls for a widget differ depending whether using the Viewer or Builder, the type of widget, and if any widget ''Options'' are enabled.


When creating Widgets, the design elements to consider include the following:
The layout and size of widgets is controlled by the layout manager which is part of the Board the widget is on. The spacing between widgets and the general look of widgets is controlled by the Theme manager. Finally the widget itself usually provides some configuration on the presentation of the data, such as colors for bars in a bar chart.
* Will the Widget be static or interactive?  What Actions can the user take when interacting with the data, and what will be the desired behavior of the widget upon invoking these Actions?
* Will the Widget need to interact with other Widgets?
* What data objects and attributes are needed to display the Widget?
* How should the Widget take updates when additional data becomes available?
* What are the physical dimensions and layout of the Widget?


Refer to the following pages for more detailed information on:


The following process defines the typical lifecycle of creating a Widget:
* General Configuration: see the ''Managing Widgets'' section below.
# Mock up the Widget, considering how it should display on the screen (layout, data elements, and so on).
* [[appboard/2.5/builder/widgets/list|Widget Types]]: Comprehensive list and details for each widget type
# Implement the Data Collections needed to provide data to the Widget.
* [[appboard/2.5/builder/widgets/options|Widget Options]]: These are common to most widgets and are part of the widget configuration.
# Create data filters for displaying the appropriate data in the Widget.
* [[appboard/2.5/builder/widgets/actions|Widget Actions]]: Although not immediately obvious from looking at a widget, actions are configured for mouse-click or mouse-hover events. This is where real interactivity can be built into the dashboards with in-context drill-downs, filtering, and cross-over to related proxied web applications via enPortal.
# Define events that will trigger Actions to update the data and filters.


[[File:appboard-2.5-widget-anatomy.png|frame|center|Example widget in the Builder]]


This page details how to manage Widgets, including creating, editing, or removing Widgets. Separate individual pages for each type of Widget provide additional detail for configuring the settings of that particular Widget.
=== Available Controls ===


* flip: (builder only) switch between the regular widget visualization and a table displaying the raw data.
* magnifying glass / search: ([[appboard/2.5/builder/widgets/options|option]]) toggle text search on/off.
* wrench / edit: (builder only) edit the widget configuration
* lightning bolt / actions: (builder only) edit the widget actions
* question mark / help: ([[appboard/2.5/builder/widgets/options|option]]) widget help
* download: ([[appboard/2.5/builder/widgets/options|option]]) download Data Collection.
* maximize / minimize: toggle a widget to maximize and fill the entire board and back to it's original size.
* <tt>X</tt> / delete: (builder only) delete the widget.
* <tt>>></tt> / toggle controls: (builder only) show/hide controls
* home: This is not shown in the screenshot above but the home icon is present with [[appboard/2.5/builder/widgets/web_page|Web Widgets]] only.


== Managing Widgets ==
== Managing Widgets ==


The Builder offers a ''Widgets'' mode for general widget management. From this page it's possible to view all widgets in the system, modify configuration, modify actions, move widgets from one board to another, copy, and add and delete widgets. Often however it's easier to manage widgets from the ''Builder'' mode directly on the Board. Existing widgets can be modified or deleted using the widget ''Controls'', and new widgets added using the ''Add Widget'' quick action. The advantage of using the ''Builder'' mode is widgets can also be arranged on the board, the layout tweaked, and immediately viewing the widget after making changes.


Perform the following steps to view and manage Widgets:
=== Adding / Editing Widgets ===


# Log in to AppBoard Builder as an administrator.
Use the ''Add Widget'' button when in the ''Builder'' mode to add a widget onto the current board, or the ''Add'' button when in the ''Widgets'' mode.
# In the <b>Builder Modes</b> panel, select <b>Widgets</b>. The <b>Widgets</b> panel is displayed.
# Use the "Boards" drop-down list to limit the listed Widgets to those contained on a specific Board.


== Adding Widgets ==
Editing existing widgets can be done by clicking the wrench control of a widget, or using the ''Edit'' button with a selected widget in the ''Widgets'' mode.


The Add wizard, and Edit dialog are basically the same except that the Add operation can be cancelled, while changes to existing widgets are immediate (no cancel).


Perform the following steps to add a Widget to an existing Board:
Widget configuration is split into three main sections, although depending on the widget type there may be additional sections:


# Log in to AppBoard Builder as an administrator.
* '''Data''': This step defines:
# In the <b>Builder Modes</b> panel, select <b>Widgets</b>.  The <b>Widgets</b> panel is displayed.
** '''Widget Type''': Sets or changes the type of this widget. Refer to the [[appboard/2.5/builder/widgets/list|Widget Types]] documentation information on each widget type.
# Click <b>Add</b>. The <b>Add Widget</b> wizard is displayed.
** '''Widget Name''': By default this name is used internally in the Builder as well as in the widget titlebar. However, if the ''Display Name'' is configured, then that is used in the widget titlebar instead. It is recommended to use unique and descriptive widget names. If these aren't appropriate for the widget titlebar then also set the ''Display Name''.
# Click in the <b>Widget Type</b> box to locate and select the type of Widget to create.
** '''Display Name''': optional and as described above.
#* Each available Widget Type will display icons indicating which mobile devices, if any, are supported by that Widget.
** '''Data Collection''': Set the data collection used to drive the widget. The presence of this option depends on the ''Widget Type'' as not all widgets have a directly associated data collection.
# '''Widget Name''' - Enter the name to display for the Widget in the Widget Title Bar.
* '''Visualization / ...''': Depending on the widget type at least the ''Visualization'' step will be present and optionally other steps such as ''Presentation'' etc... These steps all have to do with the specific widget type configuration. Refer to the [[appboard/2.5/builder/widgets/list|Widget Types]] documentation for detailed information on each type.
# '''Data Collection''' - Select the name of an appropriate Data Collection that will provide the data to be displayed in the Widget.
* '''Options''': Options allow for text searching, quick filters, data collection downloads, and setting widget help text. Refer to the [[appboard/2.5/builder/widgets/options|Widget Options]] documentation for more information.
#* For convenience, buttons are provided for Adding or Editing a Data Collection.
# '''Display Name''' [Optional] (new to Appboard 2.5.2) You can give a label to be displayed as the title of the widget container on the board here. If not set it will default to Widget Name. This allows you to use Widget Name to describe the context and usage of the widget and show something else as the Title.
# [Optional] For some Widgets, a button is provided to configure an [[appboard/2.5/builder/configure_alternate_widget|Alternate Widget]] to be displayed on mobile devices, if the Widget is only supported for display in the desktop AppBoard Viewer.  
# Configure the '''Visualization''' and '''Options''' for the Widget. See the individual Widget documentation page to learn about the settings available for the selected Widget type.
# Click <b>Finish</b>.
# In the <b>Builder Modes</b> panel, select <b>Builder</b> and navigate to the appropriate Board to observe the new Widget.


== Editing Widgets ==
=== Actions ===


Refer to the [[appboard/2.5/builder/widgets/actions|Widget Actions]] page.


Perform the following steps to edit an existing Widget:
=== Deleting Widgets ===


# Log in to AppBoard Builder as an administrator.
Deleting widgets can be performed by using the widget <tt>X</tt> control in the ''Builder'' mode, or using the ''Delete'' button with a selected widget in the ''Widgets'' mode.
# In the <b>Builder Modes</b> panel, select <b>Widgets</b>.  The <b>Widgets</b> panel is displayed.
# Select a Widget and then click <b>Edit</b> to view the Widget's configuration.
# Modify the Data, Visualization, and Options for the Widget. See the individual Widget documentation page to learn about the settings available for the selected Widget type.
# Click <b>Close</b>.
# In the <b>Builder Modes</b> panel, select <b>Builder</b> and navigate to the appropriate Board to observe the updated Widget.


=== Moving Widgets ===


=== Changing a Widget Type ===
This refers to moving widgets from one Board to another. For actual placement of a widget on a board then refer to the [[appboard/2.5/builder/layout|Board Layout]] documentation.


Perform the following steps to change the type of a Widget:
To move a widget you must be in the ''Widgets'' mode. Clicking in the ''Board'' column for a particular widget will allow the Board to be changed via a drop-down selection. After moving a widget it is recommended to visit both the original and target boards in the ''Builder'' mode to adjust the layout to suit.


# Follow the steps outlined above under Editing Widgets to launch the Edit Widget Wizard.
=== Copying Widgets ===
# On the '''Data''' tab, select a different Widget Type.


Copying a widget will copy the widget, all actions, and optionally the Data Collection used by the widget. Use the ''Copy'' button with a widget selected when in the ''Widgets'' mode to perform a copy. The following fields are presented:


Where possible, AppBoard will retain the Actions, Options, Data Collection, and Filter Rules that were previously configured for the Widget.   There is no intelligent mapping of configuration options from one type to another, so you should expect to re-do some of the Widget configuration after changing a Widget's type.
* '''Name''': defaults to the existing name, can be modified
* '''Board''': where the copy should reside
* '''Use Existing Data Collection / New Data Collection''': toggle to determine whether copies of the data collection should also be made.
* '''Names Alterations''': these options are only available if ''New Data Collection'' is selected above. It allows for either a prefix and/or a suffix to be added to the data collection name.


== Copying Widgets ==
Certain configuration remains global and shared even if a copy is performed, in particular:


The Copy feature allows administrators to replicate one Widget at a time via the Widgets page.
* Icon, Color, Shape, and Colored Shape Filters
 
* Diagrams: Diagrams themselves are global, the Diagrammer widget is used to show and modify diagrams.
 
* Relationship Models
Perform the following steps to copy an existing Widget:
 
# Log in to AppBoard Builder as an administrator.
# In the <b>Builder Modes</b> panel, select <b>Widgets</b>.  The <b>Widgets</b> panel is displayed.
# Select a Widget and then click <b>Copy</b>.  The <b>Copy Widget</b> dialog is displayed.
# Enter the following information to create the new Widget:
## <b>Name</b>: The name to give to the new Widget
## <b>Board</b>: Select the name of Board on which to place the new Widget
## Data Collection Selector:
### <b>Use Existing Data Collection</b> - The new Widget will use the same Data Collection as the source Widget
### <b>New Data Collection</b> - The new Widget will have a new Data Collection that will be auto-generated by AppBoard
#### <b>Add a Prefix</b>: Check the box and enter the name of a prefix to add at the beginning of the old Data Collection name when generating the name of the new Data Collection
#### <b>Add a Suffix</b>: Check the box and enter the name of a suffix to add at the end of the old Data Collection name when generating the name of the new Data Collection
#### If neither "Add a Prefix" nor "Add a Suffix" are checked, the new Widget will use a new Data Collection with the same name as the Data Collection used by the source Widget
# Click <b>Copy Widget</b> to create the new Widget that is a copy of the original Widget.
 
 
The following settings are shared between copied Widgets (all other settings are replicated per Widget):
* [[appboard/2.5/builder/icon_filter|Icon Filters]]
* [[appboard/2.5/builder/colored_shape_filter|Colored Shape Filters]]
* [[appboard/2.5/builder/color_filter|Color Filters]]
* Diagram (Diagrammer Widget)
* Relation Models (used in Topologies)
 
== Adding and Editing Actions ==
 
 
Perform the following steps to add or edit actions on a currently existing Widget:
 
# Log in to AppBoard Builder as an administrator.
# In the <b>Builder Modes</b> panel, select <b>Widgets</b>.  The <b>Widgets</b> panel is displayed.
# Select a Widget and then click '''Actions'''.  The Actions panel for that Widget is displayed.
# To add an Action, click the '''Add Action''' button.  To edit an Action, click on any of the configured fields in a currently existing Action and make the desired changes.  Actions can be deleted by clicking the red X icon for the corresponding action.
# Click '''Close''' when finished.
 
== Removing Widgets ==
 
 
A Widget must always be tied to a specific Board. So when removing a Widget from a Board, you have two options:
 
# Move the Widget to another Board
# Delete the Widget from AppBoard
 
 
===Moving a Widget To Another Board===
 
 
Perform the following steps to move a Widget to another Board:
 
 
# Log in to AppBoard Builder as an administrator.
# In the <b>Builder Modes</b> panel, select <b>Widgets</b>. The <b>Widgets</b> panel is displayed.
# Click in the <b>Board</b> column for the Widget and select from the drop-down list the name of the Board to which you want to move the Widget.
 
===Deleting a Widget From AppBoard===
 
 
Perform the following steps to delete a Widget from AppBoard:
 
 
# Log in to AppBoard Builder as an administrator.
# In the <b>Builder Modes</b> panel, select <b>Builder</b>.
# Navigate to the Board displaying the Widget that you want to remove.
# Click the "X" in the upper-right corner of the Board. The message is displayed: "Are you sure you want to remove the widget?  This action cannot be undone.".
# Click <b>OK</b>.  The Widget is deleted from AppBoard.
 
 
{{Note|An alternative to the above is to select the Widget and click <b>Delete</b> in the Widgets panel.}}


== Related Topics ==
== Related Topics ==


* [[appboard/2.5/builder/widgets/list|Widget Types]]
* [[appboard/2.5/builder/widgets/actions|Widget Actions]]
* [[appboard/2.5/builder/widgets/options|Widget Options]]
* [[appboard/2.5/mobile/widget_support|Mobile Widget Support]]
* [[appboard/2.5/mobile/widget_support|Mobile Widget Support]]
* [[appboard/2.5/builder/stacks_and_boards|Stacks & Boards]]

Latest revision as of 06:33, 5 November 2014

HeaderFlow05.png

Overview

Widgets are used to present data in different ways, and are also the primary mechanism to interact with data through the use of Actions. Widgets are arranged onto Boards that control layout, and Boards are organized into Stacks that are used as the primary navigation element and also tied to provisioning content.

AppBoard offers a wide variety of widgets along with an API to write custom HTML widgets, and the ability to bring in external web content through enPortal. The screenshot below shows a broad cross section of widgets shipped with AppBoard:

Wall of widgets

Widget Anatomy

A widget consists of the visible components, the frame, titlebar, controls, the actual content, and optionally a status-bar which allows for quick data filtering called a Quick Filter as shown in the screenshot below. The controls for a widget differ depending whether using the Viewer or Builder, the type of widget, and if any widget Options are enabled.

The layout and size of widgets is controlled by the layout manager which is part of the Board the widget is on. The spacing between widgets and the general look of widgets is controlled by the Theme manager. Finally the widget itself usually provides some configuration on the presentation of the data, such as colors for bars in a bar chart.

Refer to the following pages for more detailed information on:

  • General Configuration: see the Managing Widgets section below.
  • Widget Types: Comprehensive list and details for each widget type
  • Widget Options: These are common to most widgets and are part of the widget configuration.
  • Widget Actions: Although not immediately obvious from looking at a widget, actions are configured for mouse-click or mouse-hover events. This is where real interactivity can be built into the dashboards with in-context drill-downs, filtering, and cross-over to related proxied web applications via enPortal.
Example widget in the Builder

Available Controls

  • flip: (builder only) switch between the regular widget visualization and a table displaying the raw data.
  • magnifying glass / search: (option) toggle text search on/off.
  • wrench / edit: (builder only) edit the widget configuration
  • lightning bolt / actions: (builder only) edit the widget actions
  • question mark / help: (option) widget help
  • download: (option) download Data Collection.
  • maximize / minimize: toggle a widget to maximize and fill the entire board and back to it's original size.
  • X / delete: (builder only) delete the widget.
  • >> / toggle controls: (builder only) show/hide controls
  • home: This is not shown in the screenshot above but the home icon is present with Web Widgets only.

Managing Widgets

The Builder offers a Widgets mode for general widget management. From this page it's possible to view all widgets in the system, modify configuration, modify actions, move widgets from one board to another, copy, and add and delete widgets. Often however it's easier to manage widgets from the Builder mode directly on the Board. Existing widgets can be modified or deleted using the widget Controls, and new widgets added using the Add Widget quick action. The advantage of using the Builder mode is widgets can also be arranged on the board, the layout tweaked, and immediately viewing the widget after making changes.

Adding / Editing Widgets

Use the Add Widget button when in the Builder mode to add a widget onto the current board, or the Add button when in the Widgets mode.

Editing existing widgets can be done by clicking the wrench control of a widget, or using the Edit button with a selected widget in the Widgets mode.

The Add wizard, and Edit dialog are basically the same except that the Add operation can be cancelled, while changes to existing widgets are immediate (no cancel).

Widget configuration is split into three main sections, although depending on the widget type there may be additional sections:

  • Data: This step defines:
    • Widget Type: Sets or changes the type of this widget. Refer to the Widget Types documentation information on each widget type.
    • Widget Name: By default this name is used internally in the Builder as well as in the widget titlebar. However, if the Display Name is configured, then that is used in the widget titlebar instead. It is recommended to use unique and descriptive widget names. If these aren't appropriate for the widget titlebar then also set the Display Name.
    • Display Name: optional and as described above.
    • Data Collection: Set the data collection used to drive the widget. The presence of this option depends on the Widget Type as not all widgets have a directly associated data collection.
  • Visualization / ...: Depending on the widget type at least the Visualization step will be present and optionally other steps such as Presentation etc... These steps all have to do with the specific widget type configuration. Refer to the Widget Types documentation for detailed information on each type.
  • Options: Options allow for text searching, quick filters, data collection downloads, and setting widget help text. Refer to the Widget Options documentation for more information.

Actions

Refer to the Widget Actions page.

Deleting Widgets

Deleting widgets can be performed by using the widget X control in the Builder mode, or using the Delete button with a selected widget in the Widgets mode.

Moving Widgets

This refers to moving widgets from one Board to another. For actual placement of a widget on a board then refer to the Board Layout documentation.

To move a widget you must be in the Widgets mode. Clicking in the Board column for a particular widget will allow the Board to be changed via a drop-down selection. After moving a widget it is recommended to visit both the original and target boards in the Builder mode to adjust the layout to suit.

Copying Widgets

Copying a widget will copy the widget, all actions, and optionally the Data Collection used by the widget. Use the Copy button with a widget selected when in the Widgets mode to perform a copy. The following fields are presented:

  • Name: defaults to the existing name, can be modified
  • Board: where the copy should reside
  • Use Existing Data Collection / New Data Collection: toggle to determine whether copies of the data collection should also be made.
  • Names Alterations: these options are only available if New Data Collection is selected above. It allows for either a prefix and/or a suffix to be added to the data collection name.

Certain configuration remains global and shared even if a copy is performed, in particular:

  • Icon, Color, Shape, and Colored Shape Filters
  • Diagrams: Diagrams themselves are global, the Diagrammer widget is used to show and modify diagrams.
  • Relationship Models

Related Topics

Retrieved from "http://ab.edge-technologies.com/docs/index.php?title=Appboard/2.5/builder/widgets&oldid=6411"