第2章 Business Central Configuration

All Business Central configuration settings are loaded from the EAP_HOME/standalone/deployments/business-central.war/WEB-INF/web.xml file. If you deploy Business Central on Red Hat JBoss EAP server, files jboss-web.xml and jboss-deployment-structure.xml contain configuration settings as well.

注記

Business Central can be run on different platforms. For more information, see Red Hat JBoss BRMS Installation and Configuration Guide.

2.1. Access Control

Workbench Configuration

Within Red Hat JBoss BRMS, users may set up roles using LDAP to modify existing roles. Users may modify the roles in the workbench configuration to ensure the unique LDAP based roles conform to enterprise standards by editing the deployments directory located at JBOSS_HOME/standalone/deployments/business-central.war/WEB-INF/classes/workbench-policy.propeties.

If authenticating user via LDAP over Git, administrators must set system property org.uberfire.domain to the name of login module it should use to authenticate users via the Git service. This must be set in the standalone.xmlfile in EAP.

注記

You can further customize Business Central with parameters no_build or no_search. The parameters disable the build and search functionality. Include one or both parameters in the Business Central URL, for example http://SERVER:PORT/business-central/kie-wb.jsp?no_build&no_search.

2.2. Branding Business Central Application

The Business Central web application can be customized by overriding some of its default styles. The personalized Business Central branding allows you to get a consistent appearance across all your applications, while it is also possible to create a different user interfaces for each team within your company. The customizable elements are built by using HTML files and images, which enables an easy and flexible customization of the application without having to recompile the code.

The following Business Central application elements can be customized:

  • In the login screen, the foreground corner images, company logo, and project logo can be changed.
  • The upper application banner displayed after logging in can be personalized.
  • In help pop-up windows, the label text and splash help images can be customized.

2.2.1. Customizing Business Central Login Page

Procedure: Changing Foreground Corner Images

  1. Start the EAP server and open Business Central in a web browser.
  2. To change the upper right corner foreground image, copy the substitute PNG file named bg-login.png to the EAP_HOME/standalone/deployments/business-central.war/img/ directory in your Red Hat JBoss BRMS installation.
  3. To change the lower right corner foreground image, copy the substitute PNG file named bg-login-2.png to the EAP_HOME/standalone/deployments/business-central.war/img/ directory in your Red Hat JBoss BRMS installation.
  4. Force a full reload of the login page, bypassing the cache, to view the changes. For example, in most Linux and Windows web browsers, press Ctrl+F5.

Procedure: Changing Company Logo and Project Logo

  1. Start the EAP server and open Business Central in a web browser.
  2. Navigate to the EAP_HOME/standalone/deployments/business-central.war/img/ directory in your Red Hat JBoss BRMS installation.
  3. To change the company logo that appears at the upper right hand corner of the login page, replace the default image login-screen-logo.png with a new image in the PNG format.
  4. To change the project logo that appears above the login text fields, replace the default image RH_JBoss_BRMS_Logo.svg with a new SVG file.
  5. Force a full reload of the login page, bypassing the cache, to view the changes.

2.2.2. Customizing Business Central Application Header

  1. Start the EAP server, open Business Central in a web browser, and log in with your user credentials.
  2. Copy your new application header image in the SVG format to the EAP_HOME/standalone/deployments/business-central.war/banner/ directory in your Red Hat JBoss BRMS installation.
  3. Open EAP_HOME/standalone/deployments/business-central.war/banner/banner.html file in a text editor.
  4. In the banner.html file, edit the following <img> tag to provide the name of your new header image:

    <img src="banner/logo.svg"/>
  5. Force a full reload of the page, bypassing the cache, to view the changes.

2.2.3. Customizing Business Central Splash Help Windows

Each splash page and its corresponding HTML file are located in the EAP_HOME/standalone/deployments/business-central.war/plugins/ directory. The files contain information about the images and the text to be displayed. For example, the authoring_perspective.splash.js splash page points to the authoring_perspective.splash.html file, which contains the names, captions, and location of all the image files that appear in the splash help pop-up windows of the Business Central Authoring perspective.

Procedure: Changing Splash Help Images and Captions

  1. Start the EAP server, open Business Central in a web browser, and log in with your user credentials.
  2. Copy the new splash help images to the EAP_HOME/standalone/deployments/business-central.war/images/ directory in your Red Hat JBoss BRMS installation.
  3. Open the corresponding HTML file from the plugins directory in a text editor.
  4. Edit the HTML file to point to your new splash help image. For example, to change the first image that appears in the Authoring perspective splash help, edit the following <img> tag in the authoring_perspective.splash.html file to add your new image:

    <img src="images/authoring_perspective1.png" alt="">
  5. To change the image caption that appears on the splash help, edit the <h4> and <p> tag contents in the <div> tag below the correspoding <img> tag:

    <div class="carousel-caption">
      <h4>Authoring</h4>
    
      <p>Modularized and customizable workbench</p>
    </div>
  6. Force a full reload, bypassing the cache, and access the splash help pop-up windows to view the changes.

2.3. Extending Business Central

Starting with version 6.1 of Red Hat JBoss BRMS, Business Central can be configured to add new screens, menus, editors, splashscreens and perspectives by the Administrator. These elements can extend functionality of Business Central and can be accessed through the ExtensionsPlugin Management.

You can now define your own Javascript and HTML based plugins to extend Business Central and add them without having to worry about copying files in the underlying filesystem. Let us add a new screen in the system to show you the basics of this functionality.

2.3.1. Plugin Management

You access the Plugin Management screen by clicking on ExtensionsPlugin Management. This brings up the Plugin Explorer screen that lists all the existing plugins under their respective categories:

  • Perspective Plugin
  • Screen Plugin
  • Editor Plugin
  • Splashscreen Plugin
  • and Dynamic Menu

Open any of these, and you will see the existing plugins in each category, including the uneditable system generated ones.

Let us create a new plugin that echoes "Hello World" when users visit the screen for that plugin. In general, the steps to creating a new plugin are:

  1. Create a new screen
  2. Create a new perspective (and add the new screen to it)
  3. Create a new menu (and add the new perspective to it)
  4. Apps (optional)
Adding a New Screen

Click the 6576 button and select New Screen. You will be prompted to enter the name of this new screen. Enter "HelloWorldJS" and press the OK button. The Screen plugin editor will open, divided into 4 sections: Template, CSS, JavaScript and Media.

注記

All manually created elements go into their respective categories in case you want to edit them later. In this case, to open the Screen plugin editor again if you close it, open the Screen Plugin category and scroll past the system generated screens to your manually created plugin and click on it to open the Screen plugin editor again.

Template is where your HTML goes, CSS is for styling, JavaScript is for your functions and Media is for uploading and managing images.

Since we are making a simple Hello World plugin, enter the following code in the Template section: <div>My Hello World Screen</div>. This can be any HTML code, and you can use the supplied Angular and Knockout frameworks. For the purposes of this example, we are not using any of those frameworks, but you can choose to by selecting them from the drop down in the Template section.

Enter your JavaScript code in the JavaScript section. Some common methods and properties are defined for you, including main, on_close and on_open. For this demo, select the on_open and enter the following: function () { alert('Hello World'); }

Click the Save button to finish creating the screen. After you save the screen, refresh business central so that the Screen Plugin is listed in the Screen Component of Perspective plugin.

Adding New Perspective

Once a screen has been created, you need to create a perspective on which this screen will reside. Perspectives can also be created similar to the way a screen is created by clicking on the New button and then selecting New Perspective. You can now provide a name for this perspective, say HelloWorldPerspective. This will open the Perspective plugin editor, similar to the Screen plugin editor.

The Perspective Editor is like a drag and drop grid builder for screens and HTML components. Remove any existing grids and then drag a 6×6 grid on the right hand side to the left hand side.

Next, open the Components category and drag a Screen Component on the right hand side to the left hand side (in any grid). This will open the Edit Component dialog box that allows you to select the screen created in the previous step (HelloWorldJS). Click the OK button and then click Save to save this perspective. To tag your perspective, enter Home in the tag name field and click Tags. Click OK and save the changes.

You can open this perspective again from the Perspective plugins listed on the left hand side.

Adding New Menu

The final step in creating our plugin is to add a dynamic menu from where the new screen/perspective can be called up. To do so, go to ExtensionsPlugin Management and then click on the New button to select New Dynamic Menu. Give this dynamic menu a name (HelloWorldMenu) and then click the OK button. The dynamic menu editor opens up.

Enter the perspective name (HelloWorldPerspective) as the Activity Id and the name for the drop down menu (HelloWorldMenuDropDown). Click OK and then Save.

This new menu will be added to your workbench the next time you refresh Business Central. Refresh it now to see HelloWorldMenu added to your top level menu. Click on it to reveal HelloWorldMenuDropDown, which when clicked will open your perspective/screen with the message Hello World.

You have created your first Plugin!

Working with Apps (Optional)

If you create multiple plugins, you can use the Apps directory feature to organize your own components and plugins, instead of having to rely on just the top menu entries.

When you save a new perspective, you can add labels (tags) for them and these labels (tags) are used to associate a perspective with an App directory. You can open the App directories by clicking on ExtensionsApps.

The Apps directory provides an alternate way to open your perspective. When you created your HelloWorldPerspective, you entered the tag Home. The Apps directory by default contains a single directory called Home with which you associated your perspective. This is where you will find it when you open the Apps directory. You can click on it to run the perspective now.

You can create multiple directories and associate perspectives with those directories depending on functional and vertical business requirements. For example, you could create an HR directory and then associate all HR related perspectives with that directory to better manage Apps.

You can create a new directory by clicking the 6418 button.

2.3.2. The JavaScript (JS) API for Extensions

The extensibility of Business Central is achieved by an underlying JavaScript (JS) API which is automatically loaded if it is placed in the plugins folder of the Business Central webapp (typically: INSTALL_DIR/business-central.war/plugins/), or it can be loaded via regular JavaScript calls.

This API is divided into multiple sets depending on the functionality it performs.

Register Perspective API

Allows for the dynamic creation of perspectives. The example below creates a panel using the registerPerspective method:

$registerPerspective({
    id: "Home",
    is_default: true,
    panel_type: "org.uberfire.client.workbench.panels.impl.MultiListWorkbenchPanelPresenter",
    view: {
        parts: [
            {
                place: "welcome",
                min_height: 100,
                parameters: {}
            }
        ],
        panels: [
            {
                width: 250,
                min_width: 200,
                position: "west",
                panel_type: "org.uberfire.client.workbench.panels.impl.MultiListWorkbenchPanelPresenter",
                parts: [
                    {
                        place: "YouTubeVideos",
                        parameters: {}
                    }
                ]
            },
            {
                position: "east",
                panel_type: "org.uberfire.client.workbench.panels.impl.MultiListWorkbenchPanelPresenter",
                parts: [
                    {
                        place: "TodoListScreen",
                        parameters: {}
                    }
                ]
            },
            {
                height: 400,
                position: "south",
                panel_type: "org.uberfire.client.workbench.panels.impl.MultiTabWorkbenchPanelPresenter",
                parts: [
                    {
                        place: "YouTubeScreen",
                        parameters: {}
                    }
                ]
            }
        ]
    }
});
Editor API

Allows you to dynamically create editors and associate them with a file type. The example below creates a sample editor and associates it with filename file type.

$registerEditor({
    "id": "sample editor",
    "type": "editor",
    "templateUrl": "editor.html",
    "resourceType": "org.uberfire.client.workbench.type.AnyResourceType",
    "on_concurrent_update":function(){
        alert('on_concurrent_update callback')
        $vfs_readAllString(document.getElementById('filename').innerHTML, function(a) {
            document.getElementById('editor').value= a;
        });
    },
    "on_startup": function (uri) {
        $vfs_readAllString(uri, function(a) {
            alert('sample on_startup callback')
        });
    },
    "on_open":function(uri){
        $vfs_readAllString(uri, function(a) {
            document.getElementById('editor').value=a;
        });
        document.getElementById('filename').innerHTML = uri;
    }
});

In addition to on_startup and on_open methods seen in the previous example, the API exposes the following callback events for managing the editor’s lifecycle:

  • on_concurrent_update;
  • on_concurrent_delete;
  • on_concurrent_rename;
  • on_concurrent_copy;
  • on_rename;
  • on_delete;
  • on_copy;
  • on_update;
  • on_open;
  • on_close;
  • on_focus;
  • on_lost_focus;
  • on_may_close;
  • on_startup;
  • on_shutdown;

You can display this editor via an HTML template:

<div id="sampleEditor">
    <p>Sample JS editor (generated by editor-sample.js)</p>
    <textarea id="editor"></textarea>

    <p>Current file:</p><span id="filename"></span>
    <button id="save" type="button" onclick="$vfs_write(document.getElementById('filename').innerHTML, document.getElementById('editor').value,  function(a) {});">Save</button>
    <br>

    <p>This button change the file content, and uberfire send a callback to the editor:</p>
    <button id="reset" type="button" onclick="$vfs_write(document.getElementById('filename').innerHTML, 'Something else',  function(a) {});">Reset File</button>
</div>
PlaceManager API
The methods of this API allow you to request that the Business Central display a particular component associated with a target: $goToPlace("componentIdentifier");
Register plugin API

The methods of this API allow you to create dynamic plugins (that will be transformed in Business Central screens) via the JS API.

$registerPlugin( {
    id: "my_angular_js",
    type: "angularjs",
    templateUrl: "angular.sample.html",
    title: function () {
        return "angular " + Math.floor(Math.random() * 10);
    },
    on_close: function () {
        alert("this is a pure JS alert!");
    }
});

The plugin references the angular.sample.html template:

<div ng-controller="TodoCtrl">
    <span>{{remaining()}} of {{todos.length}} remaining</span>
    [ <a href="" ng-click="archive()">archive</a> ]
    <ul class="unstyled">
        <li ng-repeat="todo in todos">
            <input type="checkbox" ng-model="todo.done">
            <span class="done-{{todo.done}}">{{todo.text}}</span>
        </li>
    </ul>
    <form ng-submit="addTodo()">
        <input type="text" ng-model="todoText" size="30" placeholder="add new todo here">
        <input class="btn-primary" type="submit" value="add">
    </form>
    <form ng-submit="goto()">
        <input type="text" ng-model="placeText" size="30" placeholder="place to go">
        <input class="btn-primary" type="submit" value="goTo">
    </form>
</div>

A plugin can be hooked to Business Central events via a series of JavaScript callbacks:

  • on_concurrent_update;
  • on_concurrent_delete;
  • on_concurrent_rename;
  • on_concurrent_copy;
  • on_rename;
  • on_delete;
  • on_copy;
  • on_update;
  • on_open;
  • on_close;
  • on_focus;
  • on_lost_focus;
  • on_may_close;
  • on_startup;
  • on_shutdown;
Register splash screens API

use the methods in this API to create splash screens.

$registerSplashScreen({
    id: "home.splash",
    templateUrl: "home.splash.html",
    body_height: 325,
    title: function () {
        return "Cool Home Splash " + Math.floor(Math.random() * 10);
    },
    display_next_time: true,
    interception_points: ["Home"]
});
Virtual File System (VFS) API

with this API, you can read and write a file saved in the file system using an asynchronous call.

$vfs_readAllString(uri,  function(a) {
  //callback logic
});

$vfs_write(uri,content,  function(a) {
  //callback logic
})

2.4. Configuring Table Columns

Business Central allows you to configure views that contain lists of items in the form of tables. You can resize columns, move columns, add or remove the default list of columns and sort the columns. This functionality is provided for all views that contain tables.

Once you make changes to the columns of a table view, these changes are persisted for the current logged in user.

Adding and Removing Columns

Tables that allow columns to be configured have the 6435 button in the top right corner. Clicking on this button opens up the list of columns that can added or removed to the current table with a check box next to each column:

6436

Resizing Columns

To resize columns, place your cursor between the edges of the column header and move in the direction that you want:

6437

Moving Columns

To re-order and drag and drop a column in a different position, hover your mouse over the rightmost area of the column header:

6438

You can now grab the column and move it:

6439

Drop it over the column header that you want to move it to.

Sorting Columns

To sort columns, click on the desired column’s header. To reverse-sort, click on the header again.