Contents


Customize the style of IBM BPM coaches

A pattern and a hierarchical approach

Comments

Today's IT projects demand rich, attractive, and efficient user interfaces more than ever before. A set of requirements that was once reserved for customer-facing systems is increasingly also being applied to internal systems. Businesses now want a consistent visual style in the user interfaces across all of the applications in their organization – reducing the need to train users of new systems, maximizing brand awareness, and increasing employee satisfaction.

Therefore, an increasingly common requirement for IBM® Business Process Manager (BPM) projects is to fully consider the style of coaches and how users interact with them. In addition, the coach designer in IBM BPM was designed with development speed as the priority rather than the ability to fine-tune the style of user interface pages. Both of these facts have led organizations to face some difficult choices when deciding how to proceed with IBM BPM coaches.

This article describes a pattern for building IBM BPM coaches, along with a hierarchical method for changing their style. The pattern allows customizations, which you implement by using the hierarchical method, rolled out across multiple IBM BPM applications from a central toolkit so minimal (if any) changes are needed at the application level. The pattern and the hierarchical method work with any version of IBM BPM starting with IBM BPM V8.0.1.

This article demonstrates an end-to-end journey of implementing customizations and creating a responsive user interface that is displayed correctly on all devices. This approach has been successfully implemented with several organizations. The pattern recognizes the maintenance challenges that arise when modifying the default coach views or when creating brand new coach views from scratch. Both actions increase the maintenance overhead for applications or can cause compatibility issues when updating IBM BPM. To address these potential issues, the pattern only uses default controls, does not require complex proprietary toolkits, and uses new coach views are only when absolutely necessary. You can read this article and implement the pattern without ever needing to look at the sample code. However, a sample .twx file is available on GitHub for reference.

This article focuses on how to customize responsive coaches and gives you a pattern for maintaining the customizations across an entire enterprise. If you don't want to make major customizations to the style of your coaches, but you still want responsive user interfaces that work well on all devices, see the Access IBM BPM from anywhere series.

In IBM BPM V8.5.7, new capabilities include responsive controls, grid layouts, and a theme customizer in Process Designer. The Deliver Modern UI for IBM BPM with the Coach Framework and Other Approaches IBM Redbooks publication and the IBM BPM product documentation describe these capabilities in detail. If you are using IBM BPM V8.5.7 and don't have a need for compatibility with earlier versions, you aren't using Bootstrap, and you don’t need the granularity of the coach view customizations, use the capabilities described in the IBM BPM V8.5.7 documentation and IBM Redbooks publication. IBM has been collaborating with Salient Process, releasing incremental updates to the SPARK UI toolkit and IBM BPM in preparation to fully embed it in a future release of IBM BPM. Make sure to get the latest cumulative fixes for IBM BPM V8.5.7.

What you need to use this pattern

This article assumes a good understanding of IBM BPM development, CSS, HTML, and general web development. Knowledge of how the Bootstrap CSS framework functions is helpful but not necessary, because links to easy-to-follow tutorials are included.

This pattern can be used with any version of IBM BPM V8.0.1 through IBM V8.5.7, and in future versions, assuming there are no major changes to the coach framework. There might be small changes to the IBM BPM default CSS file between versions. If you upgrade to a new version of IBM BPM, run regression tests on your applications.

Throughout this article, screen captures and other examples use an example toolkit. You can download this sample application from GitHub at DeanCleaverIBM/CustomisingIBMBPMStylePatternAndMethods and experiment with it.

The sample .twx file was developed in IBM BPM V8.5.6 and can only be imported into IBM BPM V8.5.6 or later. Even if you are using an earlier version of IBM BPM and cannot use the sample .twx file, you can still follow the pattern by reading this article.

The pattern for building coaches

The pattern for building coaches in IBM BPM is composed of two parts. The first part is a reusable template, which you should use on every coach throughout an application. The template contains the required library files, fonts, and CSS file. The second part of the pattern is Bootstrap and the coach views that you need to implement Bootstrap.

The template

The Coach Template component is the core of the pattern. It contains the library files, the CSS file, and the basic branding elements. The template implements the customization method that is discussed in later sections. Therefore, every application that implements the customization method must use this template as a base for all coaches.

The following screen capture shows the Layout tab for the Coach Template component from the sample .twx file that is available on GitHub.

Screen capture of the Coach Template layout
Screen capture of the Coach Template layout

As you can see at the top of the previous screen capture, the Coach Template in the example has an IBM logo that is configured to be displayed in the top right of the screen. The next items in the template are a set of three custom HTML blocks that contain HTML formatting and a title block, which is set by a variable bound to a configuration option of the coach view. The content box is the next item in the template. Finally, there are four coach views, each containing a set of included files and scripts.

Instead of being included in the Coach Template behavior tab, the coach views that contain the files and scripts, are wrappers for their contents. With this approach, the contents are easier to update, move, and modify individually. You don't need to update the template. All developers who use the toolkit have the flexibility to use the coach views independently, if needed for a future requirement. These coach views serve no purpose other than containing the files and scripts. Details are explained in future sections of this article.

The Font_Awesome coach view includes all of the files you need for using Font-Awesome on coaches that use the Coach Template. Font-Awesome is an icon font pack that you can use for inserting lightweight, customizable, scalable, vector-based images into your web pages. While it is not a focus of this article, Font-Awesome is used by some of the coaches in the included example toolkit. You don't need further knowledge about Font-Awesome for this article, but you can learn more at http://fontawesome.io.

The Bootstrap_Files coach view contains all of the files needed for implementing Bootstrap on a web page (or in this case, a coach). You learn more about Bootstrap and how to use it in the next section.

The CSS_Overrides coach view contains the CSS overrides to the base styles of IBM BPM, giving a unique appearance to the coaches in the example toolkit. Learn more in the sections that follow.

The IBM_CSS_Classes coach view contains all of the custom CSS classes in the example toolkit that you uses to set the style of specific elements. Learn more in the sections that follow.

Bootstrap

To achieve a responsive user interface that various types of devices can display well, the pattern for customizing IBM BPM coaches uses Bootstrap, an HTML, CSS, and JavaScript framework for developing responsive mobile projects.

For more information about Bootstrap, see www.getbootstrap.com. If you have not used Bootstrap before, learn about its responsive features in the Bootstrap 3 Tutorial on the W3Schools website.

There are many examples of Bootstrap implemented with IBM BPM, but often they are tied to proprietary implementations, or they are in specific visual styles that are difficult to customize. The approach in this article shows how to implement the responsive capabilities of Bootstrap with two simple coach views that implement the CSS framework. The coach views, called Bootstrap Row and Bootstrap Column, are described in detail in the following sections.

The template includes the Bootstrap JavaScript library, and you can create new controls that use Bootstrap. Some IBM BPM customers have used this approach, but this article does not delve into those examples. You can see examples at Bootstrap Examples on the W3Schools website.

The Bootstrap Row coach view

This Bootstrap Row coach view consists of two HTML blocks with a content box in between. The first HTML block opens a <div> tag and applies the Bootstrap Row class, and the second HTML block closes the <div> tag, as shown in the following screen capture.

Screen capture of the Bootstrap Row coach                 view
Screen capture of the Bootstrap Row coach view

The result is a coach view that can be dragged and dropped into the coach designer. Everything that is placed in that coach view is then effected by the row class, which is needed by Bootstrap columns.

The Bootstrap Column coach view

The Bootstrap Column coach view is built in a very similar way to the Bootstrap Row coach view. The end result is a <div> tag with a CSS class attached to the <div> tag and a content box placed within the <div> tag. In this case, however, the CSS class is one of several classes available for this coach view, if you use the columnWidth configuration option.

The custom HTML block that contains the opening <div> tag is not the simple <div> tag with a CSS class like on the Bootstrap Row coach view. Instead, the contents are bound to the value of the columnWidth variable, as shown in the following screen capture:

Screen capture of HTML block in Bootstrap Column coach                     view bound to the columnWidth variable
Screen capture of HTML block in Bootstrap Column coach view bound to the columnWidth variable

As you can see, the columnWidth variable has a variable type of BootstrapColumnSelectionType. The following screen capture shows how the columnWidth variable is set up on the Variables tab for the Bootstrap Column coach view.

Screen capture of the Bootstrap Column variables tab with                     the columnWidth variable
Screen capture of the Bootstrap Column variables tab with the columnWidth variable

BootstrapColumnSelectionType is a business object of the list data type, which is basically a string. It can be set only to the value of one of the list entries, which are set in the business object configuration page, as shown in the following screen capture:

Screen capture of the BootstrapColumnSelectionType                     business object
Screen capture of the BootstrapColumnSelectionType business object

When you add a list data type to a coach view, as the example with the Bootstrap Column coach view, it is displayed as a drop-down list in the coach designer, as shown in the following screen capture:

Screen capture of the Coaches configuration tab of a                     Bootstrap Column in coach designer
Screen capture of the Coaches configuration tab of a Bootstrap Column in coach designer

Each of the options available from BootstrapColumnSelectionType are Bootstrap CSS classes that effect the behavior that the Bootstrap framework follows, based on the size of the device screens for end users. Many more possibilities are available in Bootstrap, but to keep the example toolkit simple only a few commonly used ones are included. You can learn more with the Bootstrap 3 Tutorial on the W3Schools website.

Use Bootstrap framework responsive features with the coach views

This section uses the example application and toolkit to demonstrate how to assemble the Bootstrap Row and Bootstrap Column coach views to create a responsive user interface.

The following steps show how to assemble a coach that mirrors the Unit Test example in the sample application and toolkit that you can download from GitHub. The examples in this article use heritage human services, so you can use them with versions of IBM BPM starting with IBM BPM V8.0.1. For more information, see the Difference between heritage human services and client-side human services topic in the IBM BPM documentation.

  1. Create a heritage human service, add a coach to it, and link it to the start and end events.
  2. Open the coach designer.
  3. Add the Coach Template to the coach. Now everything that is in the template has access to the Bootstrap JavaScript and CSS code that is needed for the responsive features.
  4. Click the template, and switch to the configuration tab.
  5. Add a title in the template configuration tab, as shown in the following screen capture: Screen capture of the                             Coach Template added to a blank coach
    Screen capture of the Coach Template added to a blank coach
  6. Add a Bootstrap Row coach view, and you should see a Coaches tab that looks like the following screen capture: Screen capture of the                             Coaches tab after the Bootstrap Row has been added to the                             coach
    Screen capture of the Coaches tab after the Bootstrap Row has been added to the coach
  7. Add some Bootstrap Column coach views, and set their width to 12/4 in the configuration tab for each coach view. The following screen capture shows the Coaches tab with those coach views added: Screen capture of Bootstrap                         Columns coach views added to the coach with 12/4 width                         set
    Screen capture of Bootstrap Columns coach views added to the coach with 12/4 width set
  8. Add content to each of the columns, as shown in the following screen capture:Screen capture of content in the                         Bootstrap Column coach views
    Screen capture of content in the Bootstrap Column coach views
  9. Then run the Unit Test coach to test it.

    The following screen capture shows the Unit Test coach displayed on a large screen, similar to how an end user of the process application sees it:

    Screen capture of the bootstrap                         displayed on a large screen
    Screen capture of the bootstrap displayed on a large screen

    The following screen capture shows the Unit Test coach displayed on a small screen, similar to how an end user of the process application sees it:

    Screen capture of the bootstrap                             displayed on a mobile-device sized screen
    Screen capture of the bootstrap displayed on a mobile-device sized screen

The hierarchical method for coach styles

When you create a rich user interface in a web application, you can use several different approaches to creating the look you want. IBM BPM is no different. However, each approach comes with its own pros and cons, and each approach is suitable in different scenarios.

The following sections describe and prioritize each of the methods for setting user interface styles for your IBM BPM process participants. The first section covers the general style of the page, and the second section covers the style of the specific coach views.

This hierarchy of approaches is designed so that the methods at the top of the list are simplest, the most reusable, and most maintainable.

General style of the page

The following style techniques for the general style of the page are listed in order of priority: implement the first method, but if it is not possible, move to the next method in the list. The following sections discuss each approach in detail.

  1. A centralized CSS override file to override the standard IBM BPM CSS file
  2. A centralized CSS file with additional classes
  3. HTML attributes (inline style)
  4. Custom HTML blocks

Method 1: A centralized CSS override file to override the standard IBM BPM CSS file

The first place to modify the appearance of your user interfaces in IBM BPM is a centralized CSS file that overrides the standard IBM BPM Claro Theme CSS files. Every element that can be dragged onto a coach in IBM BPM has associated classes. This means that you can reference these classes to override the base style sheet and apply different style

You can create your coach as you usually would in IBM BPM, and run the service. Then, use browser development tools to look through the various page elements to discover what classes are referenced. You can place the classes in a centralized file, with the new style applied, and then attach the file to a template that is used as the basis for every coach.

In the example available on GitHub, see the CSS file (bpm&bootstrap-css-overrides.css) that is attached attached to the CSS Overrides coach view on the Coach Template. The following screen capture shows the style of a coach built with the example toolkit.

Screen capture of the style of a coach built using the                     demo toolkit
Screen capture of the style of a coach built using the demo toolkit

The example application and toolkit provide good examples of the scale of changes that you can accomplish with this method. The resulting style is substantially different than the default style from IBM BPM.

The reason this approach is first in the hierarchy is because it is quick and relatively simple to rapidly modify the appearance of all the user interfaces across an entire application (or even multiple applications, if implemented correctly).

The CSS file is stored centrally in the template, and changes are replicated everywhere it is used. If the file and template are stored in a toolkit, then all IBM BPM applications that reference it (and maintain their dependencies) keep up-to-date with style changes. It is even possible to store the CSS file on an HTTP server and reference it in the template, which means that you can update the user interface even after all IBM BPM applications are deployed.

The method for deciding which CSS classes to override is straightforward. Open an IBM BPM coach in any common browser, and use the element inspector to click each element and check what CSS classes are used for those elements. Then override those classes in your centrally managed CSS file.

In the following screen capture, the headerContentNode div is selected in the Chrome element inspector.

Screen capture of the the element inspector used to                     identify a class for overrides
Screen capture of the the element inspector used to identify a class for overrides

You can see to the right that the dojoxGridHeader CSS style is applied to this element. Any overrides applied to this class can be added to a centrally managed CSS file that affects the style of the element on the page.

This pattern and the associated example toolkit use a centralized CSS file that is bundled with the toolkit. This design means that each application has the CSS file inside, and each application can be updated independently if needed. However, with this approach, you need to redeploy each application to update the interface across all applications.

If your team doesn't want to deal with that requirement, an alternative approach is to place this centralized CSS file on an HTTP server and reference it inside the template. This approach gives less control over how each application is upgraded, but updating one file replicates changes across all IBM BPM applications. The CSS file also can be reused across non-IBM BPM interfaces.

Method 2: A centralized CSS file and additional classes

The next method in the hierarchy is another centralized CSS file attached to your template, but this time with additional classes. If you need to set style for a collection of elements that are unrelated to any current class, or if the current class is too broad, consider using this approach.

You have a centralized CSS file as in the previous approach, but the classes are unique to the particular organization or even the application. This file can be one you already use across the organization or, it can be entirely new. You can combine this CSS file with file described in the first method, or keep the files separate. Either way, remember that the classes must be added to each element that you want to have the new style.

To apply to a coach view, complete the following steps:

  1. Prepare the CSS class.
  2. Go to the HTML Attributes section of a coach and click Add a class.
  3. Type in the name that matches the additional class that you have defined in the style sheet on the template. The style is then applied to that element alone.
  4. Due to the structure of IBM BPM, some elements do not take on the style from applying the class. If you do not see the changes you expect, look at the element structure in your browser developer tools again. If needed modify your CSS to reference the style on any sub-elements.

If you are applying a CSS class to a piece of custom HTML, follow the same procedure as applying the class to any other type of web page.

The following three screen captures show an example of a custom CSS class from a centrally managed file used on the template to set the style of the title of the page.

The following screen capture shows the pageTitle CSS class:

Screen capture of an example custom CSS class in a CSS file

The following screen capture shows shows the pageTitle class applied to the title <div> of the Coach Template in the example toolkit:

Screen capture of the CSS class applied to a <div> in a custom HTML                     block
Screen capture of the CSS class applied to a <div> in a custom HTML block

The following screen capture shows how the user interface for the coach template looks at run time, with content and with the page title configuration option set to Unit Test.

Screen capture of the title on the page after the CSS is                     applied
Screen capture of the title on the page after the CSS is applied

Method 3: HTML attributes (inline styles)

The first two methods previously described don't work if you are making a very specific modification or you don't want the look of the element to change if global styles are updated. The next approach is to apply directly to an element by using inline style in the HTML attributes tab.

For example, this method is good for adding a left margin of a few pixels to an element. This approach should be used sparingly, because the application is very specific. From Process Designer, it is difficult to see if this method is used, and therefore it is more difficult to maintain. The following screen capture shows an example of using the HTML attributes method to change the text color of a text field:

Screen capture of in-line style applied in Process                     Designer
Screen capture of in-line style applied in Process Designer

The following screen capture shows the results of applying the inline style, like what the users of the coach see:

Screen capture of a coach with the in-line style applied
Screen capture of a coach with the in-line style applied

Method 4: Custom HTML blocks

If all the previous methods don't meet your requirements, or if you need to make a very specific "one-off" change to a page (such as adding a <div> tag or inserting white space in a specific location), then you can place custom HTML blocks directly on the coach.

The following three screen captures show examples of how to use custom HTML blocks on the Coach Template to add a custom title to the page.

The following screen capture shows the first example custom HTML block selected, with a <div> opening with the pageTitle CSS class assigned to it:

Screen capture of the first custom HTML block example in the                     sample toolkit template
Screen capture of the first custom HTML block example in the sample toolkit template

The following screen capture shows the second example custom HTML block bound to the contents of the titleText configuration variable:

Screen capture of the second custom HTML block example in the                     sample toolkit template
Screen capture of the second custom HTML block example in the sample toolkit template

The following screen capture shows the <div> opened in previous section now closed, in the third example custom HTML block.

Screen capture of the third custom HTML block example in the                     sample toolkit template
Screen capture of the third custom HTML block example in the sample toolkit template

Style of specific components

Sometimes to get a specific style for a particular component, changes to the actual coach views are needed. If you want a particular component to have a different style than other components, simply changing the CSS file might not give the results you are looking for.

The following style techniques for the component-specific style are listed in the order to be implemented. The following hierarchy is listed in order of priority for methods to set the style for specific coach view components. The following sections discuss each approach in detail.

  1. Default coach view components wrapped in a reusable custom coach view
  2. A reusable custom coach view that uses default IBM BPM components as a base template
  3. A reusable coach view built from scratch
  4. A single-use coach view

Method 1: Default coach view components wrapped in a reusable custom coach view

The first method to try is to keep the default coach views as-is, but embed them in another coach view that implements the required style changes. For example, this is appropriate for a custom text field that requires specific styles placed around it.

Because this approach does not modify the underlying default coach view (or views, if multiple are used), all functionality of the base coach view is retained. Also, the actual default component is still supported by IBM BPM updates. Minimal or no changes to the custom coach view are required after an IBM BPM update.

The following three screen captures show a text field with a piece of HTML code placed after it. The HTML code adds cm (which represents centimeters) as text that appears after the text field. The idea behind this example custom coach view is to display measurements in centimeters.

The following screen capture shows the coach view in the coach designer. The label field is bound to a configuration option named label. Then, the label can be set by the top-level coach view.

Screen capture of the coach                     view designer with a default text field embedded in a reusable                     coach view (Text field with CM units) selected
Screen capture of the coach view designer with a default text field embedded in a reusable coach view (Text field with CM units) selected

The following screen capture shows the same coach view again, but with the focus on the custom HTML block that shows a page break (added to ensure that the text appears in the right location), followed by cm.

Screen capture of the coach                     view designer with a default text field embedded in a reusable                     coach view (Text field with CM units), with the custom HTML block selected
Screen capture of the coach view designer with a default text field embedded in a reusable coach view (Text field with CM units), with the custom HTML block selected

The following screen capture shows how the custom coach user interface looks at run time to the users of the process application:

Screen capture of an default text field embedded in a reusable                     coach view (Text field with CM units), viewed from a                     browser at run time
Screen capture of an default text field embedded in a reusable coach view (Text field with CM units), viewed from a browser at run time

Method 2: A reusable custom coach view that uses default IBM BPM components as a base template

When wrapping a default component is insufficient to get the style and functionality that you want for the user interface, use the second method in the hierarchy. For this method, you use a default component as a starting point when developing a new component. Duplicate the original method, move it to the relevant toolkit, and then make the necessary changes.

The advantage of this approach is that it retains the default IBM BPM capabilities that you are familiar with. However you lose IBM BPM support for the component if you take this route. If an update to IBM BPM is applied, any updates to the default component need to be applied to the custom component manually.

See the example toolkit for an example of this method. A custom button example extends the default button to include an icon from the Font-Awesome icon font pack in the text string that is displayed on the button. The following example uses the fa-check icon. The following screen capture shows the Font Awesome Button coach view from the example toolkit, as users view it from a browser:

Screen capture of a custom button                 example that extends the default button to include an icon from the                 Font-Awesome icon font pack, viewed from a                     browser at run time

Method 3: A reusable coach view built from scratch

Consider a third method in the hierarchy when you cannot make use of any of the default coach view components in IBM BPM. This approach builds a new coach view from scratch, but builds it in a way that is easy to reuse.

The example toolkit contains several examples of these types of coach views, used to implement the previous method for using Bootstrap. The Bootstrap Row and Bootstrap Column coach views are both completely custom views that are reusable. Another example is the Notification Container coach view, as shown in the following screen capture:

Screen capture of the Notification Container coach view                     from the example toolkit, viewed from the browser at run time
Screen capture of the Notification Container coach view from the example toolkit, viewed from the browser at run time

Method 4: A single-use coach view

In isolated cases, you might have a requirement for a "single-use" coach view in your project. The requirements that lead to these types of coach views are rarely motivated by style, but this situation warrants a mention.

The usual motivations for creating a single-use coach view are requirements like complex client-side logic implemented on a page. These requirements might be possible to implement only when using the coach view framework instead of the coach designer.

This method is OK to use if the coach view you create is well documented and built to be as easy to maintain as possible.

In our experience working with organizations that use IBM BPM, we have seen many examples of projects that faced issues because of too many single-use coach views. Code can become very difficult to follow if there are numerous single-use views are used in a project. Without documentation, maintenance tasks can become very difficult.

Conclusion

This article described methods for customizing the style of coaches in IBM BPM V8 and later using the Bootstrap CSS framework and multiple overrides of the default CSS file. Now you can apply these approaches in your own environment, to meet your organization's specific needs.

The hierarchical method of setting styles was successfully implemented with several organizations that use IBM BPM. The key to this success is adopting the approach outlined in this article from the outset, and building well-structured and maintainable UI toolkits. Throughout the projects, developers followed the method as closely as possible and put special efforts in place to ensure that no project-specific content was included in toolkits. The customers subsequently replicated this approach across the enterprise, providing a consistent style across multiple IBM BPM projects.

For example, one organization is now using this method for more than six projects. Because the UI toolkit contains only what is needed to implement the method, any changes to the toolkit don't greatly affect the projects that consume it. The style across the entire IBM BPM environment is maintained from one central point. Now, when the developers want to make changes to the style of the user interface, they simply make changes in the toolkit and take a snapshot. Then, when other projects are ready to upgrade, they adopt the latest toolkit snapshot. If the hierarchical method is followed, no additional work is required.

Acknowledgements

The authors would like to thank Gerry McLaughlin, Scott Glenn, and Dennis Parrott for reviewing this article.


Downloadable resources


Related topics


Comments

Sign in or register to add and subscribe to comments.

static.content.url=http://www.ibm.com/developerworks/js/artrating/
SITE_ID=1
Zone=Middleware
ArticleID=1043355
ArticleTitle=Customize the style of IBM BPM coaches
publish-date=02282017