Creating custom view components

The View designer consists of built-in view components (like record grid, record editor). You can create your own custom view components. A view component is a regular AngularJS directive. To create a custom view component you can create an AngularJS directive and register it to make it available in the View designer.

For more information on directives, see Creating Custom Directives .

View component files

Anatomy of a view component consists of the following files:

For example:

Star-rating view component consists of the following files:

To create a custom view component

1. Define a Angular module for your view component that must have isolated scope and rxConfiguration configuration property.
   Sample code:

   angular.module('com.example.samplelibrary.view-components.customer-location')
       .directive('customerLocation', function () {
           return {
               restrict: 'E',
               templateUrl: '/scripts/view-components/customer-location/com-example-samplelibrary-customer-location.html'
     
               // should have isolated scope
               scope: {
                   rxConfiguration: '='
               }
           };
       });

2. Register the view component.
   To make a view component available for use in the View designer, you must register the view component by using the registerComponent method of rxViewComponentProvider. The following code illustrates view component basic registration:

   var componentDescriptor = {
       name: 'Customer Location',
       type: 'com-example-samplelibrary-customer-location',
       bundleId: 'com.example.samplelibrary'
   };
     
   rxViewComponentProvider.registerComponent(componentDescriptor);
   
   

Component descriptor properties

The following table describes the component descriptor properties:

propertiesByName configuration

This configuration describes all properties which are needed for the view component during runtime.

The following code illustrates registration of a view component with propertiesByName configuration:

rxViewComponentProvider.registerComponent({
    name: 'Customer Location',
    type: 'com-example-samplelibrary-customer-location',
    bundleId: 'com.example.samplelibrary',
  
    propertiesByName: [
        {
            name: 'customerName',
            isConfig: true,
            isProperty: true,
            isRequired: true
        },
        {
            name: 'selectedCustomer',
            isPropery: true
        }
    ]
});

Design time configuration

By default, a view component does not require any custom configuration logic. The View designer automatically creates all the required configurations based on the component descriptor. You may add custom configuration logic for configurations such as:

• complex inspector configuration
• saving and restoring complex component definition
• controlling the appearance of the view component in the View designer canvas
• complex user input validation
  
  

To implement the custom configuration, perform the following steps:

1. Create a model that extends the default rxViewComponentModel.

   angular
       .module('com.bmc.samplelibrary.view-components.customer-location')
       .factory('CustomerLocationModel', function (rxViewComponentModel) {
           var CustomerLocationModel = rxViewComponentModel.extend({
               initialize: function(){
                   // launch parent initialize method
                   rxViewComponentModel.prototype.initialize.apply(this, arguments);
     
                   // provide your custom initialization
               },
     
               // ... customize other model methods
           });
     
           return CustomerLocationModel;
       });
   
   

2. Create a design manager. 
   Design manager is a regular angular service. To register a service as a view component design manager, it must be specified in the view component descriptor. 

   // create angular service 
   angular.module('com.example.samplelibrary.view-components.customer-location')
       .factory('comExampleSamplelibraryCustomerLocationDesignManager', function(CustomerLocationModel){
           return {
               getModel: function(componentDefinition){
                   return new CustomerLocationModel();
               },
     
               someCustomeMethod: function(){
                   //...
               }
           };
   });
     
   // register service as design manager
   rxViewComponentProvider.registerComponent({
       designManagerService: 'comExampleSamplelibraryCustomerLocationDesignManager',
       // ...
   });

   When you provide a custom design manager, the View designer always uses the custom design manager and not the default design manager service.

3. Create a design time directive.

   Design time directive is a regular Angular directive. See Design time directive.

   angular.module('com.example.samplelibrary.view-components.customer-location)
       .directive('comExampleSamplelibraryCustomerLocationDesign', function () {
           return {
               restrict: 'E',
               templateUrl: '/scripts/view-components/customer-location/com-example-samplelibrary-customer-location-design.html'
     
               scope: {
                   rxConfiguration: '='
               }
           };
       });

4. Register the design-time directive by using the designType property of the component descriptor.

   // register design directive
   rxViewComponentProvider.registerComponent({
       designTime: 'com-example-samplelibrary-customer-location-design',
       // ...
   });

Design-time directive 

Design-time directive represents how a view component is displayed on the canvas in the View designer. It provides the functionality for configuring and storing the view component properties in the component definition object. The View designer uses the design manager for creating the model which can store the definition. 

Component definition

Component definition is a representation of a view component in a view definition.

Sample component definition:

{
      "resourceType": "com.bmc.arsys.rx.services.view.domain.ViewComponentDefinition",
      "guid": "dac5ae7b-7bac-4997-97e0-4ef59364e011",
      "type": "com-example-samplelibrary-customer-location",
      "propertiesByName": {
        "customerName": "Customer A"
      }
}

Where,

{
        "customerName": "Customer A"
      }

rxViewComponentModel

rxViewComponentModel is the default model that is used by a view component. You can extend this model to create a design manager. The rxViewComponentModel provides the following feature:

• stores component configuration
• configures the property pane
  
• implements validation
• saves component definition

 The following table lists the rxViewComponentModel properties:

{
    customerName: "Customer A"
}

{
    inputs: {
        rxData: {
            title: {
                label: 'Title',
                type: 'text',
                group: 'general',
                index: 1
            }
        }
    },
     
    groups: {
        general: {
            label: 'General',
            index: 1
        }
    }
}

The following table lists the rxViewComponentModel methods:

Validation issue

Validation issue is an object that describes the details of a single view component configuration validation issue. Validation issues are displayed on the Validation Issues tab in the view designer.

 The format for validation issue object is as follows: 

 The following image illustrates how the properties defined in the validation issue object appear in the View designer:

Design manager

Design manager is to create view component model and configure the data dictionary for the expression builder. If you do not provide a design manager when you register a view component, the default manager, rxViewComponentManager is used. 

Design manager methods

getModel: function (componentDefinition) {
    return new rxViewComponentModel({
        guid: 'dac5ae7b-7bac-4997-97e0-4ef59364e011',
        type: 'com-example-samplelibrary-customer-location',
        rxData: {
            customerName: componentDefinition.propertiesByName.customerName
        },
        rxInspector: {
            inputs: {
                rxData: {
                    customerName: {
                        label: 'Customer Name',
                        type: 'rx-inspector-expression-node-field',
                        group: 'properties',
                        index: 0
                    }
                }
            },
            groups: {
                properties: {
                    label: 'General',
                    index: 1
                }
            }
        }
    });
}

Expressions

An expression is a string that can be evaluated to a value during runtime.

For example:

expression: '1 + 2'
evaluated value: 3

 When you register a view component, you can mark any property with enableExpressionEvaluation. It means that the property value is automatically evaluated at runtime and passed to the runtime directive. Expressions may contain references to properties of multiple view components in the current view, as well as view input parameters and keywords. This mechanism allows view components to share data.

Additional resource

To add your resources such as images, JavaScript, and so on to a custom view component, see the developer community post  How to add your resources to a custom view component .

Section 508 compliance

All BMC built-in view components in BMC Helix Platform and all BMC built applications running on BMC Helix Platform are Section 508 compliant and are accessible by the visually impaired. 

Related topics

Example of creating a custom view component

Creating custom view components for record editor

Creating custom actions

Enabling logging for a Digital Service application

Enabling browser logging in a Digital Service application

Naming conventions for AngularJS objects