This content is dedicated to our next version. It is work in progress: its content will evolve until the new version is released.

Before that time, it cannot be considered as official.

Pages development

A page presents information to a user or can also collect information entered by a user.

Displayed in a browser, a page is intended for use in applications.

Provided pages

You do not need to create all your pages from scratch. Bonita already provides some pages.
Bonita Administrator Application "Resources" tab lists all the non-UI Designer-made pages, that can be reused "as-is" in an application. By downloading the Bonita User and Administrator applications from Bonita Studio Welcome page, you also download Bonita pages created with Bonita UI Designer.
Those pages can be customized and added to an application.

Custom pages

A page resource has the general resource definition. If it contains an Index.groovy file, this must implement the PageController interface optionally with libraries. If you create a custom page with Bonita UI Designer, its structure and content will be congruent by default.

A custom page is displayed inside an iframe to prevent conflicts between resources (for example JS and CSS) and those used in the custom page. This also reduces the risk of migration issues, for example if a custom page uses a version of JQuery that gets updated.

PageController interface

public interface PageController {

/**
* Let the custom page parse request for specific attribute handling.
*
* @param request the HTTP servlet request intended to be used as in a servlet
* @param response the HTTP servlet response intended to be used as in a servlet
* @param pageResourceProvider provide access to the resources contained in the custom page zip
* @param pageContext provide access to the data relative to the context in which the custom page is displayed
*/
public void doGet(HttpServletRequest request, HttpServletResponse response, PageResourceProvider pageResourceProvider, PageContext pageContext);
}

Permissions for custom pages

If your custom page is an HTML page using the Web REST API, you need to specify the REST API authorizations that a user needs to have in order to access the resources in the custom page. These resource authorizations are defined in the page.properties file.

When you’re doing a page with the UI Designer, some resources (from button widget or variable as example) are automatically generated in the page.properties file. You should manually declare the Bonita REST API resources which you’re using in your artifact (page, custom-widget or fragment), when the automatic detection fails to found them.

You should always declare the resource on the most atomic artifact (in fragment, if the resource is used in a fragment, in a custom widget, or at page level)

If your custom page is written in Groovy and uses the Bonita Engine Java APIs, you do not need to specify any resource authorization.

For each REST resource accessed in the page, specify the authorization needed for each method used.
You can find examples of the default resources in resources-permissions-mapping.properties.

The following example shows the resource authorizations defined for a custom page that enables a user to view but not update organization information:

#The name must start with 'custompage_'
name=custompage_orgViewer
displayName=Organization viewer
description=Organization viewer page. You cannot modify the organization from this page.
resources=[GET|identity/user, GET|identity/personalcontactdata, GET|identity/professionalcontactdata, GET|identity/role, GET|identity/group, GET|identity/membership, GET|customuserinfo/user, GET|customuserinfo/definition, GET|customuserinfo/value]

When a user is given access t this page because they are in a profile that contains it or that is mapped to an application that contains the page, then this user is granted, upon login, the permissions associated to these resources (see REST API authorizations for more details).

Debugging a custom page in development

While you are developing a custom page, you can enable custom page debug mode. In debug mode, you can see changes to your custom page without importing a new .zip archive.

To enable custom page debug mode, edit console-config.properties and set custom.page.debug to true.

To work on a page in debug mode:

On a Tomcat installation, <java.io.tmpdir> points to <BUNDLE_HOME>/temp/

  1. Import your custom page zip archive into the Bonita Administrator Application. This creates a directory <java.io.tmpdir>/bonita_portal_*/tenants/tenant_id/pages/custompage_<your custom page>.

  2. Publish the page to a profile, then log out and log in as a user having this profile.

  3. You can now update Index.groovy and the contents of the lib directory directly in <java.io.tmpdir>/bonita_portal_*/tenants/tenant_id/pages/custompage_<your custom page>.

  4. To view the page after you modify it, refresh the page in the browser.

When you have finished developing the page, recreate the custom page zip archive, and then modify the page to import it. This makes your final version of the page permanently available.

In Bonita Studio, the debug mode is enabled by default.
If you want to disable it, you need to use the setup tool provided in workspace/tomcat/setup/ to update console-config.properties (Update the file database.properties first so it points to the target database. E.g.: h2.database.dir=../../default/h2_database).

Constraints

When you update to a newer version of Bonita, your custom page definition should still be valid. However, this cannot be guaranteed for all future updates.

Page resources management

Page resources

Custom page resources can be accessed by a PageResourceProvider.

The bonita.css can be retrieved using pageResourceProvider.getBonitaThemeCSSURL()

Other css/js resources can be retrieved using pageResourceProvider.getResourceURL("<path in the custom page resources folder>")

If you are not using Groovy you can directly access a resource by adding a link in index.html.

For example: <link href="css/file.css" rel="stylesheet" />

API access

If your page is viewed in a custom profile or in an application, you will have access facilities for the REST API.

you will be able to access any REST API using the following path: ../API/{API name}/{resource name}

Theme access

If your page is viewed in an application, you will have access facilities for the application theme.

The Theme.css is directly accessible by adding the following link in index.html: <link href="../theme/theme.css" rel="stylesheet" />