List-Details (Employee)

List-Details (Employee)

Asset Version: 2.0.1
  • Version 2.0.1
  • Version 2.0.0
  • Version 1.0.0
Last Published: May 10, 2018 By: Kony Team
960 3 0 209
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
  • Kony Fabric
 

Devices

 

Platforms


Features

  • It includes sample employee data
  • List-Details layout pre-configured for displaying Employee data
  • Easily configurable- customize as per your requirement
  • Connect with any backend data source 
  • List view comes with preconfigured Search and dictionary

Prerequisites

  • Kony Visualizer v8
  • Kony Fabric v8

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 V8 SP1 Fixpack 16 and above

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. On the My Libraries tab, select the defined Marketplace library from the drop-down list in which the component exists.
    library.png
  3. 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 Controllers section to access the respective formController. Create a method and implement the code snippet similar to the sample code mentioned below.
/* creating a component's Object */
var listdetail = new com.konymp.listdetail(
{
	"clipBounds": true,
	"height": "100%",
	"id": "listdetail",
	"isVisible": true,
	"left": "0dp",
	"skin": "sknID",
	"top": "0dp",
	"width": "100%",
	"zIndex": 1
}, {}, {});

/* Setting component's properties */
listdetail.defaultProfile = "konymp_ld_profile.png";
listdetail.defaultCover = "konymp_ld_cover.png";
listdetail.defaultStatus = true;
listdetail.hideHeader = true;
listdetail.headerText = "Directory";
listdetail.searchSrc = "konymp_ld_search.png";
listdetail.leftSrc = "konymp_ld_menu_icon.png";
listdetail.rightSrc = "kony_ld_filter_icon.png";
listdetail.flxDictionaryVisible = 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.

General

Dictionary
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
Status Icon
Description: Enables status of an employee in both List and Detail Screen.
Syntax: defaultStatus
Type: Boolean
Read/Write: Read + Write
Remarks: The default value of the property is true
Example:
this.view.ComponentID.defaultStatus = true

Header

Visibility
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;
Text
Description: Specifies the text for the Header in List screen.
Syntax: headerText
Type: String
Read/Write: Read + Write
Example:
this.view.ComponentID.headerText = "Directory";

Search

Search
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;
Placeholder Text
Description: Specifies the placeholder text for Search in List screen.
Syntax: searchText
Type: String
Read/Write: Read + Write
Example:
this.view.ComponentID.searchText = "Search";
Inactive Icon
Description: Specifies the Inactive icon for search in the List screen.
Syntax: src
Type: String
Read/Write: Read + Write
Example:
this.view.ComponentID.src= "konymp_ld_search.png";
Active Icon
Description: Controls whether or not to display the search box in the list screen.
Syntax: searchSrc
Type: String
Read/Write: Read + Write
Remarks: The default value of the property is true.
Example:
this.view.ComponentID.searchSrc= "konymp_ld_search.png";
Cancel Text
Description: Specifies the cancel text once the data is entered in search field.
Syntax: cancelText
Type: String
Read/Write: Read + Write
Example:
this.view.ComponentID.cancelText = true;

Hamburger Menu

Visibility
Description: Specifies the visibility of Hamburger Menu on top left corner of List Screen.
Syntax: leftVisible
Type: Boolean
Read/Write: Read + Write
Example:
this.view.ComponentID.leftVisible= true;
Icon
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= "konymp_ld_menu_icon.png";

Filter Menu

Visibility
Description: Specifies the visibility of Filter Menu on the top right corner of the List Screen.
Syntax: rightVisible
Type: Boolean
Read/Write: Read + Write
Example:
this.view.ComponentID.rightVisible= true;
Icon
Description: Specifies the image for Filter Menu in the List screen.
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= "kony_ld_filter_icon.png";

Images

List Profile Image
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 The dimensions of the profile image must be 128px X 128px.
The image must be circular in shape.


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 = "konymp_ld_profile.png";
Detail Cover Image
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= "konymp_ld_cover.png";

Details Screen

Header Back Icon
Description: Specifies the image for background of header in Details Screen.
Syntax: src1
Type: Boolean
Read/Write: Read + Write
Example:
this.view.ComponentID.src1 = "konymp_ld_.png";
Call Mobile Icon
Description: Specifies the image for Mobile icon in the Details Screen.
Syntax: src5
Type: Boolean
Read/Write: Read + Write
Example:
this.view.ComponentID.src1 = "konymp_ld_.png";
Call Work Icon
Description: Specifies the image for Work icon in the Details Screen.
Syntax: src4
Type: Boolean
Read/Write: Read + Write
Example:
this.view.ComponentID.src4 = "konymp_ld_.png";
Email Icon
Description: Specifies the image for email in the Details Screen.
Syntax: src3
Type: Boolean
Read/Write: Read + Write
Example:
this.view.ComponentID.src3 = "konymp_ld_.png";

Skin Section

Header

Search
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;

Dictionary Alphabet Focus

Right Menu Visibility
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.This value will be rendered only at run time.
Example:
this.view.ComponentID.rightVisible= true;

Dictionary Selected Index

Right Menu Visibility
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;

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
Description: The event is invoked when a user clicks left menu icon.
Syntax: leftMenuClick()
rightMenuClick
Description: The event is invoked when a user clicks right menu icon.
Syntax: rightMenuClick()

Configuring the Kony Fabric App

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

Note:

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

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

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

The following sections help you use the Kony Fabric app.

 

Publishing Sample App to Kony Fabric

Once the app is imported to Visualizer, you must publish the same in Kony Fabric application. Publishing the app can be done in two ways:

 

From Visualizer

  1. In Kony Visualizer, click File menu.
  2. Click Publish to Kony Fabric to publish the app.

From Kony Fabric

  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.
  5. Click Publish.

Configuring Kony Fabric Services

The ListDetail Kony Fabric app contains a set of orchestration, and objects services by default. Using the Kony Fabric 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 Kony Fabric storage. The EmployeeModelSchema is the data model schema for the Kony Fabric data storage.

The ListDetail Kony Fabric 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 Kony Fabric 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 Kony Fabric 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 Kony Fabric storage. You can easily decouple the app data model with the Kony Fabric 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 Kony Fabric 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.

Inserting data into database

Employee : {
"Department_id": "", // id exists in department table
"Designation_id": "", // id exists in designation table
"Employee_id": "", // primary key for this table
"First_name": "", // First name
"Last_name": "", // Last name
"Location_id": "", // id exists in location table
"Manager_id": "", // employee id
"Status_id": "", // id exists in status table
"CreatedBy": "",
"CreatedDateTime": "",
"LastUpdatedBy": "",
"LastUpdatedDateTime": "",
"SoftDeleteFlag": ""
}

Contact : {
"Contact_id": "", // primary key for the table
"Contact_type_id": "", // 1 for mobile(personal) 2 for office 3 for mail_id
"CreatedBy": "",
"CreatedDateTime": "",
"employee_id": "", // Self explanatory
"Is_primary": "", // 0 or 1
"LastUpdatedBy": "",
"LastUpdatedDateTime": "",
"SoftDeleteFlag": "",
"Value": "" // Self explanatory
}

Department :
{
"CreatedBy": "",
"CreatedDateTime": "",
"Department_id": "", // primary key for this table
"LastUpdatedBy": "",
"LastUpdatedDateTime": "",
"Name": "", // department name
"SoftDeleteFlag": ""
}

Designation : {
"CreatedBy": "",
"CreatedDateTime": "",
"Designation_id": "", // primary key for this table
"LastUpdatedBy": "",
"LastUpdatedDateTime": "",
"Name": "", // designation name
"SoftDeleteFlag": ""
}

Media:

Media : {
"employee_id": "",
"Extension": "",
"Image": "",
"Media_id": "",
"Media_name": "", // must be "profile" or "cover"
"Media_type_id": "", // can be ignored
"Url": "", //URL of the image
"CreatedBy": "",
"CreatedDateTime": "",
"LastUpdatedBy": "",
"LastUpdatedDateTime": "",
"SoftDeleteFlag": ""
}

Status : {
"CreatedBy": "",
"CreatedDateTime": "",
"LastUpdatedBy": "",
"LastUpdatedDateTime": "",
"Name": "", // Status name
"SoftDeleteFlag": "",
"Status_id": "" // primary key for status table
}

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.