In this tutorial, you will learn how to customize your display cards, forms, and collections in xDM to enhance the user experience of your employee application.

Learning outcomes

Learning track

This tutorial is the third unit of the Data Authoring track. Make sure to complete the first two units, Build your first data authoring application and Data quality, before starting this tutorial.

If you have not completed these prerequisites, return to the Tutorials menu.

GO TO TUTORIALS

Also, if you have not already done so, click the button below to download resources such as the images and data sets that will be used in this tutorial.

DOWNLOAD TUTORIAL RESOURCES

Display cards define the visual representation of a record in a nicely formatted way. They appear in collections displayed as lists, tables, or grids. They also appear in form headers or as chips to display a reference to a record.

In this section, you will be guided to customize two different display cards.

Learning outcomes

Customize the Employee card

You are now going to customize the display card of the Employee entity by adding a primary and a fallback image.

  1. In the Application Builder, open the HRTutorial model.
  2. In the Model Design view, navigate to Entities > Employee > Display Cards, and open the EmployeeDisplayCard.

  1. In the Image section of the editor, in the Primary Image property, select SemQL from the drop-down menu.

  1. Enter the following values:

  1. Next to the Fallback Image property, click the Select Image button.

  1. Search for view-profile and select the image returned.

  1. In the Avatar section, in the Avatar property, select SemQL from the value type drop-down menu.

  1. Enter the following values:

  1. Save your work.

Add more cosmetic elements

You are now going to adapt the EmployeeCollection and add an icon to the department display card from the image library.

  1. Under the Employee entity, expand the Collections node and double-click EmployeeCollection.

  1. Select the Overview tab.

  1. In the List section, select Show Avatar.

  1. In the Grid section, select Allow Grid.

  1. Save your work.
  2. Go to Entities > Department > Display Cards and then double-click DepartmentDisplayCard.

  1. In the Avatar section, next to the Avatar property, click the Select Image button.

  1. Search for domain.svg and select the image returned.

  1. Save your work.

Refresh and observe results

Since you did not change any rules in your model besides the display card images, you do not need to re-deploy your model. You only need to refresh your application.

  1. Go to your Employee Tutorial application, open the user menu in the top-right corner, and click Refresh Application.

  1. In the navigation drawer, select the Departments business view. Notice that departments now have an avatar icon.

  1. Select the Employee business view and sort records by first name.
  2. Select the following employees by clicking their avatar:
  1. Click Edit in the Options menu.

  1. Scroll down to the end of the form and click the cloud icon to upload.

  1. Select the picture data-authoring\employees\alyssa.png from the tutorial resources and click Edit next.
  2. Repeat the same process for the other two employees:
  1. Click Go to list.
  2. Click Finish.

  1. When the toaster indicates "Changes successfully applied," click Click to refresh.

  1. Notice how the pictures you uploaded now display as avatars.

  1. In the Options menu, click List view to display the Employees collection as a list.

  1. In the Options menu, Grid view to display the Employees collection as a grid.

  1. In the Options menu, click Table view to switch back to the default view.

Congratulations!

You have enhanced the user experience by customizing display cards.

To summarize:

Next, you will learn how to build forms.

It is best practice to separate data authoring forms from browsing forms.

When browsing data, some obvious information such as labels can be hidden, and other information that can be highlighted using a different typography or color. You may also use computed fields in data browsing forms.

In this section, you will create an employee browsing form. You will use SemQL to format relevant employee attributes and display meaningful data to business users.

For example, instead of displaying the hire date as it is, you can define a Hired expression with the following format: Since 28-Feb-2018.

As you will learn later, you can also use SemQL expressions and conditions to format your results. For example, you might want to hide a field depending on the value of another field, or change the color of a field value depending on a complex condition.

Learning outcomes

Create a form and its structure

You will start this series of steps by creating a new form and its structure (tabs and containers).

  1. In the Application Builder, under the Employee entity, right-click the Forms node and click Add Form.

  1. Set the Name to EmployeeBrowsingForm, and click Finish.

  1. In the EmployeeBrowsingForm editor, select the FormTab: General element in the tree view and enter the following values in the Property Inspector:

  1. Click the Select Image button next to the Icon property.

  1. Search for account-circle.svg and select the image returned.

  1. Set the Display As property to Icon and Label.
  2. Add a second tab by dragging and dropping the Add Form Tab button under the General tab and rename it to Contact.
  3. In the Properties view, in the General section, click the Select Image button next to the Icon property.

  1. Search for cellphone-link.svg and select the image returned.

  1. Set the Display As property to Icon and Label.
  2. Add two nested containers in the General tab by dragging and dropping the Add Form Container button, as shown below.

  1. Select the second container and enter the following values in the Properties view:

  1. Add a second nested container into the parent container by dragging and dropping the Add Form Container button as shown below.

  1. Select the second nested container that you just added. In the Properties view, set the Layout Direction to Vertical.
  2. Save your work.

Configure the form fields

Add the Picture field

  1. Under the Entities > Employee > Forms node, open the EmployeeBrowsingForm form.

  1. Drag the Picture attribute and drop it into the first vertical container, as shown below.

  1. In the Properties view, in the General section, set the Component Type property to Image.

  1. In the Properties view, in the Component section, enter the following values:

  1. In the Label section, deselect Visible.

  1. Save your work.

Add the Name field

  1. Drag the Add Form Field button and drop it in the second vertical container, as shown below.

  1. Rename it to Name.

  1. Select the Value cell and click the Edit Expression button.
  2. Enter the following expression in the SemQL editor and click OK.
SEM_CONCAT(' ', '1', Salutation, FirstName, LastName)
  1. In the General section of the Properties view, enter the following values:


  1. In the Component section, set the Typography to Title.
  2. In the Label section, deselect Visible.
  3. Save your work.

Add the Title field

  1. Drag the Title attribute and drop it after the Name field, as shown below.

  1. In the General section of the Properties view, enter the following values:
  1. In the Component section, set the Typography to subhead.
  2. In the Label tab, deselect Visible.

  1. Save your work.

Add the Subsidiary field

  1. Drag and drop the Subsidiary attribute after the Title field.
  2. In the General section of the Properties view, enter the following values:
  1. In the Component section, set the Typography to subhead.
  2. In the Label section, deselect Visible.

  1. Save your work.

Add the Department field

  1. Drag and drop the FDN_Department attribute after the Subsidiary field.
  2. In the General section of the Properties view, enter the following values:
  1. In the Component section, enter the following values:

  1. In the Label section, deselect the Visible option.
  2. Save your work.

Add the IsContractor field

  1. Drag and drop the Add Form Field button after the Department field.
  2. Rename it to Contractor.
  3. Select the Value cell and click the Edit Expression button.

  1. Enter the following expression in the SemQL editor and click OK.
case when IsContractor = '1' then 'Contractor' else 'Employee' end
  1. In the General section of the Properties view, enter the following values:
  1. In the Component section, next to the Text Color property, select SemQL in the value type drop-down, and click the Edit button to open the SemQL editor.
  2. Enter the following expression in the SemQL editor and click OK.
case
        when IsContractor = '1' then 'md:orange'
        else 'md:green'
end
  1. In the Label section, deselect Visible.
  2. Save your work.

Add the Hired field

  1. Drag the Add Form Field button and drop it after the Contractor field.
  2. Rename it to Hired.
  3. Select the Value cell and click the Edit Expression button.

  1. Enter the following expression in the SemQL editor and click OK.
SEM_CONCAT(' ', '1', 'Since', to_char(HireDate , 'DD-Mon-YYYY'))
  1. In the General section, enter the following values:
  1. In the Label section, deselect the Visible option.
  2. Save your work.

Add the Ended field

  1. Drag and drop the Add Form Field button after the Hired field.
  2. Rename it to Ended.
  3. Select the Value cell and click the Edit Expression button.

  1. Enter the following expression in the SemQL editor and click OK.
SEM_CONCAT(' ', '1', 'Ended', to_char(EndDate , 'DD-Mon-YYYY'))
  1. In the General section of the Properties view, enter the following values:
  1. Next to the Visible property, select SemQL in the value type drop-down menu, and click the Edit button to open the SemQL editor.
  1. Enter the following expression in the SemQL editor and click OK.
EndDate is not null
  1. In the Component section, set the Text Color to md:red.
  2. In the Label section, deselect Visible.
  3. Save your work.

Add the Employee ID field

  1. Drag and drop the Add Form Field button into the second vertical container.
  2. Rename it to ID.
  3. Select the Value cell and click the Edit Expression button.

  1. Enter the following expression in the SemQL editor and click OK.
LPAD(SEM_TO_CHAR(ID), 6 , '0')
  1. In the General section, enter the following values:
  1. In the Component section, enter the following values:
  1. In the Label section, deselect Visible.
  2. Save your work.

Add the Phone field

  1. Drag the Phone attribute and drop it into the Contact form tab.
  2. In the Label section of the Properties view, set the Icon property to images://mdi/cellphone.svg.

Add the Phone Status field

  1. Drag the Add Form Field button and drop it into the Contact form tab, after the Phone field.
  2. Rename it to PhoneStatus.
  3. Select the Value cell and click Edit Expression.

  1. Enter the following expression in the SemQL editor and click OK.
case
  when Phone is null then 'No phone.'
  when Phone is not null
    and EnrichedPhone.IsPossible is null then 'Phone not verified yet.'
  else
    SEM_CONCAT(' • ', '1', EnrichedPhone.EnrichedPhone, EnrichedPhone.Country, EnrichedPhone.LineType, EnrichedPhone.Location)
end
  1. In the General section of the Properties view, enter the following values:
  1. In the Component section, next to the Text Color property, select SemQL in the value type drop-down menu, and click the Edit button to open the SemQL editor.
  2. Enter the following expression and click OK.
case
        when EnrichedPhone.IsPossible = '1' then 'md:grey'
        when EnrichedPhone.IsPossible is null then 'md:orange'
        else 'md:red'
end
  1. Set the Typography property to caption.
  2. In the Label section, deselect Visible.
  3. Save your work.

Add the Email field

  1. Drag and drop the Email attribute into the Contact form tab, after the Phone Status field.
  2. Select the Value cell in the tree view, and click the Edit Expression button.
  3. Enter the following expression in the SemQL editor, and then click OK.
SEM_CONCAT('', '1', 'mailto:', Email)
  1. In the General section of the Properties view, enter the following values:
  1. In the Component section, next to the Display Text property, select SemQL in the value type drop-down menu, and click the Edit button to open the SemQL editor.

  1. Enter the following value in the SemQL editor and then click OK.
Email
  1. In the Label section, set the Icon to images://mdi/email.svg.
  2. Save your work.

Activate the browsing form

  1. In the Application Builder, navigate to Entities > Employee > Business Views, and double-click the Employee business view.

  1. In the Transitions section, select EmployeeEO.

  1. In the Display Properties, click the Select a value button next to the Browsing Form property.

  1. Select EmployeeBrowsingForm and then click OK.

  1. Save your work.
  2. Validate your model. To do so, right-click the root node in the Model Design view element HRTutorial [0.0] and click Validate. No error should be returned.

See the browsing form in action

  1. Go back to the Welcome page and open the Employee Tutorial application.
  2. Open the user menu and select Refresh application.

  1. Select Employees in the navigation drawer.
  2. Click Alexis Bull's record to view the new browsing form.

  1. Browse the employee records of Jack Livingston and Julie Nayer to see how the user interface adapts.

Congratulations!

You have successfully created a browsing form for your Employee entity.

To summarize:

The next section will focus on creating an authoring form that will differ from the browsing form.

Data authoring forms should be optimized to provide the best user experience when entering data in steppers. The layout, field positions, and formatting may differ from the browsing experience.

In this section, you will enhance the authoring form for employee records.

Learning outcomes

Modify the existing form

Now that you know how to build a form, you will edit the EmployeeForm that you generated with the Generate Application Components wizard and enhance it.

Create the structure

You will now add containers to the default form.

  1. In the Application Builder, go to Entities > Employee > Forms, and double-click EmployeeForm.

  1. Select all the attributes (press and hold Shift, and select the first and last attribute in the tree view) and click the Delete Selection button.

  1. Click OK in the confirmation dialog.
  2. Select the EmployeeTab and set the following values in the Properties view (you can also double-click the Name and Label cells within the tree view to edit them):

  1. Drag the Add Form Tab button and drop it after the ContactInfo Form Tab.
  2. Rename it to HR.

  1. Drag and drop the Form container button into the ContactInfo tab, and repeat this operation twice to create three nested Form Containers within the first one.

  1. Select the three nested containers: select the first container, press and hold the Shift key, and select the third container.
  2. In the General section of the Properties view, set the Layout Direction to Vertical.

  1. Drag and drop one Form Container into the HR tab and create two nested Form Containers.

  1. Select the two containers and in the General section of the Properties view, set the Layout Direction to Vertical.

Contact Info (first column)

  1. Drag the FirstName attribute from the Attributes list and drop it in the first nested container of the ContactInfo tab.

  1. Select the FirstName form field.
  2. In the Properties view, in the Helper Text field, type As it appears on the photo ID provided by the employee.
  3. In the Label section, select Floating Label.
  4. Drag the LastName attribute and drop it into the same container, after the FirstName form field.
  5. Select the field.
  6. In the Label section of the Properties view, select Floating Label.
  7. Drag the Salutation and Subsidiary attributes and drop then after LastName.

9. Save your work.

Contact Info (second column)

  1. In the ContactInfo tab, in the second nested form container, drag and drop the IsContractor attribute.

  1. Drag a form container and drop it just after the field IsContractor.
  2. Drag the Phone attribute and drop it into this container.

  1. Select the Phone field.
  2. In the General section of the Properties view, enter the following values:
  1. Set the Relative Width to 70.
  2. In the Label section, select Floating Label.
  3. Drag the EnrichedPhone.Country attribute (from the complex attribute EnrichedPhone) and drop it after the Phone field.

  1. Select the EnrichedPhone_Country field.
  2. In the General section of the Properties view, enter the following values:
  1. In the Label section, select the Floating Label option.
  2. Drag a form field and drop it into the second vertical form container. It is automatically inserted after the container that holds the Phone and EnrichedPhone_Country fields.
  3. Rename it to PhoneStatus.

  1. Select the Value cell and click Edit Expression.

  1. Enter the following expression in the SemQL editor and click OK.
case
  when Phone is null then 'No phone.'
  when Phone is not null
    and EnrichedPhone.IsPossible is null then 'Phone not verified yet.'
  else
    SEM_CONCAT(' • ', '1', EnrichedPhone.EnrichedPhone, EnrichedPhone.Country, EnrichedPhone.LineType, EnrichedPhone.Location)
end
  1. In the Component section, enter the following values:
  1. In the Label section of the Properties view, deselect Visible.
  2. Drag the Email attribute and drop it below the PhoneStatus field.
  3. Select the Email field.
  4. In the General section of the Properties view, type Note: email is mandatory for contractors in the Helper Text field.
  5. In the Label section, select Floating Label.
  6. Save your work.

Contact Info (third column)

  1. Drag the ID attribute and drop it into the third nested container.

  1. Select the Value cell and click Edit Expression.

  1. Enter the following expression in the SemQL editor, and click OK.
LPAD(SEM_TO_CHAR(ID), 6 , '0')
  1. In the General section of the Properties view, enter the following values:
  1. Drag and drop the Picture attribute after the ID field.
  2. Select the Picture form field and in the General section of the Properties view, set Component Type to Image.

  1. In the Component section, set the following properties:
  1. Review your Contact Info tab. It should look as shown below:

HR (first column)

  1. In the first container of the HR form tab, drag and drop the FDN_Department attribute.

  1. Select this form field.
  2. In the Component section of the Properties view, enter the following values:

  1. Drag the Title attribute and drop it after the Department field.

  1. Select the Title form field.
  2. In the Label section of the Properties view, deselect Floating Label.

HR (second column)

  1. In the second container of the HR form tab, drag and drop the HireDate attribute.

  1. Drag and drop the EndDate attribute after the HireDate field.

  1. Save your work.

Plug your form

Because you modified the default authoring form that was previously used by the AuthorEmployees stepper, you need to adapt this stepper to the new tab structure and make it a two-step stepper.

  1. In the Application Builder, expand the Steppers node under the Employee entity, and double-click AuthorEmployees.
  2. In the Steps tree table, select the second line.
  3. In the Name and Definition finger tab of the Properties view, enter the following values:

  1. In the Form Enrichers finger tab, for the DefaultHireDate enricher, deselect the On Form Open checkbox.
    This enricher will be triggered on the second step (i.e., the HR tab).


  1. Select the first line of the table in the Steps section and click the Add Form Step button.

  1. In the dialog, select the EmployeeForm > HR form tab, and then click Finish.
  2. In the Steps tree table, select the step ContactInfo once again, and select the Enabled On Parent Create checkbox.
  3. In the Step Transition Validations finger tab in the Properties view, select the following lines (press and hold Control—or Command on macOS—and then select items one by one):
  1. Right-click the selection, and then select Skip.

  1. In the Form Validations finger tab, deselect the On Data Change checkbox for the following validation rules:

  1. Still in the Form Validations tab, deselect the On Form Open checkbox for the following validation rules:

  1. In the Steps tree table, select the HR step.
  2. In the Form Enrichers finger tab, for the DefaultHireDate enricher, select the On Form Open checkbox.


  1. In the Step Transition Validations finger tab, select the following lines, right-click the selection, and then select Block:

  1. In the Form Validations finger tab, select the On Data Change checkbox for the following validation rules:

  1. Still in the Form Validations finger tab, select the On Form Open checkbox for the following validation rules:

  1. Save your work.

Deploy your changes

  1. In the Model Design view of the Application Builder, right-click the root node corresponding to the HRTutorial [0.0] model, and click Validate.
    There should be no errors.

  1. Go to the Management perspective of the Application Builder.
  2. Right-click EmployeeTutorial and select Deploy Model Edition.

  1. In the dialog, click Finish to deploy your updated model.

View the authoring form in action

The application is deployed and ready to use. You will now create an employee to view your new authoring form in action.

  1. Log in to the Employee Tutorial application.
  2. In the navigation drawer, select the Employees business view.

  1. Open the Options menu and click Create.

  1. Notice the following:


  1. Enter the following values in the Contact tab and click Next:

  1. Enter the following values in the HR tab then click Finish:

  1. Search for the record you just created: click the Filter button above the Employees collection and enter pavlov in the Search Text field.

  1. Click the record to open it.

  1. Open the Options menu on the top right corner of the browsing form and click Edit.

  1. Enter the following values in the Contact tab, and then click Next:
  1. Leave the HR tab as it is and click Finish.
  2. Wait until the toaster at the bottom left corner of the screen indicates "Changes successfully applied", and then click Click to refresh.

  1. Observe the changes on both tabs of the browsing form.

Congratulations!

You have successfully customized the authoring form for the Employee entity.

To summarize:

The next section will focus on customizing a collection view.

Collections present records in table, list, or grid format. You can determine which view types are accessible to business users.

Collections consist of table columns that are similar to form fields. You can specify which columns are visible or hidden by default.

Next, you will learn how to customize the Employee collection view, as shown in the image below.

Learning outcomes

Modify the Employee collection

Collection columns share almost identical properties with form attributes, but collections have a simpler layout.

  1. In the Design perspective of Application Builder, go to Entities > Employee > Collections and then double-click EmployeeCollection.
  2. Select the ID column and then set the following properties in the Column section of the Properties view:

  1. Drag and drop the Add Table Column button between the ID and FirstName fields.
  2. Enter the following values:

  1. Click the Edit Expression button in the Value cell.

  1. Replace the existing value with the following expression in the SemQL editor and click OK.
case 
        when IsContractor = '1' then 'Contractor' 
        else 'Employee' 
end ||
case
        when EndDate is not null then ' (inactive)'
        else ''
end
  1. In the Column section of the Properties view, next to the Text Color property, select SemQL in the drop-down menu, and click the Edit button to open the SemQL editor.

  1. Enter the following expression in the SemQL editor and then click OK.
case 
        when EndDate is not null then 'md:grey' 
        when IsContractor = '1' then 'md:orange' 
        else 'md:green' 
end
  1. Select the FirstName column in the collection editor.
  2. In the General section of the Properties view, deselect Visible By Default.

  1. Repeat the same operation for the following fields:
  1. Drag the existing FDN_Department column and drop it between Title and HireDate.

  1. Enter the following values in the Column section of the Properties view:
  1. Drag Add Table Column and drop it between the FDN_Department and HireDate fields.
  2. Enter the following values:

  1. Click the Edit Expression button to open the SemQL editor.

  1. Replace the existing value with the following expression in the SemQL editor and click OK.
case 
  when Phone is not null then
        case 
                when EnrichedPhone.EnrichedPhone is null then SEM_CONCAT('', '1', Phone, ' (?)')
                when EnrichedPhone.IsValid = '1' then
                        SEM_CONCAT('', '1', EnrichedPhone.EnrichedPhone, ' (✓)')
                when EnrichedPhone.IsValid = '0' then
                        SEM_CONCAT('', '1', EnrichedPhone.EnrichedPhone, ' (!)')
                else ''
        end
  else ''
end
  1. Drag the existing Email column and drop it between VerifiedPhone and HireDate and set the Label to Email.

  1. Click the Edit Expression button in the Value cell to open the SemQL editor.

  1. Replace the existing value with the following expression in the SemQL editor and click OK.
SEM_CONCAT('', '1', 'mailto:', Email)
  1. In the General section of the Properties view, set the Component Type to Hyperlink.
  2. In the Column section, next to the Display Text property, select SemQL in the drop-down menu, and set the Display Text to Email.

  1. Drag the Picture column and drop it between EndDate and IsContractor.

  1. Enter the following values in the Column section of the Properties view:
  1. Select the IsContractor column in the tree view, press and hold the Shift key, and select the Phone column.
  2. In the Properties view, deselect Visible By Default.

  1. Save your work.

See the collection view in action

Since you did not change any rules besides the collection layout, you do not need to re-deploy the model. Simply refresh your application.

  1. On the Welcome page, open the Employee Tutorial application, and click Refresh application from the user menu.

  1. In the navigation drawer, select Employees.

  1. Observe the following enhancements to the new collection view:

  1. Open the Options menu and click Select columns.

  1. Drag the Title column and drop it between Salutation and Department.
  2. Select the checkbox next to Title to make it visible and click Apply.

  1. The collection now shows the column that you have just added.

Congratulations!

You have successfully customized the collection view for your Employee entity.

To summarize:

In this tutorial unit, you have learned how to customize the user interface with display cards, forms, and collections within your first data authoring application.

Learning recap

Next steps

In the next unit, Business views and hierarchies, you will learn how to customize your business views and hierarchies to offer a better navigation experience to your business users.

GO TO TUTORIALS

Thank you for completing this tutorial.