SPARK UI Toolkit
The SPARK User Interface (UI) Toolkit is an IBM BPM UI toolkit created by Salient Process, a Premier IBM Business Partner specializing in IBM Smarter Process consulting services and innovation.
IBM and Salient Process have partnered to make the SPARK UI Toolkit the UI toolkit of choice for IBM BPM customers. There are already efforts underway to incorporate the SPARK UI Toolkit into the IBM BPM product. For more information about this partnership and future plans for the SPARK UI Toolkit and IBM BPM UI, see 4.2, “Understanding the IBM and Salient Process partnership” on page 156.
This chapter includes the following topics:
4.1 Introduction
The SPARK UI Toolkit enhances and streamlines the BPM UI creation process. It does so with controls and familiar UI development patterns that let UI developers focus more directly and efficiently on business problems.
This chapter provides a detailed introduction to key concepts, capabilities, and controls in the SPARK UI Toolkit.
Core concepts are described in 4.3, “Basic BPM UI concepts with SPARK” on page 157. The section builds upon that foundation to a full explanation of developing UI with the SPARK UI toolkit.
|
Note: As a UI developer, you are encouraged to read this chapter in its entirety to become expert in the use of the SPARK UI Toolkit. It is recommended that all developers using SPARK read, at a minimum, 4.3, “Basic BPM UI concepts with SPARK” on page 157 to take advantage of key benefits of the SPARK UI Toolkit.
|
4.1.1 Understanding the value of the SPARK UI Toolkits
The SPARK UI Toolkit offers the following benefits:
•Increases UI developer productivity up to three to four times faster than using traditional methods and decreases maintenance costs by avoiding UI complexity.
•Achieves the productivity increase through an efficient and intuitive development experience in combination with reduced skills expectations (primarily JavaScript, limited HTML or CSS, and no Dojo, AJAX, RWD, jQuery, or AngularJS required).
•Provides 90+ responsive and configurable controls, which can adapt to the form factor of the device running the coach and are suitable for both production and fast-build proof-of-concept scenarios.
•Includes, with every control, a simple and powerful event-based framework that creates a consistent approach for validation, formula-based computations, and cross-control interaction.
•Optimizes UI performance by using controls that support lazy loading and server-side pagination that can support complex UIs and large tabular data sets.
The SPARK External Participant Toolkit can extend the reach of IBM BPM to include external participants. For more information, see 6.3.1, “Expose human services indirectly through the EPS toolkit” on page 347.
The SPARK Portal Builder Toolkit provides a set of simple portal controls that build dashboards and custom portals including a Get Next Task capability. For more information, see 5.2.9, “SPARK Portal Builder toolkit” on page 305.
4.1.2 Developer experience
You can use the 90+ controls in the SPARK UI Toolkit to address a broad range of UI requirements. Though the core set of controls is relatively small (around 25), other more specialized controls (for example, Map, Slider, Signature, Video, Pop-up Menu, and Tooltip) help efficiently address more sophisticated UI requirements.
Detailed documentation and how-to articles are available at the following website for all SPARK UI Toolkit controls:
You can take advantage of patterns and capabilities that currently exist as preferred practices for IBM BPM UI development, as described in Chapter 2, “Creating user interfaces with coaches” on page 9. However, the SPARK UI Toolkit extends and streamlines the Coach Framework programing model in the following significant ways:
•Controls on a page or a view can easily refer to and talk to each other.
•Each control can react to all kinds of events, such as on click, on key press, on tab change, on timeout, on row deleted, and so on. Business logic can intuitively be expressed and attached to those events to create an interactive user experience.
•Reliance on data binding is optional. This eliminates complexity and glue artifacts commonly associated with BPM UIs. A data binding is only needed when a control must synchronize with meaningful business data.
•The enhanced SPARK UI development approach is designed after a well known effective and efficient development model of controls composed on a canvas with properties, methods, and events. The complexity stops there and all properties, methods, and events are well documented per control.
•When the values of controls and fields on a form are computationally related (whether numerical or not), spreadsheet formulas can be used to save time. These formulas automatically calculate and update values (in single fields or tables) on a page or view without you having to write code.
|
Note: BPM UI development can become more effective and efficient by exploiting the Coach Framework programming model enhancements provided by the SPARK UI Toolkit. The resulting solutions are consistently more lightweight, more maintainable, and more reusable.
|
4.1.3 Underlying patterns and principles
A foundational principle underlying the SPARK UI Toolkit is that it allows the developer to focus on solving business problems efficiently: you do not need to learn another complex JavaScript library or framework. With the SPARK UI Toolkit, you do not have to delve into the internal aspects of controls, duplicate assets, or create large amounts of glue constructs. There is no need to part with well-understood and intuitive UI development approaches.
|
Note: To use the SPARK UI Toolkit effectively, a you becomes familiar with the following four core patterns:
•Configuring controls
•Referencing and calling other controls
•Attaching logic to events
•Using formulas
These patterns are described in this chapter.
|
With an understanding of the four core SPARK UI patterns, you only have to look up the capabilities of controls and exploit those capabilities to implement business requirements. These controls include configuration options, events, and methods that you might not have used before. Because all controls follow a strictly consistent approach across the four core patterns, gaining familiarity with a new control is a simple and predictable experience.
4.1.4 Modern, lightweight, consistent across BPM versions
With few exceptions (for example charting or maps), the SPARK UI Toolkit has no dependencies on extensive libraries and frameworks beyond the Coach Framework, HTML5, and CSS3.
This makes the toolkit extremely lightweight with controls that are inherently optimized to work with IBM BPM and the underlying Coach Framework. It also virtually eliminates reliance on thick layers of additional library or framework-specific processing and previous generation cross-compatibility behaviors.
The explicit HTML5 and CSS3 dependency, however, requires the use of a modern browser with comprehensive support for HTML5 and CSS3 such as Chrome, Firefox, Internet Explorer 11+, or Safari.
HTML5 and CSS3 support requirements for SPARK are more stringent than IBM BPM requirements. For example, whereas Internet Explorer 9 support is only deprecated for IBM BPM 8.5.7, it is not supported for the SPARK UI toolkit from IBM BPM 8.5.0.1 and up.
|
Note: The SPARK UI Toolkit requires a web browser with comprehensive support for HTML5 and CSS3.
|
IBM BPM is a constantly evolving platform. The introduction of new features can be valuable to some and disruptive to others, especially when a new feature entails the deprecation of an older feature.
SPARK takes full advantage of the latest IBM BPM product capabilities. For example, SPARK-based UIs in client-side human services (CSHS) can use the full SPARK programming model directly from client-side scripts to access page controls and manipulate them. The toolkit also attempts to normalize the experience across BPM product versions.
The cross-version normalization is done by relying on constructs that remain consistent from one product version to the next (for example SPARK-based UIs can be virtually Heritage- or CSHS-agnostic). By design, the toolkit works consistently across BPM 8.5.0.1 through BPM 8.5.7 and is jointly planned by IBM and Salient Process to be fully incorporated into the IBM BPM product.
4.2 Understanding the IBM and Salient Process partnership
In June of 2016, IBM announced a partnership with Salient Process to license the SPARK toolkits with the objective of incorporating the SPARK UI toolkit features into the IBM BPM Platform. More information about that partnership, including how you can order SPARK through IBM, can be found in the following IBM announcement:
4.3 Basic BPM UI concepts with SPARK
This section presents key concepts that are specific to the SPARK UI Toolkit and can help you use the toolkit effectively and efficiently.
4.3.1 Controls and configuration properties
Control configuration, the most basic aspect of SPARK controls, is common with most other Coach Framework-based coach views. Figure 4-1 shows that it is also accessed in IBM Process Designer.
Figure 4-1 General SPARK control configuration
Common configuration categories
Many aspects of a control’s appearance, behavior, and other runtime characteristics can be specified through configuration (and can be changed later at run time). For consistency in the UI development experience, most configuration options are grouped under consistent categories, such as:
•Formula: Used for the value computation of the control. For more information about formulas, see 4.9, “Formulas” on page 225.
•Behavior: Includes general behavior-related control-specific options.
•Appearance: Includes options such as styling, coloring, layout, typography, and labeling.
•Performance: Includes options to manage processing-intensive behaviors in repeating controls, such as tables and layouts for large data sets.
•Responsive: Includes view width-sensitive settings that automatically adjust layout and appearance of a control based on the view that contains it. Note that conventional page width-based adaptive configuration options are also available through the IBM Process Designer web editor.
•Events: Used to attached logic to various events specific to a control. For more information about formulas, see “Events” on page 161).
Figure 4-2 is an example of common configuration categories for a Button control.
Figure 4-2 Extensive style configuration options example
4.3.2 Methods, events, and addressing
SPARK UI controls on a page or in views can access each other and call methods on other controls. They can also respond to events triggered programmatically or by user interactions (for example, button clicks, tabs changed, keys pressed, or data changed). The combination of event triggers, the ability to refer to other controls and to call various methods on those controls, provides a simple mechanism to create sophisticated behaviors.
Example 4-1 shows how a developer can change the text content of an Output Text control from a Button control on-click event.
Example 4-1 Addressing controls and calling methods
//Use button label to set content of the text control
text1.setText("Text set from button: " + button1.getText());
Example 4-1 is intuitive to UI developers because it is simple, familiar, and focuses on the problem. In that example, in the on-click event of a button can access another control and make it do things using calls to methods.
Methods
All SPARK controls have methods, such as Getters, setters, and various action methods. For example, these methods allow you to change the color of a button, set the title of a panel, expand a collapsible section, refresh a table backed by AJAX, make an image visible, and so on.
Example 4-2 shows how some methods abstract certain Coach Framework-specific constructs.
Example 4-2 How SPARK methods relate to Coach Framework methods
button1.setVisible(false)
…has precisely the same effect as
button1.context.options._metadata.visibility.set("value", "NONE")
Or
text1.setText("Text set from button: " + button1.getText())
…behaves exactly like
text1.context.binding.set("value", "Text set from button: " + button1.context.binding.get("value"))
Other methods are specific to particular SPARK controls and have no counterpart in the Coach Framework, as shown in Example 4-3.
Example 4-3 Control methods unique to the Coach Framework SPARK UI extensions
table1.search(0, "Acme", false, true)
The method in Example 4-3 displays only rows in a table control where the first column (at index 0) contains the string "Acme".
All SPARK controls provide documented methods and can be accessed from the SPARK support site. For information about a specific method, click the JS Doc link on the following web site:
Figure 4-3 shows methods for the Button control.
Figure 4-3 Online documentation for control methods
Common methods for all controls
Certain methods are common to all SPARK controls, Table 4-1 lists common SPARK control methods.
Table 4-1 Common SPARK control methods
|
Method
|
Description
|
|
setVisible(visible, collapse)
|
Sets view visibility. The collapse flag determines whether the space occupied by the hidden view is collapsed or displays as blank space.
For controls that have no visual representation (such as the Event Subscription control).
|
|
isVisible()
|
Indicates whether a view is visible or not.
|
|
setEnabled(enabled)
|
Turns a view’s editable state on or off (assuming the control supports such a state).
|
|
isEnabled()
|
Indicates whether a view is enabled or not.
|
|
isBound()
|
Indicates whether a view is bound to data or not.
|
|
setData(data)
|
Equivalent to context.binding.set("value", val).
Some controls provide more specialized methods such as setText() for a Text control or setDate() for a Date Picker control. Note that those methods are only aliases of setData.
|
|
getData()
|
Equivalent to context.binding.get("value").
Some controls provide more specialized methods such as getText() for a Text control or getDate() for a Date Picker control. Note that those methods are only aliases of getData.
|
|
addClass(added, replaced)
|
Adds, replaces, or removes a CSS class from the coach view top-level DOM element (referenced by context.element).
Added is a string with zero or more space-delimited CSS class names to add to the view.
Replaced is a string with zero or more space-delimited CSS class names to remove and replace with the added class names.
To remove a CSS class from a view, specify two quotation marks ("") for added and the class names to remove for replaced.
|
Events
Events are key to interactivity in the SPARK UI Toolkit. They allow controls to respond to user, device, and various programmatic triggers.
The following actions are triggered by events:
•An alert displayed when a button is clicked
•Validation performed when an item in a drop-down list is selected
•An AJAX service fetching data when a collapsible panel is expanded
•A chart refreshed when a pop-up menu item is tapped
•A label updated with a new value every time a timer ticks
•A table that filters its content when a user types search text
•An output text displaying a result when an AJAX service returns
All SPARK control events are exposed in a similar way in the Events category of the control's configuration. Figure 4-4 provides an example of a button that shows an alert saying “Hello” and using the name of a person entered in the text control.
Figure 4-4 Specifying logic in a button click event
For a more compact and convenient notation in inline event logic, SPARK UI controls can be referred to in shorthand using the ${<control-id>} notation. The inline event logic can be rewritten as the notation shown in Figure 4-5.
Figure 4-5 Shorthand notation for control references in inline event logic
|
TIP: Do not confuse the ${control-id} reference lookup notation with the jQuery $("<selector>") notation. The SPARK UI Toolkit does not depend on jQuery, though it can coexist with it.
Note: The SPARK ${ } notation is only valid when used in inline event logic. Proper syntax expects curly braces only and does not use quotes for the control-id reference lookup notation. The ${PersonName} notation is valid, whereas ${"PersonName"}, $(PersonName), or $("PersonName") are not valid.
|
Events and Coach Framework boundary events
Buttons, icons, and other controls emit boundary events when clicked or otherwise activated. For most of those controls, the events fired before emitting the boundary event, such as on button click, can inhibit the boundary event by explicitly returning false.
In Figure 4-6, the boundary event inhibitor pattern provides a convenient way to add confirmation before navigating away from a coach.
Figure 4-6 Boundary event inhibitor pattern (design time)
Figure 4-7 shows the resulting runtime behavior.
Figure 4-7 Boundary event inhibitor pattern (runtime behavior)
Event context variables
Sometimes context is important when handling events. For example, a Text control might need to restrict the length of the content or the input of certain characters or values. To do this the input event logic examines the attempted input, passed in the on input event as a context variable, before allowing or not allowing the new potential content.
Figure 4-8 illustrates how to implement this scenario.
Figure 4-8 Text “On Input” event using context variable
Table 4-2 shows the context variables that the Text > On Input event provides to the inline event logic.
Table 4-2 Content variables for the Text > On Input event
|
Variable Name
|
Description
|
|
me
|
Similar to the this concept: Refers to the control that emitted the event.
|
|
view
|
Refers to the control's first parent view that is not only decorative. Often this means the composite coach view that contains the control.
|
|
current
|
Text content in the control before the change from the input.
|
|
potential
|
Attempted content. This becomes the new text content unless the logic returns false.
|
|
selection
|
Location of the cursor in text control or boundaries of the selection if the text was selected and replaced by new content.
|
The JS Doc for each control describes the methods and the events supported by the control and associated context variables as appropriate. See the JS Doc links for each control in the online SPARK control reference, which is available at:
|
Note: The me context variable is available in all events for all controls. It is a convenient reference to the control that emitted the event. The view context variable is also similarly available and points to the view containing the control.
Because these variables are common to all controls, they are not explicitly mentioned in the JSDoc as context variables.
|
Invoking non-inline event logic
Inline events are simple and convenient. If, however, IBM Process Designer only allows a single line for those events, specifying a lot of inline logic can be cumbersome.
Because inline event logic is only JavaScript at run time, functions can easily be called from an event handler. In Figure 4-9, the calculate() function, which is defined in a script block at the page level, is called on a button click.
Figure 4-9 Calling a page-level function from an event handler
|
Note: There is no limitation to the globally-defined functions and globally-accessible objects that can be called from an inline event handler. If a function requires parameters, they can be passed in regular JavaScript manner. Context event variables can also be passed to externally-defined functions.
|
A key benefit that a reusable coach view must include is the ability to encapsulate not only the child views laid out on the containing view's canvas, but also their behavior. The SPARK UI Toolkit allows a composite coach view to host the business logic that is invoked by the various controls that it contains. This ability creates a self-contained, fully encapsulated custom reusable coach view made from smaller parts.
i
|
Hint: Full coach view encapsulation, which increases reusability and maintainability, is a significant benefit of the SPARK UI Toolkit
|
Figure 4-10 shows how the Calculate button now calls a calculate() function defined in the containing [view.calculate()] composite coach view. It is located in the Inline JavaScript section of the coach view and not at the page level.
Figure 4-10 Calling a composite coach view-level function from an event handler
Figure 4-11 shows the definition of the Calculator composite coach view's calculate() function.
Figure 4-11 Defining a method at the composite coach view level
|
Note: In a simple step, nonreusable code at the page level is made reusable. The Calculator coach view relies on no external scripts or components to perform its work.
This is the fastest and most intuitive general approach to building reusable coach views.
|
Client-side script-based event logic
As described in “Events” on page 161, SPARK provides various ways of handling business logic in response to events. The most portable approach is to encapsulate the business logic in a composite coach view, as illustrated in Figure 4-11.
If, however, encapsulating logic is not important, use client-side scripts and boundary events to achieve a similar effect. This is done in a conventional Coach Framework manner and by using a part of the programming model extended by SPARK, as shown in Figure 4-12 on page 168.
Figure 4-12 Using the SPARK programming model in a client-side coach
Firing boundary events from any event handler
Figure 4-12 shows how SPARK can make use of client-side scripts in the same way as the classic Coach Framework-based approach. Not all controls fire boundary events, however, and even for those that do, a boundary event cannot always be fired by the interaction the developer needs.
SPARK overcomes this limitation by providing a way to fire boundary events for any kind of event-triggered interaction. This is done through the Navigation Event control.
Figure 4-13 on page 169 shows an adapted version of the Calculator scenario with results computed using a Navigation Event control instead of a Button. In this scenario, the calculation is triggered every time a change occurs in the operands or the operation.
Figure 4-13 Firing boundary events from SPARK event handlers
|
Note: SPARK allows you to use many boundary events to execute business logic, as shown in Example 4-14. However, boundary events can clutter the CSHS flow and are often not the best way to achieve deep reusability. Handling events at the coach-view level is more logical and easier to maintain.
You can be more productive with a less mixed SPARK approach; this approach results in a more streamlined solution.
|
Events: Summary
Handlers for a multitude of events are available on SPARK controls. Logic is run from any of those event handlers by calling methods on controls.
Event logic can be inlined or a function defined globally. Or, event logic can be called in a control's containing composite view.
Functions called in the parent composite coach view are defined in the view's Inline JavaScript section (see the coach view’s Behavior tab in IBM Process Designer), as shown in Example 4-4.
Example 4-4 Event-callable function defined in a composite coach view
this.myFunction = function(<parameters if needed>) {
/* Business logic... */
}
Example 4-5 shows how myFunction can be invoked from an event handler of the child control.
Example 4-5 Calling a function defined in a composite coach view from a control's event handler
view.myFunction(<parameters if needed>)
Controls can be referenced from event handlers using the following commands:
•The page.ui.get(<control-id>) command is at the page level or in client-side scripts.
•The this.ui.get(<control-id>) command is in functions defined in coach views (Inline JavaScript) to refer to the child views contained in the composite coach view.
•The ${<control-id>} command is used only if specifying inline event logic. The ${ } notation is translated to a real JavaScript control reference at run time).
Using the ${<control-id>} command is a convenient way to refer to controls in inline event logic. The command works consistently at the page level and in a coach view. It is recommended that you use this command.
Lastly, your practice might be to create Human Service diagrams with dense wiring and client and server scripts for business logic. However, the SPARK UI event pattern, combined with pertinent SPARK control methods, helps minimize clutter, increases reusability, and focuses the developer on solving the business problem.
|
Tip: Using SPARK controls without taking advantage of the Coach Framework programming extensions contributed by SPARK forgoes a significant productivity and simplification advantage provided by the toolkit. When you use the SPARK UI Toolkit it is important to exploit its extended programming model.
|
Control referencing
Understanding how control referencing works is an important part of using the SPARK UI Toolkit effectively.
All examples of control referencing noted thus far (such as using the ${<control-id>} commands, page.ui.get("<control-id>") or view.ui.get("<control-id>")) are straightforward. If you use SPARK and follow standard component encapsulation practices, you can be productive working with this simple addressing (in addition to working within repeating controls in tables, which is covered in 4.7, “Working tabular and repeating data” on page 211).
|
Tip: It is important to understand the structure and implications of SPARK addressing. This understanding helps you debug BPM UIs and exploit the programming model in creative ways to solve complex requirements.
|
Control referencing works like a directory tree in the SPARK UI Toolkit. However, control referencing is a view tree. The address of a view can include not only a control's ID but also indicators, such as "/", "..", "[<index>]", that help navigate the view tree like a directory structure using relative or absolute addressing.
Figure 4-14 shows the Simple Calculator coach composition.
Figure 4-14 Composition of simple and composite coach views
The UI is represented as a tree, as shown in Figure 4-15.
Figure 4-15 Control tree representation of a coach composition
Addressing in SPARK works as noted in the following list:
•A parent view that contains children controls can access its immediate children using the command:
<parent view ref>.ui.get("<child view's control id>")
•A view that needs to access a sibling can do so in two ways.
– Directly:
<view ref>.ui.getSibling("<sibling view's control id>");
– Or through its parent view:
var parent = <view ref>.ui.getParent();
parent.ui.get("<child view's control id>")
|
Recap: A parent (composite) view (view1) can access an immediate child with the view1.ui.get("<child control-id>") command. A view (view2) can access a sibling using the view2.ui.getSibling("<child control-id>") command.
|
Understanding inline event handlers and ${<control-id>} references
When the inline logic of a control's event handler refers to a control ID, for example ${Text1}, the query is always done from the context of the parent view (or the context of the coach if there is no parent view), and not from the event's own emitting view.
At run time, the ${Text1} reference from the event handler's inline logic translates to me.ui.getParent().ui.get("Text1").
|
Note: An inline event handler, though associated with a control, runs in the context of the control's parent composite view (or the coach if there is no containing composite view). Use the me context variable to refer to the control emitting the event and the view context variable to refer to the parent composite view.
|
Special case for cosmetic controls
If the coach, or coach view composition, is arranged like a tree with parents and siblings (and descendants) the addressing scheme can break by moving controls around to different levels of the tree.
For example, after having created logic between a Button and a Text control (Id: Text1), the reference to Text1 control breaks if moved in a Panel control (Id: Panel1) for cosmetic reasons and the reference must changed from ${Text1} to ${Panel1/Text1}.
To prevent such problems, most container controls in SPARK whose purpose is to group or arrange or wrap around other controls are purposely not considered in the addressing hierarchy. Examples include panels, layouts, tab section, wells, and input groups. This flattens the view hierarchy, depending on how many cosmetic-only controls are present in a UI and how much they are nested. It also solves the problem of potential reference breakage from visual control rearrangements.
Figure 4-16 shows the coach view tree from Figure 4-15 on page 171 when adjusted to account for SPARK's handling of cosmetic coach views.
Figure 4-16 Control tree representation adjusted for cosmetic-only controls
Table 4-3 provides the list of controls that are considered cosmetic for SPARK UI addressing.
Table 4-3 List of cosmetic SPARK controls (not inserted in a control’s addressing path)
|
Control
|
Notes
|
|
Caption Box
|
Caption Box is a container that wraps around a control to add a label or caption around it.
|
|
Collapsible Panel
|
|
|
Deferred Section
|
|
|
Horizontal Layout
|
Unless bound to a list, which makes it a repeating container.
|
|
Input Group
|
Input group is a container that wraps around a control to add a button or icon to the left or right of the control.
|
|
Modal Section
|
|
|
Page Layout Row
|
Deprecated after IBM BPM 8.5.0.1.
|
|
Page Layout Column
|
Deprecated after IBM BPM 8.5.0.1.
|
|
Page Layout Cell
|
Deprecated after IBM BPM 8.5.0.1.
|
|
Panel
|
|
|
Panel Header
|
|
|
Panel Footer
|
|
|
Popup Menu
|
Popup menu is a container that wraps around a control to add a pop-up menu to it.
|
|
Stack
|
Stack is like a tab section without any tabs or decorations around it. It only show one pane at a time.
|
|
Status Box
|
Status Box is a container that wraps around a control to add a status message bubble under it.
|
|
Tab Section
|
|
|
Table Layout
|
Deprecated after IBM BPM 8.5.6.
|
|
Table Layout Row
|
Deprecated after IBM BPM 8.5.6.
|
|
Table Layout Cell
|
Deprecated after IBM BPM 8.5.6.
|
|
Tooltip
|
Tooltip is a container that wraps around a control to add a tooltip to it.
|
|
Vertical Layout
|
Unless bound to a list, which makes it a repeating container.
|
|
Well
|
|
|
Note: The control ID of Horizontal and Vertical Layout containers becomes part of the address of the child controls they contain if the layouts are bound to a list. A layout is bound to a list if they layout is configured as repeating containers.
|
Accessing controls in repeating containers
The Table control in the SPARK UI Toolkit is an example of a repeating control. At design time, only the first row is visually modeled. For example, a Table control (Id: Table1) might contain a Text control (Id: Text1) and a Button control (Id: Button1).
In the most use cases, there are three consistent patterns that control referencing needs to support. The following examples refer to a Table control, but control addressing must behave similarly for any repeating container:
•From outside of a table, a control needs to access a control that is in a table by control ID and by row index.
•From inside of a table, a control in a table column needs to access a control in another column but in the same row.
•From inside of a table, a control in a row needs to update a control outside of the table.
Figure 4-17 shows the inline logic of an on-click event to update the Text control in the fourth row of the table.
Figure 4-17 Event referring to nth repeating Text control in table
The example in Figure 4-18 shows how a control can access another one in the same row.
Figure 4-18 Event referring to Text control in table in same row as control emitting event
The runtime behavior of the examples in Figure 4-17 and Figure 4-18 is shown in Figure 4-19 on page 176.
Figure 4-19 Control addressing and events with repeating table, runtime behavior
|
Note: Achieving the same behavior, as shown in Figure 4-19, without SPARK addressing using classic Coach Framework capabilities requires a more complicated and cumbersome approach. This approach uses wrapper composite coach views.
|
The third example in Figure 4-20 on page 177 shows how a control in a table can refer to another control outside the table using relative addressing.
Figure 4-20 Event referring to Output Text control outside of table
Figure 4-21 shows the runtime result for the third example in Figure 4-20.
Figure 4-21 Control addressing from inside to outside of repeating table, runtime behavior
|
Tip: In the event handler of a repeating control, the me.ui.getIndex() command provides an easy way to determine the row or list index of the control whose event fired.
|
|
Tip: Using relative addressing is a better practice than using absolute addressing, especially within a composite coach view. Absolute addressing often requires the logic of a composite coach view to know details about the naming and structure of its parent. That logic can be altered by other UI developers and break absolute references.
|
More information about tables and repeating containers is covered later in this chapter (see 4.7, “Working tabular and repeating data” on page 211). This section addresses only the topic of typical addressing usage with repeating content.
4.3.3 Optional data binding
Data binding to controls is a valuable and convenient capability. It allows controls bound to data either through data binding or through configuration options to automatically synchronize their state based on the bound business data and vice versa. This capability is provided by the Coach Framework ready for use. The majority of SPARK UI controls also support this capability.
Most SPARK UI controls, however, work almost identically whether they are bound to business data or not. They do not need to be bound to data to be functional. This allows the UI developer to only use business data structures for business data purposes. There is no need for data holder structures (Business Objects) whose primary purpose is often to only back UI control states, even when those controls do not represent a meaningful business or process data concept. This can significantly reduce solution clutter and allows reusable coach views to have less external dependencies to function properly.
When a SPARK UI control is not bound to data, all its methods work as though it were bound to data, but no data synchronization occurs. In either case, all SPARK UI controls support the methods shown in Table 4-4.
Table 4-4 Data-related methods for SPARK controls
|
Method name
|
Description
|
|
getData()
|
Same as context.binding.get("value").
|
|
setData(val)
|
Same as context.binding.set("value", val).
|
|
isBound()
|
Indicates if the control has a real binding from IBM BPM or a synthetic binding from SPARK.
|
|
Note on aliases: Many controls provide more intuitive aliases to the getData or setData commands, for example getText or setText for the Text control, getDate or setDate for the Date Picker control, and so on. Regardless, the getData and setData commands always work on controls.
|
|
Tip: Only use data bindings to update or react to changes in legitimate business data that is part of the human service.
|
Data change events without a data binding
Many SPARK controls provide support for a change event. The change event works the same way even if the control is not bound to data, as shown in Figure 4-22.
Figure 4-22 Data change events for bound or unbound controls
4.3.4 Validation
All SPARK UI control types that support validation visually reflect an invalid state. However, SPARK controls that support validation do not strictly depend on the conventional Coach Framework-based validation approach described in 2.7, “Adding validation to a coach” on page 39. However, the controls behave as expected with conventional validation.
The SPARK UI Toolkit and its controls provide support for combinations of the following types of validation behaviors:
1. Incorrect input is prevented in the first place. In this case, the control is never in an invalid state.
2. A control allows invalid input but flags the issue during typing.
3. A control allows invalid input but flags the issue after it loses focus.
4. Some controls contain invalid input, but submission is prevented until errors are resolved.
5. Some controls contain invalid input, and issues are flagged after submission.
Client-side validation is well-suited for cases 1, 2, 3, and 4, assuming the validation needed does not rely on server-side rules. Server-side validation, including AJAX-based validation, can also work well for cases 3, 4, and 5.
Client-side validation
Client-side validation means that logic can be triggered to examine the content of one or more controls as content changes. Then validation errors can be flagged on one or more controls in the composite view containing the controls or on the entire coach.
Figure 4-23 shows how the simplest kind of client-side validation can give user feedback as content is typed or as the control loses focus.
Figure 4-23 Validation error reported on a Text control
Figure 4-24 shows how this kind of behavior can be modeled with a regular expression on the Text control.
Figure 4-24 Example of validation through regular expression on Text control
|
Note: In the context of text validation, a regular expression is a character pattern that defines the allowable format, characters, numbers, or symbols that can be entered in the field. For more information about regular expressions, see the regular expression website:
|
Other controls such as Masked Text provide build-in capabilities to restrict typed content through input masks, as shown in Figure 4-25 on page 181.
Figure 4-25 Example of validation enforcement with Masked Text control
Programmatic validation
Although configuration-time validation can be useful, the most flexible type of validation is programmatic. Table 4-5 lists the four methods provided by the extended SPARK programming model to assist with client-side validation behavior.
Table 4-5 Client-side validation-related methods for SPARK
|
Method name
|
Description
|
|
<view>.setValid(
flag,
errorMessage
)
|
Sets the client-side validation state of a control. If not valid, the error shown in the validation error tooltip can be specified.
|
|
<view>.isValid()
|
Queries if a control is in a valid state.
|
|
bpmext.ui.getInvalidViews(
fromView
)
|
Retrieves a list of invalid views (optionally under a particular view). If there are no validation errors, the method returns an empty list or array.
|
|
bpmext.ui.getRequiredViews(
onlyEmtpy,
fromView
)
|
Retrieves a list of required views (optionally under a particular view). The onlyEmpty flag filters out views whose binding data is set. If no matching views are found, the method returns an empty list or array.
|
The setValid() method can be used to set or unset the valid state on any view that supports the concept of a valid state. In Figure 4-26 on page 182, logic runs when the Decimal control value changes and shows an error if the validation test fails.
Figure 4-26 Using the setValid() method for client-side programmatic validation
|
Note: The decision for where validation logic is run (that is, on the client or on the server) must be carefully evaluated and made by the solution architect. The SPARK UI Toolkit provides streamlined support for both scenarios.
|
The next validation scenario is identical to the previous except that the validation logic runs in an AJAX service. The AJAX service invocation is done through the Service Call SPARK control.
Instead of calling the validation logic locally, the Amount Decimal's on change event invokes the Validation Service Call control. The call control invokes the server-side validation logic. After the AJAX service returns, the on result or on error event of the Service Call control is asynchronously triggered. The event then sets the Amount Decimal's validation state accordingly. See the interaction sequence in Figure 4-27 on page 183.
Figure 4-27 Using the setValid() method along with Service Call control and AJAX-based validation
|
Sequence recap:
1. Data changes in the Amount Decimal control, which triggers the On Change event.
2. The Decimal On Change handler calls the execute() command on the Validation Service Call control.
3. The Validation Service Call control invokes its associated AJAX service.
4. The associated AJAX service executes the validation logic (server-side) and returns an error if the amount < 100.
5. The Service Call control's event handlers call setValid(true|false) on the Amount Decimal control.
|
This scenario highlights another key benefit of the SPARK UI Toolkit: Service Call-based invocations do not rely on a human service diagram. This means that both client-side logic and server-side invocations can be fully encapsulated inside a view. This ability takes reusability a step further compared to a classic Coach Framework-based scenario.
Lastly, the scenario in Figure 4-28 explains how to use the bpmext.ui.getInvalidViews() command preventatively. This method easily prevents navigation if any control on a page or in its embedded views is in an invalid state.
Figure 4-28 Using the bpmext.ui.getInvalidViews() method to inhibit coach navigation
|
Note: The same pattern shown for the bpmext.ui.getInvalidViews() command in Figure 4-29 on page 186 can be applied with the bpmext.ui.getRequiredViews()command to prevent navigation if not all required views are filled.
|
4.4 UI layout
The ability to configure layout behavior to control the following areas is essential to providing a naturally flowing user experience.
•Vertical or horizontal flowing
•Vertical and horizontal alignment of content (including justification, auto reflowing, or wrapping of content)
The ability for that behavior to adapt to different form factors is equally important and is covered in 4.6, “Responsiveness” on page 202.
As of IBM BPM 8.5.7, coach content can be laid out using a grid that is configurable. It is configurable at design time and controls layout behavior for coaches built in the IBM Process Designer Web Editor, as described in 2.10, “Designing a coach using the grid layout” on page 50.
|
Tip: Grid responsive behavior is always based on the width of the coach. Grids are best to use in a coach or for coach views that are always expected to take up the entire width of the coach.
|
SPARK UI layout controls provide sophisticated and consistent layout support for both the Web and Desktop Editors in IBM Process Designer. They also work well for coaches and coach views from IBM BPM 8.5.0.1 through IBM BPM 8.5.7.
|
Tip: The responsive behavior of SPARK UI layout controls is not relative to the coach page width. This makes SPARK UI layouts a good choice to lay out controls in a composite coach view (that is, a view that contains other controls).
|
4.4.1 Horizontal and vertical layouts
The core layout support provided in the SPARK UI Toolkit is contained in the two Horizontal Layout and Vertical Layout controls. The choice between horizontal and vertical layout is a design-time consideration. It is fully overrideable at run time (especially for responsive behavior, which is covered in “Layout controls: Responsive settings” on page 206. Both Horizontal Layout and Vertical Layout controls are backed by the same logic. The only difference is how IBM Process Designer displays the container controls at design time (using a horizontal or vertical layout).
Figure 4-29 on page 186 lists important layout and alignment configuration parameters available for the Horizontal and Vertical Layout controls.
Figure 4-29 Layout and alignment configuration options for Horizontal and Vertical Layout controls
Horizontal layout flow and options
When using horizontal layout, all controls directly contained in the Layout control are displayed next to each other horizontally (see Figure 4-30).
Figure 4-30 Horizontal layout modes with a default Justified horizontal alignment
By default, a margin is included around the layout, whether horizontal or vertical. Often, however, the UI developer might not want a new margin added with each new level of nesting, especially when a layout is nested inside of another. The Horizontal Tight layout option removes the margin to allow for a more esthetically pleasing layout appearance in such cases, as shown in Figure 4-30.
Left, right, center horizontal alignment
Figure 4-31 shows how layouts configured in a horizontal layout mode can align their controls left, right, or center. Additional horizontal layout configuration options also allow content to scroll horizontally or auto-wrap.
Figure 4-31 Horizontal layout modes with left horizontal alignment
For inline scroll, content appears properly aligned until it is compressed enough to cause horizontal scrolling. For auto-wrapping, alignment also works predictably and the wrapped content also aligns correctly (left, right, or center).
|
Note: When using the Horizontal Inline Scroll layout option, use controls that vertically expand (for example, a Popup Menu, Tooltip, and Status Box). Use these controls with caution because the expanded content might appear vertically cut off (that is, the scrolling portion of the browser clips vertically overflowing content).
|
Justified alignment
Justified alignment is the default alignment mode unless otherwise configured through the Horizontal Alignment option. The contained controls in a justified-aligned layout do not wrap overflowing content or scroll to show the overflow.
Instead, the width of the child controls can become elastic so that the entire row of controls takes up the width of the layout, such as table cells in a row. Contained controls can have a width configured in % or unit-based width (for example, 120 px or 2.9 em). The browser auto-adjusts the width of any contained control that does not have a width configuration option specified.
The width of controls contained in a layout can reach a point where they can be compressed no further. Figure 4-32 on page 188 shows how controls, buttons in this example, overflow unless responsiveness settings override this behavior.
Figure 4-32 Horizontal overflow and justified horizontal alignment
|
Note: Justified is not a valid horizontal alignment option for the Inline Scroll and Auto-wrap layout options.
|
Vertical layout flow and options
When using vertical layout, all controls directly contained in the Layout control are stacked vertically; they flow top to bottom. See Figure 4-33.
Figure 4-33 Vertical layout mode with justified horizontal alignment
The Left, Center, and Right horizontal alignment options also apply for vertically flowing layout content and the stacked control horizontal align. Figure 4-34 shows the center-aligned example.
Figure 4-34 Vertical layout mode with Center horizontal alignment
Width and height
By default, unless the Width configuration option is set, a layout control takes up the entire width of its container, whether in a coach view or a coach. As shown in the Horizontal Inline Scroll example in Figure 4-31 on page 187, a Layout control with a Horizontal Inline Scroll layout flow scrolls its child content. This happens as soon as the combined (compressed) widths of all child controls exceeds the configured width of the Layout control.
In general, the widths of immediate child controls contained in the layout are configured by setting the Width option on each child control. Child control widths do not need to be set unless the browser's layout behavior needs to be overridden. In the case of Justified alignment (see “Justified alignment” on page 187), child controls act like table cells, with one cell for Vertical layout and multiple cells for Horizontal layout. The widths of justified child controls behave like the widths of cells in an HTML table.
|
Note: Width-layout behavior with the SPARK UI Toolkit does not use the 12 columns layout model (except for Page Layout controls, which are deprecated after IBM BPM 8.5.0.1). SPARK allows any width specifications and any number of columns. To use a 12 column model with responsiveness based only on coach width, use the Grid in IBM Process Designer's Web Editor, otherwise use a SPARK UI Layout control.
|
Unless the height of a layout is configured, the Layout control expands vertically to accommodate showing its child content. If the height is configured and the content vertically exceeds the height configured, then the layout automatically allows vertical scrolling. Figure 4-35 shows a vertically scrolling layout.
Figure 4-35 Vertically scrolling layout
Setting the Height of a Layout control works predictably with any unit (for example 150 px or 6.2 em). However, heights set using percentages (%) only work if all parent elements (or layouts or views) of the Layout control have a height specified until either of the following is encountered:
•A height is specified in units (not using %).
•The coach body element is reached in the DOM hierarchy and has either a percentage (%) or a unit-based height specification.
This is a limitation of specifying heights using CSS-based styling.
Vertical alignment
The ability to configure a Layout control’s Vertical Alignment option matters in two situations:
•If the height of the layout is configured and is greater than the vertical space taken by its content, whether the layout flows horizontally or vertically.
•The height of child content flowing horizontally is uneven.
Figure 4-36 on page 190 shows the first of the listed situations.
Figure 4-36 Layout height greater than height of contained controls
Figure 4-37 shows the second listed situation.
Figure 4-37 Uneven heights for controls in horizontally flowing layout
Nesting layouts
Horizontal or vertical layout controls must be nested to achieve a variety of layout behaviors. Layouts can contain other nested layouts with their own Layout Flow, Horizontal Alignment, Vertical Alignment, Width, and Height configuration options.
These capabilities, especially when combined with responsive behavior support, provide powerful and flexible options for BPM UI layout at the coach or coach view level.
The Tight (Vertical or Horizontal) Layout Flow options are most useful in nested situations where certain parts of the child layout need to align with the edges of the parent layout. Figure 4-38 on page 191 shows the layout difference of using a nested layout with and without the Tight option.
Figure 4-38 Using the Tight layout flow option for nested layouts
4.4.2 Tabbing or stacking UI content
The SPARK UI Toolkit provides a Tab control that shows one pane at a time. It also provides a Stack control for arranging panes of content that only display one at a time.
Tab Section control
Figure 4-39 on page 192 shows an example of the design-time and runtime behavior and appearance of the Tab Section.
Figure 4-39 Tab Section control (design time and run time)
The Tab Section control provides a Tab Changed event that gets fired when the current tab is changed, either by the user or programmatically. The binding data, if the control is bound, contains the 0-based integer index of the tab currently showing. The UI developer can also change the current tab programmatically using the setCurrenPane() command.
|
Note: A 0-based tab index means that the first tab is at index 0, the second at index 1, and so on.
|
Stack
The Stack control is similar in behavior to a Tab Section control but without any visual decorations; it has no visible tabs or borders.
4.4.3 Displaying modal content
At times content needs to be displayed modally, in such a way as to prevent input in other parts of the UI. In those cases, the Modal Section provides a flexible option to do so for any control. An example of this is a Panel for modal dialog-like behavior, such as a Well containing a Progress Bar control.
|
Note: A Well is a simple cosmetic container that can be colored or left blank and given an optional background icon. See 4.4.4, “Wells” on page 195 for more information about this topic.
|
The Modal Section acts only as a container. The control the UI developer inserts in the containment box at design time is shown modally, against a darker backdrop, at run time. Figure 4-40 shows a Modal Section containing a Well and a Progress Bar control.
Figure 4-40 Modal Section displayed at run time with a Progress Bar
Figure 4-41 shows the same Modal Section containing a Well and a Progress Bar in IBM Process Designer’s Web Editor.
Figure 4-41 Modal Section in IBM Process Designer Web Editor
Showing and hiding modal sections
The display of modal sections is based on the standard Coach Framework visibility setting and can also be controlled using the setVisible() SPARK UI command. For this reason, a Modal Section control’s visibility setting must be set to NONE initially, otherwise the section is displayed as the coach opens. The visibility of the Modal Alert control works the same way.
After being displayed, the Modal Section can be closed in two ways:
•By calling the setVisible(false) command on the Modal Section control.
•By clicking in the darkened area of the section (assuming the Close On Click configuration option has been set at design time), as illustrated in Figure 4-42.
Figure 4-42 Close on Click configuration option for Modal Section
Lastly, the On Close event on a Modal Section control is available to take programmatic actions when closing and fires when the Modal Section closes from user action or programmatically (from the <Modal Section control ref>.setVisible(false) command).
Displaying dialogs modally
Modal sections can be used equally to display modal dialogs. Figure 4-43 on page 195 shows a Panel displayed as a modal dialog (meaning in a Modal Section) and the simple logic to open and close it.
Figure 4-43 Panel control displayed in a Modal Section as a modal dialog box
4.4.4 Wells
Wells provide a simple way to display content in an area that can be colored and can include an icon in its background. The purpose of Wells is limited to making UIs more visually appealing and organized by separating parts of the UI from their background using different coloring. Wells are appropriate to use by themselves or inside Layout controls or a Grid.
Figure 4-44 shows a Well configured to display a bank icon in its background, using the INFO color style, containing a Donut Chart control.
Figure 4-44 Configuration and runtime behavior of a Well control containing a Chart
4.5 Calling AJAX services
AJAX services under the Coach Framework are often called directly or indirectly from the diagram of a human service. This option is simple to use but provides low reusability because it does not allow the service invocation to be encapsulated inside a coach view.
Another classic option, for coach views only, is to create a Service type configuration option and then to call the service through context options using the <serviceName>(serviceArgs) command. This option, however, can expose a detail about the coach view as a configuration option. In some cases, this detail must remain internal to, or encapsulated in, the view. It is also a fairly technical exercise.
The SPARK UI Toolkit includes a control that offers streamlined and encapsulated interaction capabilities that work the same way in coaches and in coach views. They also work in a manner that is consistent with how SPARK events work.
4.5.1 Service Call control
The Service Call control is in the SPARK UI Toolkit palette (shown in Figure 4-45) under the System category.
Figure 4-45 Control palette showing Service Call control
Configuration
The Service Call control is configured and works in the following manner:
•A Service Call control must always be associated with a IBM BPM AJAX service, as shown in the configuration example of Figure 4-46.
Figure 4-46 Service call associated with IBM BPM AJAX service
•The service call control provides the execute() command to trigger the invocation of the associated AJAX service. The execute() command accepts a single input that can be a simple or complex type, such as following inputs:
– ${Service_Call1}.execute("abc”): Used to specify a string as input.
– ${Service_Call1}.execute({"prop1": "value1", "prop2": 2}): Used to specify an object with a prop1 string property and a prop2 integer property.
•If the single parameter for the execute() command is omitted, the value associated with the Input Value configuration option is used
•The control setInputData() command provides a programmer-friendly way of updating the value of the Input Value configuration option.
•If the Auto Run configuration option is checked, the Service Call control calls execute(). This is done automatically every time the value associated with the Input Value configuration option changes and when the control is first loaded.
•The Service Call control can show a visual progress indicator (see Figure 4-47) that is displayed when the AJAX invocation is in progress.
Figure 4-47 Service Call busy indicator configuration
Invocation sequence
Figure 4-48 on page 199 shows the invocation sequence required for the Single Select control containing shipping modes to use the Service Call control to trigger a shipping cost query. This query in turn sets the retrieved cost in a Decimal control.
Figure 4-48 Usage example for the Service Call control
|
Sequence recap:
1. Selected item changes in the Single Select control, which triggers the On Change event.
2. The Single Select On Change handler calls the execute() command on the ShippingRateQuery Service Call control.
3. The ShippingRateQuery Service Call control invokes its associated AJAX service.
4. The associated AJAX service executes its server-side logic and returns the shipping cost (or an error for standard shipping mode).
5. The Service Call control's event handlers call the setValue(<returned AJAX result>) command on the Shipping Rate Decimal control.
|
Figure 4-49 shows the resulting behavior at run time for a successful invocation for the given sequence, logic, and configuration noted in the previous sequence recap.
Figure 4-49 Runtime example for Service Call control, successful invocation
Figure 4-50 on page 201 shows a failed invocation.
Figure 4-50 Runtime example for Service Call control, AJAX service error
Handling server logic errors
AJAX service logic error information is accessible from the Service Call control through the getLastError() command, which contains an error object with the following properties:
•errorText
•errorCode
When the On Error Service Call event fires, the getLastError().errorText and getLastError().errorCode commands are used to retrieve the message. The message is retrieved from the AJAX service logic that is associated with the error.
Reporting errors from AJAX service logic
Errors in AJAX service logic can be reported in three ways inside the AJAX Service associated with the Service Call control:
•By initializing tw.local.error to new tw.object.AjaxError() and setting the errorText and errorCode property of the error. With this approach, an error event or exception is not thrown. When the AJAX invocation returns, the Service Call control automatically activates its On Error event
•By using an Error end event. In this case, the error code and the data from the error mapping on the Error Event map go to both errorCode and errorText.
•By throwing a server-side JavaScript error, for example by throwing a new Error (“Invalid account number”). The exception Java text, including the location of the offending statement, is mapped to the errorText. The value of errorCode, in this case, is determined by IBM BPM, not by the service developer.
4.6 Responsiveness
Responsiveness in the SPARK UI Toolkit works on the following two levels:
•Classic (IBM BPM-based) responsiveness: The basic responsive behavior exposed in the IBM Process Designer Web Editor for controls that provide adaptive properties.
•Enhanced Web Component-based responsiveness: The SPARK responsive capabilities that behave consistently since IBM BPM 8.5.0.1 work with both IBM Process Designer Web and Desktop Editors. They allow greater flexibility than coach form factor-based responsive triggers.
4.6.1 Classic responsiveness
Most SPARK UI Toolkit controls provide adaptive configuration options that can be exploited through IBM Process Designer’s Web Editor.
Figure 4-51 shows an example of the Note control Label Style adaptive property. This property allows IBM Process Designer Web Editor to specify different configuration option values across the three IBM BPM-supported screens or form factors (Small, Medium, and Large).
Figure 4-51 SPARK control adaptive property example
At run time, the control auto-adjusts the configuration option value of its adaptive property based on the Coach Framework's screen factor-based trigger. Figure 4-52 shows the runtime example for the previously-configured Note control.
Figure 4-52 IBM Process Designer Web Editor's adaptive properties, runtime behavior
Using this approach (which only works with IBM BPM 8.5.5 and higher and requires using Process Designer Web Editor), a large number of SPARK UI controls provide adaptive properties. These properties can be configured, as appropriate, to provide this type of behavior.
4.6.2 Enhanced Web Component-based responsiveness
By combining layouts and the Responsive Sensor control, the SPARK UI Toolkit provides responsive behavior benefits. Those benefits are as follows, in addition to classic responsiveness support in IBM BPM:
•Responsive behavior is provided and works consistently across product versions from IBM BPM 8.5.0.1.
•Coach views can predictably determine their responsive behavior even when they do not take up the entire width of the coach in which they are placed.
Coach views with SPARK behave like Web Components. As such, they do not depend on the overall coach form factor from the IBM Process Designer web editor to trigger layout changes. Layout changes can instead be triggered by the size change of the coach view itself, independently from the coach that contains it.
SPARK UI responsiveness relies on the following three controls:
•Responsive Sensor
•Horizontal Layout
•Vertical Layout
Responsive Sensor control
The Responsive Sensor is a container control. It wraps itself around its contained child controls, usually a Horizontal or Vertical Layout, and acts as a size-sensing rubber band. It is configured with box factors that help determine when the sensor activates responsive behavior in its contained Layout controls.
Figure 4-53 shows an example of the Responsive Sensor control at design time.
Figure 4-53 Response Sensor and box factor configuration
After box factors are specified, a Layout control (Horizontal in Figure 4-53) inside the Responsive Sensor specifies layout-related behavior. The behavior is based on one or more of the box factors configured. In Figure 4-54 on page 205, the layout is configured with the following options by default (settings in Appearance category):
•Layout Flow: Horizontal
•Horizontal Alignment: Justified
The settings in the Responsive category override the default configuration. For example, if Sensor1's box factor name is Narrow, then the Layout Flow is Vertical (option labeled as childLayout). Figure 4-54 on page 205 provides the full design-time configuration.
Figure 4-54 Responsive behavior overriding the default layout configuration
|
Note: The name of the responsive sensor used by the Layout control (see the Responsive → Responsive Sensor configuration option) is not a mandatory setting. If it is not provided, the Layout control listens to its nearest Responsive Sensor parent.
|
Box factor change event
At times it can be useful to take programmatic action whenever a box factor is activated. The Responsive Sensor control provides a special event (Events → On Responsive Boundary) that fires every time a box factor changes, including the first time a box factor is activated.
The Events → On Responsive Boundary event handler provides an event context variable. At run time, the variable contains the properties shown in Table 4-6.
Table 4-6 Responsive Sensor’s on Responsive Boundary event handler context
|
Event context variable property
|
Description
|
|
boxFactor
|
The name of the Responsive Sensor box factor that became active
|
|
lowerBound
|
The lower bound in pixels for the current box factor
|
|
upperBound
|
The upper bound in pixels for the current box factor
|
|
Width
|
The current width in pixels that triggered the box factor change
|
Example 4-6 shows the code in the On Responsive Boundary event handler of a Responsive Sensor control. This code logs the current box factor name. It is logged to the web browser console when a responsive boundary is crossed.
Example 4-6 On Responsive Boundary event handler code sample
console.log("Active box factor: " + event.boxFactor
|
Reminder: The On Responsive Boundary event does not fire every time a resize occurs. It only fires when a new box factor becomes active.
|
Layout controls: Responsive settings
When a box factor is active and a Horizontal or Vertical Layout's responsive behaviors option uses that box factor, any Behaviors configuration setting corresponding to the box factor entry is applied. Figure 4-55 shows a configuration setting example.
Figure 4-55 Layout configuration with responsive settings
|
Note: The example in Figure 4-55 assumes a Responsive Sensor contains the Layout and the Responsive Sensor is at least configured with the box factors named Medium and Narrow.
|
Table 4-7 provides descriptions of the Behaviors configuration settings for a Layout control.
Table 4-7 Responsive configuration settings reference
|
Setting
|
Description
|
|
boxFactorName
|
The name of the Responsive Sensor box factor that activates the configuration for the row of settings.
|
|
childLayout
|
Same as Appearance → Layout Flow: The Layout Flow applied to the child content of the Layout control (Horizontal, Horizontal Inline Scroll, Horizontal Tight, Horizontal Auto-wrap, Vertical, and Vertical Tight).
|
|
childAlign
|
Same as Appearance → Horizontal Alignment: The Horizontal Alignment applied to the child content of the Layout control (Justified, Left, Center, and Right).
|
|
childWidth
|
Widths of child controls contained in this Layout:
If one width is specified (for example 100%), all children controls have that width.
If two widths are specified (for example 64% and 33%), the first child has the first width, the second child has the second width, the third child has the first width, the fourth child has the second width, and so on.
As many widths as needed can be specified; they are applied as per the child width algorithm described. They must be separated by a space. Units can be, for example, %, px, or em.
|
|
width
|
The Width of the Layout control (relative to its container if using %).
|
|
height
|
The Height of the Layout control (relative to its container if using %).
|
|
cssStyle
|
CSS settings to be applied to the <div> element representing the Layout control This is the same div as the context.element div reference from the Coach Framework API.
|
|
cssClass
|
CSS class to be added to the <div> element representing the Layout control This is the same div as the context.element div reference in the Coach Framework API.
|
|
Note: For any Responsive → Behaviors setting left blank, given a particular box factor name), the configuration specified under the Appearance configuration category applies.
|
4.6.3 Coach view responsiveness
This section helps the BPM UI developer decide when to use the Responsive Sensor in coach views in the following situations:
•Instead of relying on the built-in web editor grid in IBM Process Designer.
•Instead of using adaptive properties based on form (coach) factors.
Responsive behavior using built-in IBM BPM capabilities
Figure 4-56 on page 208 shows two composite coach views (Contact Information and Billing Information) stacked vertically on a coach. The responsive behavior of the views is based on adaptive properties that adjust the arrangement of input controls as the form factor changes from Medium to Small.
Figure 4-56 IBM BPM-based responsiveness, correct behavior
The form factor-based use case, shown in Figure 4-56, works equally well using the following options:
•The IBM Process Designer web editor grid
•The layout or alignment-related adaptive properties of the SPARK Layout controls
•The Responsive Sensor.
However, when a UI developer expects that a composite coach view might be placed on a coach UI in such a way that it does not take up the entire width of the page, there are benefits with other options. The Responsive Sensor control, used inside the coach view, is the best option to predictably control the coach view content's layout behavior.
Without a Responsive Sensor, when the two coach views are laid out horizontally side by side, the layout cannot accurately determine when to reflow. This is because each coach view takes up 50% of the coach's horizontal space; a coach view is twice as narrow by the time the coach-driven form factor takes effect. Figure 4-57 on page 209 shows the Error! Reference source not found error.
Figure 4-57 Coach width-based responsiveness with side-by-side composite coach view
Responsive behavior using SPARK UI capabilities
When using a Responsive Sensor, the width of a coach is not considered unless the Responsive Sensor is configured as wide as the page. This means that coach view responsiveness is an aspect that is controlled by, and encapsulated in, the coach view. The same example shown in Figure 4-57 is provided for contrast in Figure 4-58 on page 210. Figure 4-58 shows a Responsive Sensor and a Horizontal Layout configured with a single Responsive > Behaviors configuration option for a narrow (≤ 420 px) form factor.
Figure 4-58 SPARK UI-based responsiveness
4.7 Working tabular and repeating data
The SPARK UI Toolkit provides several ways of displaying repeating data. Repeating data can be displayed as follows:
•From IBM BPM, through human service data represented as local variables
•From an AJAX service as a list of simple types, string or number; or of complex types defined in IBM Process Designer as Business Objects
4.7.1 Table and Service Data Table controls
The two tabular data controls provided by the SPARK UI toolkit are as follows:
•The Table control, for working with IBM BPM human service data
•The Service Data Table control, for displaying data returned by a backing AJAX service
Table control
The Table control can be bound to a list of complex objects. It is a high-performance control to display data in cells as coach views or using other cell-rendering options. Figure 4-59 provides key feature and capability highlights of the SPARK UI Table.
Figure 4-59 High-level Table control options (* denotes optionally enabled features)
To configure the columns in a table, various controls must be added to the columns of the table by dragging and dropping from the palette. When needed, the individual controls for each column can be bound to <list>.currentItem.<property> as required, as shown in Figure 4-60.
Figure 4-60 Binding table and column controls to BPM data
|
Note: Tables can only be bound to lists of complex types. For lists of simple types (such as strings, numbers, and so on) use a Layout control instead of a Table. Horizontal and Vertical Layouts can be bound to lists of simple types and, thus, become repeating containers, as described in 4.8.1, “Layouts and repeating data” on page 223.
|
Column configuration
By default, a table with no column configuration renders all columns containing a control as a coach view. Figure 4-61 on page 213 shows other rendering options available from the Columns table configuration option.
Figure 4-61 Table column configuration options
To fully configure columns in a table, a configuration entry must be explicitly added for each column mapping to a control in the table. The first control corresponds to column configuration entry 0, the second to entry 1, and so on.
When displaying in a table, the borders on an input type coach view control such as Text, Integer, Decimal, and Date Picker are distracting and add unnecessary clutter. The Seamless coach view option renders the coach views but automatically removes the border styling on input controls, as illustrated in Figure 4-62 on page 214.
Figure 4-62 Comparison between coach view and Seamless coach view rendering options
|
Note: The Table control respects tab index on data entry. A control in the Table that is rendered as a coach view can be tabbed to without using a mouse click or an explicit finger tap. A currently active input control in the table shows the cursor and is styled with a slight grey background, as shown in Figure 4-62.
|
Simple HTML column rendering
Coach views are always more expensive to render than a simple HTML Document Object Model (DOM) element. This is because they incur the management and lifecycle overhead of the Coach Framework. When Table data shown in a column can be displayed statically, the UI developer might consider using Simple HTML rendering.
With Simple HTML rendering, the control that is dragged and dropped in the Table column at design time is still necessary because it gives the column a hint about how the data is rendered. For example, a Checkbox control might hint to the Simple HTML rendering mode that a boolean true value is rendered as a check, not as the text true.
At run time, instead of the table cell containing a live coach view, it contains a lightweight HTML representation. For example, a simple check mark (for a true value) is rendered in a cell in place of an actual live Checkbox coach view. Figure 4-63 on page 215 shows how Simple HTML rendering (for all columns in this example) is minimally configured and how it is rendered at run time.
Figure 4-63 Basic Simple HTML column rendering for a Table (no format options specified)
Figure 4-64 on page 216 uses the same example as in Figure 4-63. However, Figure 4-64 on page 216 shows how data formatting options in Simple HTML rendering can be specified to influence the rendering of cell data.
Figure 4-64 Simple HTML column rendering for a Table with data formatting options
|
Note: Do not omit quotes around the option keywords or they do not load properly. For example, "dateFormat": "MMM yyyy" works, but dateFormat: "MMM yyyy" does not work.
|
Table 4-8 on page 217 summarizes the supported data formatting options if Simple HTML or Custom rendering is used for a Table column (that is, the column containing the appropriate associated hint control).
Table 4-8 Simple HTML and Custom format options
|
Hint Control
|
Possible Options
|
Notes
|
|
Date Picker
|
"datePattern": "<format spec>"
For example:
"datePattern":"MM/dd/yyyy HH:mm:ss"
|
Quick reference:
•yy or yyyy for year (for example, 16 or 2016)
•MM or MMM or MMMM for month (for example, 06 or Jun or June)
•dd for date, meaning day, in month (for example, 14)
•EEE or EEEE for day of week (for example, Fri or Friday)
•z for time zone (for example, Mountain Daylight Time)
•hh for 0 - 12 hour in day (for example, 08)
•a for AM/PM indicator (for example, PM)
•HH for 0 - 24 hour in day (for example, 20)
•mm for minutes (for example, 54)
•ss for seconds (for example, 42)
Refer to dojo/date/locale::format() for a complete reference:
|
|
Checkbox
|
"type": "<"check"|"icon"|"text">
"trueValue": "<text or icon name if true>"
"falseValue": "<text or icon name if false>"
For example:
"type":"text", "trueValue":"Y", "falseValue":"N"
Or
"type":"icon", "trueValue":"thumbs-up", "falseValue":"thumbs-down"
|
If the type is "check", no other options are needed. A true value renders as a check and false renders as blank.
If the type is "icon", any icon name available in SPARK does not work. For example "times", "check-circle", "battery-full", "comment", and other types.
|
|
Decimal
|
"decimalPlaces": <integer>
"decimalSeparator": "<text>"
"thousandSeparator": "<text>"
"prefix": "<text>"
"postfix": "<text>"
For example, for USD currency:
"decimalPlaces": 2, "decimalSeparator": ".", "thousandSeparator": ",", "prefix": "$"
|
A decimal can be formatted as an integer by specifying zero decimal places.
|
|
Integer
|
"thousandSeparator":"<text>"
|
|
|
Text
|
"nullValue": "<text>"
|
Text to specify (if any) to display null or undefined values. The text content specified must be HTML-escaped. For example, specify "<not set>" for <not set>.
|
4.8 Searching content
Rows in the Table control can be searched either by matching content in a specific column or across all rows. The Table control does not provide a search text field ready for use. Instead, a simple and flexible method is provided to allow searching in different ways.
The Table search() command allows the following parametersL
•columnIndex (0-based integer): Only match content in a particular column. If null, matches across all columns.
•searchText (text): Search expression to matched.
•caseInsensitive (boolean): If true, performs a case insensitive search.
•regularExpression (boolean): If true, consider searchText as a regular expression
Figure 4-65 on page 219 shows a Text control used for a simple search.
Figure 4-65 Table-wide text search example with Text search field
|
Note: Use the clearSearch() command to remove any filter on the table set through the search() command.
|
Service Data Table control
The Service Data table control retrieves data from an AJAX service instead of from human service data.
Because coach views are tied to human service data, the Service Data Table cannot render cells as coach views. They can render them only as Simple HTML and Custom. Instead of using a list-based data binding as its data feed, the Service Data Table control includes an AJAX service configuration option as its data source, as shown in Figure 4-66.
Figure 4-66 Service Data Table control configuration and attached AJAX service
Column configuration
Unlike the Table control, the Service Data Table must be configured for each column it displays. Column configuration includes the mapping of the data returned by the service and the type of rendering to use for the column, as shown in Figure 4-67.
Figure 4-67 Service Data Table column configuration options
Querying and re-querying data
A Service Data Table might need to re-query its associated AJAX service with the same or with new input data to refresh its content or to issue a new query. Figure 4-68 on page 222 shows how this is done by calling the setQueryData() command (passing in new input data), and then by calling the refresh() command.
Figure 4-68 Service Data Table AJAX service re-query
If the associated AJAX service accepts a simple data type for input, such as an integer, the setQueryData() command can be invoked, as shown in Example 4-7.
Example 4-7 Invoking Service Data Table: setQueryData() with simple input
${Table1}.setQueryData(1200);
Example 4-8 shows how to pass a complex type as input to the AJAX query.
Example 4-8 Invoking Service Data Table:setQueryData() with complex input
${Table1}.setQueryData({"custName":"Smith", "accType":"C"});
Lastly, after setting the query data, the refresh() command must be called to invoke the AJAX service with the new input data. See Figure 4-69 on page 223.
Figure 4-69 Example of Service Data Table re-query based around text update
4.8.1 Layouts and repeating data
When layouts are bound to a list, the coach views contained in the Layout that are bound to the current list item ("currentItem") are automatically repeated at run time. Figure 4-70 on page 224 shows that the Layout is bound to a list of strings containing user IDs.
Figure 4-70 Repeating behavior of Layouts when bound to lists
Layout flow and alignment with repeating content
The Layout options in the following list, in addition to other options, are applied to the repeating content just as they are to any other child content:
•Layout flow
•Horizontal alignment
•Responsive behaviors
In Figure 4-71, the same layout as in Figure 4-70 displays user IDs using Layout Flow Horizontal Auto-wrap and Horizontal Alignment Right.
Figure 4-71 Layout flow and alignment applied to repeating Layout content
Performance options
As with the Table control, the Layouts control provides asynchronous loading capabilities. This allows large lists to display without disrupting the user experience. To engage this display, use the following configuration options in the Performance configuration category:
•Async Loading (same behavior as Table control option)
•Async Batch Size (same behavior as Table control option)
|
Note: Contained coach views can only be rendered as coach views. No Seamless coach views, Simple HTML, or Custom rendering options are currently available for a Layout.
|
The Horizontal/Vertical Layout control also provides methods to efficiently append and remove list elements instead of causing the reload of the entire list. Two of the main commands follow:
•appendElement(<simple or complex object>)
•removeElement(<0-based index>)
4.9 Formulas
Formulas are a simplifying and streamlining feature of the SPARK UI Toolkit. They can significantly reduce the need for creating code to maintain computational relationships between controls on a form.
Formulas provide support for simple expressions that prescribe how the value of a control is the result of an operation involving other controls. For example, the ${Total} Decimal control is the sum of the ${Sales} Decimal control and the ${TaxAmount} Decimal control.
When the value of a control can be computed through a formula, the control provides a special option in the Formula category of its configuration options. Figure 4-72 on page 226 shows a Decimal control's configuration example.
Figure 4-72 Formula configuration option example
After the formula is specified, the behavior of the control regarding the computation of its value does not require maintenance. Any updates to the values of any of the controls that are referenced in the formula causes the expression to recalculate automatically.
When a formula references a control whose value is itself computed through a formula, the cascade of updates occurs efficiently and in the correct order.
|
Note: As is usually the case for SPARK controls, data binding for controls is optional even when using formulas. If a control computed through a formula has a data binding, the bound value is automatically updated every time the formula result changes.
|
4.9.1 Syntax for control references
The same syntax and addressing behavior that works with event handlers works with formulas, and the notations seen previously work as expected. The following list notes some examples:
•A Total Decimal control refers to a sibling Sales control using the ${Sales} reference.
•A LineTotal control in a table refers to a Quantity control in its same row as ${Quantity=} (the equal sign meaning the same row as me)
•A Price control in a Table refers to a Margin control that is a sibling to the table containing Price as ${../Margin}. This is because Margin is one level up in the view tree from Price.
|
Note: The ${ } syntax is an optional convenience and can be replaced in event handlers with the less compact page.ui.get("<control-id>") or view.ui.get("<control-id>). However, the compact notation is not optional with formulas.
The ${ } notation (or the more compact @{ } notation explained in “Compact references”) is mandatory in formulas. Otherwise, the result of the formula is not updated after its initial value.
|
Compact references
Because formulas are meant to be as simple to use as possible, SPARK supports a more compact notation than the ${ } reference syntax. The expressions in Example 4-9 are fully equivalent and resolve to the same logic at run time. The last expression is visibly simpler to use than the first.
Example 4-9 Compactness comparison between ${ } and @{ } notations
${Sales}.getValue() + ${TaxAmount}.getValue()
…is equivalent to:
@{Sales} + @{TaxAmount}
The @{ } notation shortcuts the various implied control-specific methods calls such as those noted in the following list:
•getText() for a Text control
•getValue() for a Decimal or Integer control
•getProgress() for a Progress bar
The @{ } notation requires less programming skills to express.
That said, the formula expression becomes a JavaScript expression at run time. Thus, the sophistication of a formula is constrained only by the following items:
•The formula must be a single JavaScript statement (but ternary operations such as <condition> ? <statement 1> : <statement 2> are allowed)
•At run time, the formula, after references have been translated to JavaScript, is placed inside a return( ) statement.
For example, if the result of the formula "@{Sales} + @{TaxAmount}" must be fixed to two decimals, Example 4-10 shows how it can be altered.
Example 4-10 Using JavaScript in formulas
(@{Sales} + @{TaxAmount}).toFixed(2)
|
Note: The @{ } compact notation only works in formulas and does not work in event handlers.
|
4.9.2 Formulas referencing specific controls
Formulas between scalar (non-repeating) controls need to reference the controls involved in the calculation and add needed logic in the expression to produce the result. Figure 4-73 on page 228 computes the TaxAmount control's value.
Figure 4-73 Formula expression with two specific control references
References between controls in a table
A special case of control-to-control references involves a control in a table row referencing another control in the same row. Figure 4-74 on page 229 shows how the LineTotal Decimal control references its peer (meaning same row, same index) controls. The Price and Quantity peer controls are referenced through the @{<control-id>=} notation.
Figure 4-74 Same-row referencing in formulas
4.9.3 Formulas for control aggregates
Formulas can also be used to compute results from repeating controls in a table. For example, all repeating instances of a LineTotal control in a table can be summed into a grand total.
Example 4-11 shows how the @{ } notation allows formulas to refer to all controls named <control-id>.
Example 4-11 Using the aggregate reference notation in formulas
@{ItemsTable/LineTotal*}
The asterisk (*) symbol at the end of the reference in Example 4-11 indicates that all controls named LineTotal are under the Table control named ItemsTable.
Functions used with aggregate references
The functions currently available to work with aggregate references are noted in the following list:
•SUM( )
•COUNT( )
•MIN( )
•MAX( )
•AVG( )
Because those functions work with aggregate references, they are referred to as aggregate functions in the SPARK UI Toolkit.
Figure 4-75 shows the use of the SUM() function combined with the aggregate notation for all controls named LineTotal under the Table named ItemsTable.
Figure 4-75 Formulas referencing a control aggregate with the @{<control-id>*} notation
As is the case for all other formulas, value changes in any field directly or indirectly referenced by the SUM() function causes the formula using the SUM() function to be recalculated.
Figure 4-76 on page 231 shows the runtime behavior for the UI composition.
Figure 4-76 Runtime behavior of aggregate references and functions
4.9.4 Working with data directly
So far, all formula examples given have depended on controls on a coach or in a coach view. This works well as long as the controls are in existence, even if they are hidden. Formulas are also able to handle delayed instantiation of controls. Those results are automatically updated as the controls come into existence, even asynchronously.
There are specific situations, such as using paging with tables, when a portion of the controls in the table might never come into existence. For example, the user might never display a particular table page. In such cases, the formula does not have access to all the controls it needs to consider for the computation to show the expected result.
To illustrate the use case, Figure 4-77 on page 232 shows a grand total computation based on a @{ItemsTable/LineTotal*} formula with a paging table. The illustration shows before and after the second page is displayed.
Figure 4-77 Limitations of @{<control-ref>*} formula notation with paging tables
For such cases, the SPARK formula framework provides support for a special notation. This notation works directly with the data backing the Table control instead of relying on control references inside the table. This special notation must be used in conjunction with an aggregate function, as shown in Example 4-12.
Example 4-12 Direct data reference in a Table control
SUM(${ItemsTable}, FOR_EACH{#{lineTotal}})
It is assumed in Example 4-12 that the ItemTable control is bound to a list of objects containing the following attributes:
•Price
•Quantity
•LineTotal
With such an approach, the total is always correct. The formula does not depend on the existence of the controls in the table and directly uses the table's backing data.
The FOR_EACH expression part, however, provides one more option. Because the SPARK UI Toolkit does not make data binding mandatory, you might expect a Line Total control to have no backing data because its value is derived through client-side calculation. In such a case, the UI developer needs the sum of price x quantity calculated for each row.
Accordingly, the expression in Example 4-13 is supported.
Example 4-13 Using FOR_EACH { } to compute sub-expressions in data-backed formulas
SUM(${ItemsTable}, FOR_EACH{#{price} * #{quantity}})
|
Note: The content of the FOR_EACH{ } clause can be any valid JavaScript expression that returns a result.
|
|
Tip: Use the proper syntax with data-backed expressions. Note where parentheses are used and when curly braces are used. They are not interchangeable.
|
4.9.5 Formulas for non-numerical computations
Formulas do not need to produce numerical results. They work just as well with string data, or other types of data. For example formulas can also be used to set the following items:
•The text value of an Output Text control
•The title of a Panel or Collapsible Panel control
•The text value of a Note control
•The content of a Tooltip control
•The data for a Data control
•The text content of a QR Code control to be graphically represented
•The label of a Button control
Figure 4-78 on page 234 shows a formula used to set the title of a Panel control to the following sequence:
•Hello and the name entered in the Text control
•Hello user, if no text is entered
Figure 4-78 Using formulas for non-numerical computations
4.9.6 Formulas for control-value initialization
A convenient use of formulas, especially for controls that are not bound to data, is for control value initialization. Figure 4-79 on page 235 shows the value of an Output Text control initialized to a specific value.
Figure 4-79 Initializing unbound control data with formulas
In general, formulas do not need to contain references to other controls; a simple JavaScript expression works just as well. However, the content of the formula expression is JavaScript and, therefore, a string specified for initialization must be contained in quotes.
4.10 Reporting and analytics
The ability to visualize data in charts, to render tabular data, and to provide analytics capabilities for BPM and business data in general is built into the SPARK UI Toolkit. That process is done through three key enabling aspects:
•Controls: Seven chart types represented as seven different controls
•Drill-down framework: An XML-configurable and customizable drill-down framework that automatically gives charts drill-up and drill-down capabilities
•AJAX service-backed tables: Service Data Table control that can be combined with charts and the events they provide to zoom in on data represented in charts
This section covers each key aspect of the SPARK UI reporting and analytic features.
4.10.1 Charts
SPARK UI Charts are highly configurable and interactive controls that can represent data from a backing AJAX service or from human service data. The SPARK UI Toolkit includes seven chart controls that can be categorized in three broad classifications:
•Composition: Pie Chart, Donut Chart
•Comparison or Evolution: Bar Chart, Area Chart, Line Chart, and Step Charts
•Profiling: Multi-purpose chart
Figure 4-80 on page 237 provides a sampling of many of the charts types included in the SPARK UI toolkit.
Figure 4-80 Sampling of SPARK UI Toolkit charts
Connecting charts to data
Charts can visualize data retrieved through a configured associated AJAX service or, less commonly, through data from the human service. Figure 4-81 on page 238 shows a chart control retrieving data through an AJAX service.
Figure 4-81 Bar Chart backed by AJAX service
|
Note: The Chart AJAX service developer only needs to work with the input input variable and the dataSeries output variable. All other inputs and outputs are automatically populated by the Chart control or by the Drill Down service.
|
Figure 4-82 on page 239 shows the AJAX service sample code used to populate the bar chart example in Figure 4-81.
Figure 4-82 Sample AJAX service code in context of Bar Chart
In summary, to make a single data series chart work, the UI developer must complete the following steps:
•Place a chart on the coach or coach view canvas.
•Configure the chart to use an AJAX service; create a chart service based on the AJAX service named Default Chart Single Data Series Service.
•Create logic in the AJAX service to populate the tw.local.dataSeries object.
•Configure the chart's visual appearance, if required.
•Configure the chart's behavior (such as bounds for the X or Y axis, or both, data tooltips), if required.
•Playback the chart and adjust the appearance and behavior, if required.
Working with charts programmatically
Charts provide a number of methods to influence behavior, visual representation, and data query or re-query.
Figure 4-83 shows how to influence what a chart displays based on input data that is used in the chart's AJAX query. The illustration shows a media consumption chart that adjusts its data based on the region selected.
Figure 4-83 Example media consumption data represented in bar chart based on region
The behavior in Figure 4-83 is modeled with the following options:
•A Bar Chart SDS control.
•A Single Select control containing regions (for example Europe or United States).
•An AJAX service backing the chart. The bulk of the logic is in the AJAX service performing the actual query. This is usually the case and is not specific to using the SPARK UI Toolkit.
On the client side, the Single Select On Change event needs to set the chart's query data to the current region selected. It then refreshes the chart, as shown in Figure 4-84.
Figure 4-84 Modeling and development detail for refreshing charts after setting input data
In addition to influencing query behavior, charts provide a number of methods to control visual and data representation behavior.
In Table 4-9, several charts methods are successively called to show, hide, disable, and enable group data series. The methods also annotate the charts with labeled horizontal and vertical lines. Figure 4-86 shows matching illustrations of the chart’s behaviors. The chart starts in the state depicted in Figure 4-85.
Figure 4-85 Initial chart state before transformation sequence
Table 4-9 shows the sequence of chart data representation and annotation method calls.
Table 4-9 Sequence of chart data representation and annotation method calls
|
Step
|
Logic
|
Step
|
Logic
|
|
1
|
<Initial chart state>
|
9
|
chart.removeVerticalLine();
chart.transform("area-spline", "Sample 3");
|
|
2
|
chart.groupSeries(true,
["Sample 0", "Sample 1",
"Sample 2", "Sample 3"]);
|
10
|
chart.transform("line", "Sample 2");
|
|
3
|
chart.addVerticalLine(2, "Line 2");
chart.groupSeries(true, ["Sample 2", "Sample 3", "Sample 4"]);
|
11
|
chart.showSeries();
|
|
4
|
chart.groupSeries(true);
|
12
|
chart.focusSeries(["Sample 0", "Sample 1", "Sample 2"]);
|
|
5
|
chart.defocusSeries(["Sample 0", "Sample 3"]);
|
13
|
chart.addHorizontalLine(60, "Line 1");
|
|
6
|
chart.groupSeries(false);
|
14
|
chart.groupSeries(true);
chart.transform("bar");
|
|
7
|
chart.transform("line", "Sample 0");
|
15
|
chart.focusSeries(["Sample 0", "Sample 1", "Sample 2", "Sample 3", "Sample 4"]);
|
|
8
|
chart.hideSeries(["Sample 1", "Sample 4"]);
|
16
|
chart.transform("spline");
|
Figure 4-86 shows the matching successive runtime representations of the charts (for each of the 16 calls from Table 4-9).
Figure 4-86 Chart transformation sequence using 16 successive chart method calls
Events
Charts can respond to the following events:
•Lifecycle events (after load)
•User events (when clicking or tapping the chart)
•Backing AJAX service events (when the data series is returned from the service)
Table 4-10 lists events common to chart controls.
Table 4-10 Chart control events
|
Event
|
Description
|
|
On Load
|
Fired immediately after a chart is loaded, but it is not necessarily populated with data at that time. Useful to take initializing steps such as adding a menu with static menu items for the chart. See “Menus” for more information.
|
|
On Refreshed
|
Fired every time a chart has loaded and rendered new data from its associated AJAX service, or when the chart loads its bound data if not using an AJAX service.
|
|
On Click
|
Fired when the user clicks or taps a data point in the chart. The data point that is selected can be retrieved through the chart's getSelectedDataPoint() command. The On Click event is also the best place to add context menu items. See “Menus” for more information.
|
|
On Menu Action
|
Fired when a menu item is clicked (see “Menus” for how to create context menu items). The action context variable provides action.name to determine what menu item is clicked.
|
Menus
Menus are automatically displayed on charts when the following occurs:
•The Behavior > Enable Menu configuration option is set on the chart
•A data point (showing as a bar in a Bar Chart, a slice in the Pie Chart, and so on) is clicked by a user
•There is at least one menu item defined for the chart, through the addStaticMenuAction() and addTempMenuAction() commands, or because the chart's drill-down behavior is active.
Figure 4-87 on page 245 shows the addition of two menu actions through the addStaticMenuAction() command to a Bar Chart. Menu items are associated with action names; the action name is then checked in the On Menu Action event to help decide what to do when a menu item is clicked.
Figure 4-87 Adding menu items to a chart and taking action on item clicked
Sometimes it is useful to add a menu item that is only valid given the context of the actual click of the chart. Figure 4-88 on page 246 shows how to create a temporary menu item that is only shown when a bar labeled Category 0 is clicked. Figure 4-88 shows how the getSelectedDataPoint() chart command is used in the On Click event. The method examines what the user has clicked. In this example, the label of the select data point is checked.
Figure 4-88 Using temporary menu items for context-specific chart clicks
|
Note: Temporary menu items are best created in the Chart's On Click event. They disappear as soon as the menu closes. Temporary items are listed in a separate (top) section of the context menu.
|
4.10.2 Working with tables and charts
Reporting requirements often include both displaying summary data and providing details regarding some aspects of a chart in tabular form. Chart controls and the Service Data Table control can work together to provide such an experience. In Figure 4-89 on page 247, the user taps in the category of a chart (for example News). This requests more detailed data on News media consumption to be displayed in a table under the chart.
Figure 4-89 Runtime example of chart and table controls working together
The example in Figure 4-89 relies on a chart menu-item click to the following actions:
•Request a table query corresponding to the selected data point label (News in this example)
•Set the title of the collapsed panel containing the table to Details - <data point label>
After the AJAX query for the table returns, the collapsed panel expands, triggered by the table's On Service Data Loaded event. The populated table is revealed.
Figure 4-90 on page 248 shows the design-time detail for this interaction.
Figure 4-90 Design-time composition for chart, table, panel interaction
4.11 Solutions for common patterns and requirements
This section provides guidance for using SPARK UI-specific capabilities to implement common requirements when building BPM UIs using the SPARK UI Toolkit.
4.11.1 Working with large forms
User Experience (UX) guidelines suggest limiting the amount of content presented to a user at the same time. There are also other reasons to mitigate the performance impact of loading a large number of controls on a single coach. An example is in an extreme case when a web browser freezes or becomes unresponsive for several seconds.
An effective performance impact mitigation approach can include a combination of some or all of the following suggestions:
•If displaying data in a Table control, change the rendering option of one or more table columns to Simple HTML. Doing so can drastically reduce the cost of rendering the table. The tradeoff is that those columns cannot be edited or updated because they are not coach views at run time.
•For Table, Service Data Table, or (Horizontal and Vertical) Layout controls, the following loading options can completely eliminate a browser freezing problem. They do so by loading content asynchronously and by still providing an option to fine-tune the overall content load time:
– Configuration → Performance → Async Loading: Check to enable
– Configuration → Performance → Async Batch Size: Number of rows (or controls for a Layout) loaded at the same time as part of an asynchronous batch. The larger the batch, the faster the overall load time, at the cost of the browser acting less responsive
•To suspend the instantiation of one of more controls until explicitly requested, use a Deferred Section control, such as in the following examples:
– A Tab Section control containing Deferred Sections directly under each of its tabs might delay the instantiation of the content of each tab until the particular tab is selected. Use the lazyLoad() command on the deferred section control when the On Tab Changed event is fired, or over several seconds, in the background.
– A Table control containing potentially large coach views on each row might instead display a few light columns. This can include a button to request the display of the heavy coach view only if the button is clicked. The heavy coach view is contained in a Deferred Section that in turn only loads the processing-intensive content of the corresponding row when or if requested.
Because the Table and Service Data Table controls were described in 4.7.1, “Table and Service Data Table controls” on page 211, only the scenarios using Deferred Sections are provided in this section.
Tab Section with on-demand content instantiation
Figure 4-91 on page 250 shows how a Tab Section and a Deferred Section under each tab can work together. They can delay the loading of coach views until the tab containing them is selected.
Figure 4-91 Example of deferred content loading in a Tab control
Except for the template HTML that the Coach Framework inserts into the page, the Billing Info view does not exist until the Deferred Section lazy-loads it.
|
Note: The Billing Info coach view is small (containing approximately 10 controls) in the example shown in Figure 4-91. Thus, using a Deferred Section in a production scenario is excessive. It is also not a problem because a Deferred Section has a small footprint. However, the larger the view (for example 40 or 50+ contained controls), the greater the benefit.
|
Table with on-demand content instantiation
Figure 4-91 on page 250 shows how a table that otherwise needs to display a lot of content on each row can instead display a few light controls per row (including a deferred section). It only loads the full coach view in the row when the user clicks the View button to show more detail. Figure 4-92 on page 251 shows how the in-table, defer-loaded coach view scenario behaves at run time.
Figure 4-92 Deferred or on-demand loading of coach views in table rows
The advantage of this approach is reduced cost. The performance of a Table that might otherwise be expensive to render (the larger the views contained on each row the more expensive) can be managed. Only the cost of instantiation is incurred if or when the user requests to see more detail. The scenario can be composed as shown in Figure 4-93 on page 252.
Figure 4-93 Modeling on-demand loading of coach views in table rows
In the composition shown in Figure 4-93, the coach view is contained inside a Modal Section.
Both the Modal Section and the Contact Info coach view are contained under the Deferred Section. Therefore, even the instantiation overhead of the Modal Section is deferred until the user requests to load the content. In fact, it is the Modal Section that is lazy-loaded. The Coach Framework loads the view contained in the Modal Section when the Modal Section instance comes into existence.
|
Note: The Deferred Section's lazyLoad() command takes two parameters. The first parameter is a delay in milliseconds to wait before the lazy-loading takes place. The second parameter is for convenience. Calling the lazyLoad() command on Deferred Sections that have content that is already-loaded does not load it again. However, if the second parameter is set to true, it fires the On Lazy-Loaded event again so the logic it contains can execute again.
|
4.11.2 Server-side paging
Client-side paging loads all records in browser memory but only displays a portion of the in-memory data set page by page. Server-side paging only retrieves in browser memory a small subset of a potentially large data set. Server-side paging then displays in the table the entire data subset that is in memory.
Server-side paging is a common requirement for the Service Data Table control, but it works differently from the built-in client-side paging feature of the table controls.
The paging behavior is effectively emulated by tracking a cursor or offset in the remote data set and requesting a batch of records. The page size is essentially the maximum batch size (that is, the maximum number of records to be returned in the query).
For example, with a 250 remote-record data set and a page size of 100 the following occurs:
•A query of up to 100 records at offset zero returns the first page of 100 records.
•A query of up to 100 records at offset 100 returns the second page of 100 records.
•A query of up to 100 records at offset 200 returns the last page containing the remaining 50 records.
|
Note: Server-side paging is most easily achieved with a Service Data Table control because it is the only table control capable of fetching data through an AJAX service.
|
|
Note 2: Another more complex and less reusable pattern can be implemented through a Table control with fetched human service data. The data is fetched progressively through diagram logic and Stay On Page interactions. The pattern presented in Figure 4-94 is simpler and can be easily reused and encapsulated.
|
Figure 4-94 uses a Service Data Table to query completely artificial data for Media Consumption volumes. The runtime behavior for the sample server-side paging scenario to be implemented is also shown in Figure 4-94.
Figure 4-94 Runtime behavior for server-side paging Media Consumption query scenario
The Service Data Table-based pattern has the following two halves:
•The client side, with the Service Data Table control and the logic required to set up the query (including page size and offset). Then the table is refreshed.
•The server side, which includes the table’s AJAX Service, with its associated query and resulting data.
Client-side implementation
The sample scenario implementation shown in this section uses a coach view that contains the Service Data Table. The paging navigation controls (previous and next Button controls, and an Output Text control) are used to show the current page number.
|
Note: Using a coach view to contain all the controls and associated business logic is not mandatory for the server-side paging pattern. However, it helps keep the implementation self-contained and reusable.
|
Overall structure
Figure 4-95 on page 255 shows the overall structure and the logic defined for the Server Side Paging Table Example coach view.
Figure 4-95 Structure and logic for the Server-Side Paging Table Example coach view
|
Note: The page size in the example provided is arbitrarily set to 5. In a more comprehensive example, the page size can be set from a configuration option or from a Page Size Integer control in the coach view.
|
Service Data Table configuration
The Service Data Table is configured with the Media Consumption Query AJAX service described in “Server-side implementation” on page 257. Figure 4-96 on page 256 shows key details of the Service Data Table configuration used for the example.
Figure 4-96 Service Data Table configuration for server-side paging example
By default, the Service Data Table control automatically invokes its associated AJAX service at load time for the table. In this example, however, the initial automatic query is prevented through the Start Empty setting. The initial query is instead done explicitly and with the desired initial offset (0) at load time for the Server Side Paging Example coach view. This is done by calling the this.query(0) command from the view's load handler (see load logic in Figure 4-95 on page 255).
Paging navigation buttons
Because the Service Data Table pager widget in the table footer can only be used for client-side paging, the footer and pager widget are not shown. Instead the server-side paging pattern uses controls such as Buttons or Icons for the user to page forward or backward.
Figure 4-97 shows the two paging buttons (labeled "<" and ">") that are used to trigger the AJAX re-query with a new offset. This is done by invoking the previous() and next() coach view commands from the On Click event of the "<" and ">" buttons, respectively.
Figure 4-97 Server-side paging navigation through buttons
Server-side implementation
The template for the AJAX service associated with the Service Data Table does not prescribe inputs used for server-side paging. It only allows for input of one data element of type ANY. To combine server-side paging parameters along with other query data, create a MediaConsumptionQuery complex type. Then add the following server-side paging-related attributes (in addition to other business case-specific attributes):
•offset (Integer)
•maxCount (Integer)
The offset and maximum record count are then used in the database query to determine the page (that is, the slice of records) for which to return results. Figure 4-98 on page 258 shows the server-side logic for the AJAX service.
Figure 4-98 Server-side paging AJAX service implementation
Pattern summary
The following list recaps the pattern-specific aspects of server-side paging with a Service Data Table control:
1. Create an AJAX service associated with the Service Data Table.
2. Ensure the input data for the AJAX service includes attributes for an offset and a maximum record count.
3. Implement the AJAX Service query logic to take the server-side paging parameters into account.
4. Ensure that client-side paging aspects are turned off for the Service Data Table configuration.
5. Add controls (such as Buttons, Icons, or Links) that can be used to attach table re-query logic to on-click events to allow previous page and next page navigation.
6. Implement simple client-side logic to manage the offset specified whenever a re-query is triggered.
|
Note: The example provided is purposefully simplistic. Additional sophistication can include retrieving the full record count up front to display the current page and the maximum number of pages available. More variability to control the page size and other query and sorting criteria can easily be introduced by extending the presented pattern.
|
4.12 More on the SPARK UI Toolkit
From a BPM UI developer's perspective, the SPARK UI Toolkit represents a deliberate compromise between simplicity and flexibility.
The benefit of this approach is that the level of UI development expertise required to be effective is low after you understand the core SPARK UI patterns. At the same time, the toolkit provides many extension and customization capabilities to implement advanced and complex production requirements and scenarios.
Additional content on the SPARK UI toolkit is available and provides a solid supplement to this chapter. The following topics are noted so that you can explore additional aspects of the toolkit in context of the foregoing material:
•Controls: Creating simple and composite coach views with SPARK capabilities
•Tables: Custom rendering and performance options
•Charts: Implementing drill-down behaviors
•Useful tips on debugging, deciding when to use diagram-based or encapsulated control logic
For more information, see the following website:
http://ibm.biz/SalientProcessToolkits
4.13 Conclusion
In this chapter you have learned how the SPARK UI Toolkit provides a fully featured responsive set of controls. These controls can be used to build modern user interfaces for desktop and mobile devices. These tools provide a great user experience and accelerates developer productivity up to four times compared with traditional techniques. The SPARK UI Toolkit extends the Coach Framework by adding the following benefits:
•An addressing and event framework that simplifies how to reference controls and react to user interactions
•Simplified client-side validation and enabling coach authors to express formulas.
SPARK controls are designed to perform well when used with large data sets, using lazy loading and server-side paging techniques. Charting controls are visually impressive and provide drill-down capability that can be used to create custom dashboards, which are covered in 5.2.4, “Extend Process Portal with custom dashboards” on page 277.
The following information about IBM Process Portal is described in 5.2, “Modifying the Process Portal user experience” on page 272:
•How coaches are used to define custom user interfaces other than for task completion UI
•How the process portal can be extended and customized
..................Content has been hidden....................
You can't read the all page of ebook, please click here login for view all page.