Skip to content

Create a Component

The most powerful way to create reusable components is to create a component that includes a defined contract. The contract is a JSON file that specifies the component's exposed properties, events, and methods. You can specify those properties, events, and methods within the Iris interface, and then define the behavior of custom properties, events, and methods by adding code to the component's controller module.

When you create a component, you have a choice of creating a component with or without a contract. A component without a contract is similar to a master in earlier versions of Volt MX Iris, except that it includes a controller module. You can also convert a component that does not have a contract, or an imported master, to a component with a contract.

Once you create a component with a contract, you can control what is exposed to users of the component. You expose only the properties, events, and methods that you want to make available to your target audience, enhancing your ability to rapidly create and deploy digitalapplications for different audiences. The exposed properties, events, and methods are part of the contract.

You can then use the component in other applications, or share your custom components with other digital application developers by publishing them to HCL Forge . For more information about using components, see Using Components.

Important: Parent value for components will always be null. In component controller code, this.view.parent will always return a null value.

The following topics provide additional information about creating components:

Create a Component Without Contract

A component without contract is similar to a Master in earlier versions of Volt MX Iris, except that a component includes a Controller module. You can reuse the component within your application and distribute it via HCL Forge . However, you cannot control which of the component's properties, events, and methods are exposed, or create custom properties, events, and methods. To control the exposed properties, events, and methods of a component, create a component with contract.

To create a component without contract, follow these steps:

  1. In the Project Explorer, click the Templates tab.
  2. Right-click Components, point to New, and then select w/o Contract. The Create new Component without Contract dialog box appears.

  3. Enter a Namespace ,Name and Version for the component.

    The component must follow this naming convention: .; for example, my.namespace.
    The component version helps you track changes or upgrades made to the component.

    The new component without contract is created. The component includes a FlexContainer to contain any widgets that you add to the component and a Modules node, comprising the component's Controller and Actions Controller JavaScript files. The Actions Controller module is auto-generated and contains any defined action sequences.

  4. Add widgets to the FlexContainer, just as you would for a standard form.

  5. Add code to the component's controller module or to actions for widgets on the form. To add code to widget actions, select the FlexContainer. On the Properties panel, on the Action tab, click Edit for the event to which you want to add code. For more information, refer Add Actions.

Create a Component With Contract

To create a reusable component that can be published to HCL Forge , create a component with contract. Components with a contract use the Volt MX Iris Reference Architecture: a structured, modular framework based on the Model-View-Controller (MVC) architecture. For more information on how to create a Volt MX Iris Reference Architecture project, refer Create a Volt MX Iris Reference Architecture Project.

To create a component with contract, follow these steps:

  1. In the Project Explorer, click the Templates tab.
  2. Right-click Components, point to New, and then select with Contract. The Create new Component with Contract dialog box appears.

  3. Enter a Namespace ,Name and Version for the component.

    The component must follow this naming convention: .; for example, my.namespace.
    The component version helps you track changes or upgrades made to the component.

    The new component with contract is created. The component includes a FlexContainer to contain any widgets that you add to the component and a Modules node, comprising the component's Controller and Actions Controller JavaScript files. The Actions Controller module is auto-generated and contains any defined action sequences.

  4. Add widgets to the FlexContainer, just as you would for a standard form.

  5. Add code to the component's controller module or to actions for widgets on the form. To add code to widget actions, select the FlexContainer. On the Properties panel, on the Action tab, click Edit for the event to which you want to add code. For more information, refer Add Actions.
  6. Manage properties, events, and methods for the component with contract. For more information, refer Manage Properties of a Component with a Contract, Manage Events of a Component with a Contract, and Manage Methods of a Component with a Contract.

Each component's controller module contains the JavaScript code associated with the component.  You can add additional modules containing any supporting code to the Modules node. The actions Controller module is auto-generated and should not be modified.

Expose a Component's Widgets

Typically, a component comprises multiple widgets. Once you create a component with a contract, you can specify which of the component's widgets to expose to users.

To expose a component's widgets:

Select a component's widget on the Iris canvas or on the Templates tab of Project Explorer.

You can select a container widget or a child widget of a container widget.

Right-click the widget and select Expose Widget, or click on the Look tab in the Properties pane and set the Expose Widget property to On.

Volt MX Iris displays the Programmatic Key property. You can use the default value or specify a different programmatic key.

Note: The Expose property will allow a component creator to make the widget visible in the form or another component. A developer who is using the component cannot access the widget directly through code.

 If you select a container widget, all widgets within the container will be exposed. If you do not want to expose an individual widget within the container widget, select the widget and set its **Expose Widget** property to _Off_.

Note: You can set the Expose Widget property of a container widget to Off but expose an individual widget within the container by setting its Expose Widget property to On.

Repeat the process for each widget that you want to expose.

Data & Services Panel Support for Components

Earlier, the ability to leverage Data & Services panel features for components was not supported in Volt MX Iris. From V8 SP4 Fixpack 20, you can directly drag and drop services from the Data & Services panel to a component. In addition, you can drag and drop individual parameters of a sample service to a component. This enhancement will enable you to quickly customize components according to your requirement, and reuse them at various places in your Volt MX Iris Classic and Volt MX Irisprojects. Furthermore, you can publish customized components to HCL Forge . You can leverage Data Panel support for both components with contract and components without contract. For more information on the Data & Services panel, click here.

Once you drag and drop a sample service from the Data & Services panel to a component, a corresponding project service is added. That particular project service and its associated parameters are auto-highlighted in the Data & Services panel. So if multiple components exist and when you select a specific component, only those services which have been added to that component are highlighted in the Project Services of the Data & Services panel. The Data & Services panel also allows you to view the mappings for each project service operation in the component. The onMapping Event of the operations in the component is not generated separately in the CodeGen. You can view the onMapping Event in the preShow Event of the component

Note: Currently, only the Details form and List form UI are supported for the drag and drop of services into a component; Entry form UI is not supported.

If the sample service that you are trying to add to a component has already been added to another component, a Conflict window appears. In such a scenario, you must perform any one of the following actions to resolve this issue:

  • Select the Skip radio button, and then click OK to use the original service.
    • If multiple instances of the same service exist and you want to use the original service, click Skip All.

  • Select the Replace radio button, and then click OK to use a new service.

    • If multiple instances of the same service exist and you want to use a new service, click Replace All.

This section contains the following topics:

How to Create a Component with Services

Create a component and leverage sample services from the Data & Services panel. You can bundle these services to the required widgets of a component. You can directly drag and drop services into a component and customize it according to your requirement.

In this scenario, we will xthe List-Details (Employee) component from HCL Forge and add services to the widgets of the component. You can add parameters (for example, Name) to specific widgets (for example, empname Label) of the component. This component contains the following two screens:

  • Employee List
  • Employee Details

To import the List-Details (Employee) component and add services to the component, follow these steps:

  1. In Volt MX Iris, create a new Sample App project , and then import the List-Details (Employee) component from HCL Forge .
    The landing page of the List-Details (Employee) component is displayed on the Project Canvas and its associated widgets are displayed in the Project Explorer.

  2. To add services to the Employee List screen, follow these steps:

    1. In the Project Explorer, go to Mobile > Forms, and then click frmList. The list screen is displayed on the Project Canvas.
    2. Go to Data & Services panel > Sample Services, and then expand Employee Services.

    3. Under the employees > get > Response > records operation, drag and drop the following parameters to the respective widgets:

      • Name > empname
      • Designation > designation
      • Department > department

  3. To add services to the Employee Details screen, follow these steps:

    1. In the Project Explorer, go to Mobile > Forms, and then click frmDetails. The details screen is displayed on the Project Canvas.
    2. Go to Data & Services panel > Sample Services, and then expand Employee Services.

    3. Under the employees > get > Response > records operation, drag and drop the following parameters to the respective widgets:

      • Designation > lblEmployeeDesignation
      • Primary_Phone > callMobileFlex
      • Email > emailFlex
      • Department > departmentFlex
      • Manager_Name > reportingToFlex

    4. Go to Data & Services panel > Sample Services, and then expand Contacts.

    5. Under the getContacts > Response > responseList operation, drag and drop the following parameters to the respective widgets:

      • Name > lblEmployeeName
      • Phone > callWorkFlex

    The parameters are mapped to the corresponding component widgets, and the services are created in your Volt MX Foundry instance. In addition, the mappings are highlighted and displayed under Project Services on the Data & Services panel.

  4. Click View Mapping for a service, and then click Generate Code to view the respective mappings of the operations in the component. Alternatively, you can go to Properties panel > Component, click Edit for the onMapping Event, and then click Generate Code.

  5. You can then reuse the updated component across your Volt MX Iris projects or publish this customized component to HCL Forge .

How to Use a Component with Services

Users can import the component with bundled services that you published on HCL Forge . They can then modify the component as per their requirement.

Consider a scenario where Valerie (a user who wants to create a CRM app) imports your Employee List-Detail component to Volt MX Iris. However, she does not want to view employee data. Instead, Valerie wants to view the data of her customers. She can use the Data Panel support for Components feature to map data from another service that fetches customer data to the widgets, wherever required. Valerie can leverage an Object service to fetch the data, and she can directly map the response parameters from the Data & Services panel.

Valerie can follow these steps to import the Employee List-detail component from HCL Forge and customize the services bundled with it:

  1. Create a new project in Volt MX Iris, and then import the component to Collection Library.
  2. Create a new form, say frm1.
  3. Drag and drop the component from Collection Library to frm1. The component is added to the form and the bundled services are displayed under Project Services of the Data & Services panel.

  4. For the List and Details screen, add response parameters of the required Object service (that fetches customer data) to the corresponding widgets of the component. Response parameters of other services (such as Contacts) can also be used wherever necessary. The new parameters are mapped to the corresponding component widgets, and the services are created in Volt MX Foundry. Furthermore, the mappings are highlighted and displayed under Project Services on the Data & Services panel.

  5. Click View Mapping for the service, and then click Generate Code to view all the mappings of the parameters in the component.
    Alternatively, you can go to Properties panel > Component, click Edit for the onMapping Event, and then click Generate Code.

  6. This component can now be used in the CRM app to display the list of customers on the Customer List screen and specific customers' information on the Customer Details screen.

Specify a Container Widget as a Target Container

A target container is a Container widget that can contain other child widgets. To specify a Container widget as a target container, set both its Expose Widget and Set As Target Container properties to On.

To specify a Container widget as a target container:

  1. Select the container widget on the Iris canvas or on the Templates tab of Project Explorer.
  2. Click on the Look tab in the Properties pane.
  3. Set the Expose Widget property to On, and then set the Set As Target Container property to On.

Note: If the Expose Widget property is set to Off, setting the Set As Target Container property to On will set both the Expose Widget and Set As Target Container properties to On.

Volt MX Iris displays the Placeholder property. The Placeholder property lets you specify further information or direction to a user; for example "Add Content Here" or "Drop Image Here."

Expose a Component's Skins

In addition to specifying which of a component's widgets to expose to users, you can specify the skins to expose.

To expose a component's skins:

  1. Select the component on the Iris canvas or on the Templates tab of Project Explorer.
  2. Select the Skin tab in the Properties pane and select the skin that you want to expose.
  3. Set the Expose Skins property to On.
  4. Repeat the process for each skin that you want to expose.

Lock a Component

To prevent your component from being modified by users, you can lock the component. Users will not be able to view or modify the component's source code.

To lock a component:

  1. Select the component on the Iris canvas or on the Templates tab of Project Explorer.
  2. Right-click the component and select Lock.

Manage Properties of a Component with a Contract

Once you create a component with a contract, you can specify which properties of the component to expose to users. The specified properties are called pass-through properties. You can also define custom properties.