List-Details (Employee)

List-Details (Employee)

Asset Version: 1.0.0
  • Version 1.0.0
Last Published: Apr 27, 2017 By: Kony Team
224 1 0 33
The component displays a master list of employees. Select an employee and Details screen comes up with more information on that employee. Built in Search and Dictionary allows users to quickly navigate through the list. You can easily connect it to your backend and customize as per your requirement.

Requirements

  • Visualizer Enterprise
  • MobileFabric
 

Devices

 

Platforms

Features

  • List-Details layout preconfigured for displaying Employee data
  • Easily configurable- customize as per your requiement
  • Connect with any backend data source 
  • List view comes with preconfigured Search and dictionary

Platforms Supported

  • Android Phone Native
  • iPhone Native

Prerequisites

  • Kony account
  • Kony Visualizer Enterprise 7.3
  • Kony MobileFabric 7.3
  • A Kony Reference Architecture app created in Kony Visualizer

List/Details component is a highly configurable component which basically consists of two views( List view and Details view). List screen displays a master list of all employees. When a user selects an employee, additional information about the selected employee is displayed on Details screen. Employees can use the built-in features such as Search and Dictionary to quickly navigate through the list and find any employee.

Use Case

Consider that you are developing an employee directory app which displays a list of all employees working in an organization. When a user selects an employee, more information about that employee will be displayed. You can use List/Details Component here and develop the app in few hours.

You can import the List/Details component into your app (created in Kony Visualizer), and achieve the features of List/Details Component. The List/Details component facilitates a set of properties that help you customize the fields and functionality if required.

The following sections help you use the List/Details component in your app.

Prerequisites

Before you start using the List/Details component, ensure you have the following:

  1. Kony account
  2. Kony Visualizer 7.3
  3. A Kony Reference Architecture app in Kony Visualizer. You can create a Kony Reference Architecture app in Kony Visualizer using the following procedure:
    1. On the File Menu, click New Project. The New Project dialog appears.
    2. In the Project Name box, type a name for your project.
    3. Select Kony Reference Architecture, and click Create.

Importing the List/Details Component

Before you start importing the component to Kony Visualizer, you must download the component from Kony Marketplace. You can import the marketplace components only into the apps that are of the Kony Reference Architecture type.

  1. Open your app project in Kony Visualizer.
  2. On the File menu, point to Import, and click Component. The Open dialog appears.
  3. Navigate to the location where you downloaded the component (zip file) on your computer, select the component, and click Open. The Import Marketplace Item dialog appears.
    listdetail_import.png
  4. In the Library Name box, type a name if you want to create a new library. Otherwise, you can select the existing library name.
  5. In the Collection Name box, type a name if you want to create a new collection. Otherwise, you can select the existing collection name.
  6. In the Component Name box, the com.konymp.listdetail name is displayed by default. If you want, you can rename it.

When you import a component, the component will be imported to Visualizer's workspace, but not directly into your app. So after importing a component, you must add the component to your app.

Adding a List/Details Component into your App

To add a List/Details component:

  1. Open your app, and then open the form to which you want to add the component.
  2. From the Collections tab, drag the component onto the form on the Visualizer canvas. The component will be added to the form.
    Once you drag the component to a form, you will see the component added to the form. You will also see a new element, com.konymp.listdetail under the Component section on the Templates tab.

After adding a component to a form, you can configure the component the way you want it using the Look, Skin, and Action tabs on the Properties pane. Configuring the properties on the Properties pane is similar to configuring the properties of any widget in Kony Visualizer. For more information, refer to Button Widget.

You will also see a new tab, Component, added on the Properties pane. The Component tab contains assorted properties relevant to the component that allow you to customize the component as required. The properties on the Component tab are categorized as Pass Through and Custom properties. The Pass Through properties are the default properties of individual widgets in the component. Custom Properties are user-defined properties based on the use case of the component.

Note:

Changes made to the Custom properties are reflected only at the run time, but not at the design time (Visualizer Canvas).

You can also add a List/Details component dynamically. To do so,

  1. In the Project Explorer, on the Projects tab, click the context menu arrow of Modules, and then click New JS module. A new JavaScript file opens in the Code Editor.
  2. Copy and paste the following code snippet in the file.
/* creating a component's Object */
var listdetail = new com.konymp.listdetail({
                "clipBounds": true,
                "height": "100%",
                "id": "listdetail",
                "isVisible": true,
                "left": "0dp",
                "skin": "CopyslFbox0i25b6c13d6274d",
                "top": "0dp",
                "width": "100%",
                "zIndex": 1
            }, {}, {});
/* Setting component's pass-through and custom properties */
            listdetail.defaultProfile = "profile.png";
            listdetail.Dictionary = true;
/*Adding Component to the Form*/
            this.view.add(listdetail);

              

In the code snippet, you can edit the properties of the component as per your requirement. For more information, see Properties.

Save the file.

Setting Properties

The Properties provided in the Component tab allow you to customize the UI elements and set constraints for fields in the List/Details component. You can set the properties directly on the Component tab or by writing a JavaScript.

Dictionary
Category: Pass Through
Description: Controls whether or not to enable the dictionary in the list screen.
Syntax: flxDictionaryVisible
Type: Boolean
Read/Write: Read + Write
Remarks: The default value of the property is true
Example:
this.view.ComponentID.flxDictionaryVisible = true;

Replace the "ComponentID" with the ID of the component in all examples in this document.
You can find the ID of the component on the Look tab.

Default Cover Image
Category: Custom
Description: Specifies the file name of the image to be set as the default user cover image.
Syntax: defaultCover
Type: String
Read/Write: Read + Write
Remarks

Before setting the property:

  • Ensure that the image file exists in the workspace\resources\common directory.
  • Do not add any uppercase characters in the file name of the image.
  • Ensure that the image is in PNG format.
  • Specify the file name of the image along with the extension.
Example:
this.view.ComponentID.defaultCover= "cover.png";
Default Profile Image
Category: Custom
Description: Specifies the file name of the image to be set as the user profile image.
Syntax: defaultProfile
Type: String
Read/Write: Read + Write
Remarks

Before setting the property:

  • Ensure that the image file exists in the workspace\resources\common directory.
  • Do not add any uppercase characters in the file name of the image.
  • Ensure that the image is in PNG format.
  • Specify the file name of the image along with the extension.
Example:
this.view.ComponentID.defaultProfile = "profile.png";
Header
Category: Custom
Description: Controls whether or not to display the Header in the List screen.
Syntax: hideHeader
Type: Boolean
Read/Write: Read + Write
Remarks The default value of the property is true
Example:
this.view.ComponentID.hideHeader = true;
Left Menu Icon
Category: Pass Through
Description: Specifies the file name of the image to be set as the Left Menu Icon.
Syntax: leftSrc
Type: String
Read/Write: Read + Write
Remarks

Before setting the property:

  • Ensure that the image file exists in the workspace\resources\common directory.
  • Do not add any uppercase characters in the file name of the image.
  • Ensure that the image is in PNG format.
  • Specify the file name of the image along with the extension.
Example:
this.view.ComponentID.leftSrc= "menu_icon.png";
Left Menu Visibility
Category: Pass Through
Description: Controls whether or not to display the Left Menu Icon.
Syntax: leftVisible
Type: Boolean
Read/Write: Read + Write
Remarks

The default value of the property is true.

Example:
this.view.ComponentID.leftVisible= true;
Right Menu Icon
Category: Pass Through
Description: Specifies the file name of the image to be set as the Right Menu Icon.
Syntax: rightSrc
Type: String
Read/Write: Read + Write
Remarks

Before setting the property:

  • Ensure that the image file exists in the workspace\resources\common directory.
  • Do not add any uppercase characters in the file name of the image.
  • Ensure that the image is in PNG format.
  • Specify the file name of the image along with the extension.
Example:
this.view.ComponentID.rightSrc= "filter_icon.png";
Right Menu Visibility
Category: Pass Through
Description: Controls whether or not to display the Right Menu Icon.
Syntax: rightVisible
Type: Boolean
Read/Write: Read + Write
Remarks

The default value of the property is true.

Example:
this.view.ComponentID.rightVisible= true;
Search
Category: Custom
Description: Controls whether or not to display the search box in the list screen.
Syntax: searchList
Type: Boolean
Read/Write: Read + Write
Remarks: The default value of the property is true.
Example:
this.view.ComponentID.searchList= true;
Status Icon Visibility
Category: Pass Through
Description: Controls whether or not to display the status icon for a user.
Syntax: defaultStatus
Type: Boolean
Read/Write: Read + Write
Remarks: The default value of the property is true.
Example:
this.view.ComponentID.defaultStatus = true";

Defining Events

You can define events to be executed when an action is performed. You can configure the events directly on the Actions tab or by writing a JavaScript. To configure the events on the Action tab, click Edit against each event. For more information, refer to Add Actions.

leftMenuClick
Category: Pass Through
Description: The event is invoked when a user clicks left menu icon.
Syntax: leftMenuClick()
rightMenuClick
Category: Pass Through
Description: The event is invoked when a user clicks right menu icon.
Syntax: rightMenuClick()

 

Configuring the MobileFabric App

When you import the List/Details component into Kony Visualizer, a MobileFabric app (with name same as your Visualizer Project Name) is also uploaded to your Kony account.

Note:

The name of the MobileFabric app is same as your Kony Visualizer Project Name.

The MobileFabric app fails to upload if already any app exists with the same name.

Using the MobileFabric console, you can configure the app-related orchestration and object services, and then publish the app.

The following sections help you use the MobileFabric app.

 

Importing Sample data

Sample employee data is bundled with the List/Details component. It is available as the EmployeeModelSchema.zip file which is bundled with the component and can be found in your Visualizer workspace. Path \<works pace>\<project name>\resources\mobile\common\raw\ EmployeeModelSchema.zip
To import the sample data, do the following:

  1. Log on to your Kony account. The Dashboard page appears by default.
  2. In the left pane, click the Apps menu. The Custom Apps page appears.
  3. Find and click the ListDetail (your project's name) app. .
  4. Click the Publish tab. The Publish tab opens. You must publish the app at least once before importing the sample data.
  5. In the Publish tab, In your environment box, in the RUNTIME CONSOLES section, click object services icon (highlighted in the following figure). The Object Services page appears.

    listdetail_sampledata1.png

  6. Find the EmployeeModelSchema object service by typing in the app name search box. Click import icon (highlighted in the following figure) and select the EmployeeModelSchema.zip file located in your Visualizer workspace.
    Path \<works pace>\<project name>\resources\mobile\common\raw\ EmployeeModelSchema.zip

    listdetail_sampledata2.png

Configuring MobileFabric Services

The ListDetail MobileFabric app contains a set of orchestration, and objects services by default. Using the MobileFabric console, you can view and modify these services and also create new services.

Orchestration Service

Orchestration services are used to integrate multiple services and form a single service. We use the EmployeeStorageObjects orchestration service to fetch all the data objects in the mobile app in one go (to reduce the number of service calls). If you don't want to fetch all the data objects in one go, then delete the EmployeeStorageObjects orchestration service (and the StorageObjectService which is a service driven object or wrapper on EmployeeStorageObjects orchestration service)

To view the orchestration services, do the following:

  1. After logging on to your Kony account, open the ListDetail(your project's name) app.
  2. Click the Orchestration sub-tab. The Orchestration sub-tab opens with a list of services.
  3. Click on the EmployeeStorageObjects service. The Service Definition tab of the selected orchestration service opens by default.
  4. Click Operations tab to view the operations of the selected service.

    listdetail_orchservice.png

    EmployeeStorageObjects service contains the getAllDetails operation. The operation fetches and combines all the data objects from EmployeeModelSchema.

Object Services

The object services helps you define the app data model and map it with relevant back end services. In the object service, you can view all the objects of the data model and the default fields and relationships of each object. To learn more about object services and mapping, see Object Services.

By default, the ListDetail component is mapped with the MobileFabric storage. The EmployeeModelSchema is the data model schema for the MobileFabric data storage.

The ListDetail MobileFabric app contains the following object services:

  1. EmployeeModelSchema service contains the Employee data model
  2. StorageObjectService service acts as a service driven object for the orchestration service (wrapper around the orchestration service EmployeeStorageObjects).

To view the object service and its operations, do the following:

  1. After logging on to your Kony account, open the ListDetail(your project's name) app.
  2. Click the Objects sub-tab. The Objects sub-tab opens with a list of data models.
  3. Click any one of the data models. For example, EmployeeModelSchema. The Service Definition tab of the selected service opens by default.

    listdetail_objservice.png

Mapping List/Details Data Model (Object services) with a back end Data Source

List/Details component comes pre-configured with Employee Data Model (by default mapped to MobileFabric Storage). The data model contains multiple objects and fields related to employee information. The following diagram illustrates the objects in the data model and relationships among them.

 

lisdetail_datamap.png

The app data model is created as an object service. Using the MobileFabric console, you can modify the fields and relationships of the objects in the data model. For example, you can add new fields to objects and define new relationships between objects.

By default, the ListDetail is mapped to the MobileFabric storage. You can easily decouple the app data model with the MobileFabric storage and map it with other back end data source.

To map with a back end data source, do the following:

  1. On the ListDetail MobileFabric app page, click the Configure Services tab, and then click Objects sub-tab. The Objects sub-tab opens along with the EmployeeModelSchema object service listed.
  2. Click the context menu icon of EmployeeModelSchema as shown in the following figure. The context menu opens.

    listdetail_cloneappdata.png

  3. Click Clone App Data Model. A copy of Employee App Data Model is created and the New Object Service page appears.

    listdetail_endpoint.png

  4. In the Name box, type a name for a copy of Employee App Data Model.
  5. Click the context menu arrow to expand the Endpoint Type list. A drop-down list opens.
  6. Select the required back end data source that you want to map and click SAVE & CONFIGURE.

Modifying the Data Model

The EmployeeModelSchema object service allows you to modify the app data model as you require. You can edit/delete/add objects and fields in the data model based on your requirement. Every object in the object service contains the following sections:

Fields

In the Fields section of an object, you can add new fields and edit and delete the fields associated with the object. Every object has a set of fields that you cannot edit or delete. For example, the CreatedBy and CreatedDataTime fields of the Contact_type_id object cannot be modified.

Relationships

In the Relationships section of an object, you can define new relationships with other objects and edit and delete existing relationships of the object.

For more information, refer to Object Services.

After making the modifications in the app data model you also need to change the data object mappings with UI widgets. Steps are mentioned in Mapping data from Object Services section.

We are fetching all the data at once using getAllDetails operation of StorageObjectServices (which is a service driven object (wrapper) of the orchestration service EmployeeStorageObjects).
If you don’t want the mobile client to fetch all the data at once, then you don’t need to use these services. Delete the services and directly bind the data objects of EmployeeModelSchema with the UI widgets in the app.
However, If you want to fetch all the data at once on the client side, then after adding/deleting an object from the app data model you need to add/delete that object in the orchestration service EmployeeStorageObjects.

Note:

You can also delete the existing Employee Data Model and use a completely new app data model. In that case, you need to associate the new object services with the UI. Steps are mentioned in Mapping data from Object Services section.

 

Mapping UI with Data from Object Services

You can easily map UI widgets with object services. As an example- following screenshot illustrates the process of mapping the data to the List view segment.

lisdetail_dataobjects.png

  • As shown above, List view has following widgets- empname, designation, department, empimage
  • Employee, Designation, Department, and Media are the Object Services
  • First_Name, Last_Name, Name, and Image are the fields in the respective Object Services

List UI mapping with object services can be represented as follows:

List[“empname”] = Employee[“First_Name” + ”Last_Name”];
List[“designation”] = Designation[“Name”];
List[“department”] = Department[“Name”];
List[“empimage”] = Media[“Image”];

  

Note:

We are fetching all the data at once in the mobile app (to reduce the number of service calls) using the getAllDetails operation of StorageObjectServices (which is a service driven object (wrapper) of the orchestration service EmployeeStorageObjects). If you do not want to fetch all the data at once, then you don’t need to use these services. Delete these services and directly bind the data objects of EmployeeModelSchema and assign them to the UI of widget.

Modifying the List/Details UI

You can easily modify the UI of the List/Details component to suit your requirements

Example:

To modify the List screen UI, do the following:

  1. In the Project explorer, click the Template tab. A list of templates is displayed.
  2. Go to Mobile >> Segments >> datacontainer (segRowTemplate)
  3. Modify/ Delete/ Add widgets to the datacontainer template as per your requirement.
  4. You can also configure data mapped to a widget. Refer Mapping UI with Data from Object Services.

The following screenshots illustrate how to remove the designation Label Widget from the row template.

listdetail_listview.png

listdetail_listview1.png

 

To modify the Details screen, do the following:

  1. In the Project explorer, click the Template tab. A list of templates is displayed.
  2. Go to Components >> com.konymp.listdetail >> listdetail >> flxDetailsScreen
  3. Modify/ Delete/ Add widgets as per your requirement.
  4. You can also configure data mapped to a widget. Refer Mapping UI with Data from Object Services.

The following screenshots illustrate how to re-arrange “callMobileFlex” flex.

listdetail_detailview.png

listdetail_detailview1.png

listdetail_detailview2.png

Similarly, you can delete other widgets or rows. If you wish to add new rows in details screen, you can directly copy one of the existing flexes or add a completely new flex. The List/Details component also comes with a few additional flexes. To use the additional flexes, turn on the visibility of the flex.