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.

What you'll learn

Before you start

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 already done so, you can download resources such as images used in this tutorial by clicking on the button below.

DOWNLOAD TUTORIAL RESOURCES

The estimated duration of this unit is about 2 hours.

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 first step, you will be guided to customize two different display cards.

What you'll learn

Customize the Employee card

Let's now customize the Display Card of the Employee entity by adding a primary and a fallback image.

  1. Open the HRTutorial model in the Application Builder.
  2. Navigate to Entities>Employee > Display Cards in the Model Design View and open the EmployeeDisplayCard.

  1. In the Image section of the editor, select SemQL in the value type drop down of the Primary Image property.

  1. Enter the following values:

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

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

  1. Go to the Avatar section, select SemQL in the value type drop down of the Avatar property.

  1. Enter the following values:

  1. Save your work.

Add more cosmetic elements

Let's adapt the EmployeeCollection and then 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, click the Select Image button next to the Avatar property.

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

  1. Save your work.

Refresh and see the results

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

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

  1. Go to the Department business view and notice that departments now have an avatar icon.

  1. Select the Employee business view and sort records by First Name.

  1. Select the following employees by clicking on their avatar and then select Edit in the Action menu:

  1. Scroll down until the end of the form and click the BROWSE button.

  1. Select the picture data-authoring\employees\alyssa.png from the tutorial resources and then click EDIT NEXT.
  2. Repeat the same process for the other two employees, and then click GO TO LIST:
  1. Click FINISH.

  1. When the toaster indicates "Changes successfully applied", select CLICK TO REFRESH.

  1. See how the pictures that you have uploaded are now displayed as avatars.

  1. Select List view from the actions menu to switch the type of view of the Employees collection.


  1. Switch view again by selecting Grid view from the actions menu.

  1. Select Table view from the actions menu to switch back to the default view.

Congratulations

You have enhanced the user experience by customizing Display Cards.

What we've covered

Now is the time to get to more advanced features: let's build beautiful forms!

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

When browsing data, there is a lot of obvious information (such as labels) that can be hidden, and other information that should be highlighted using a different typography or color. You may also use computed fields in data browsing forms.

In this step, you will create a nice looking employee browsing form. You will be using SemQL to format relevant employee attributes and display meaningful data to the business users.

For example, instead of displaying the HireDate as-is, you will rather 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.

What you'll learn

Create the form and the structure

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

  1. In the Application Builder, right-click the Forms node under the Employee entity, and select 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 then 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 then rename it to Contact.

  1. Click the Select Image button next to the Icon property in the General section of the Properties view.

  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 then 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 and drop the Picture attribute into the first vertical container as shown below:

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

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


  1. In the Label section, unselect Visible.

  1. Save your work.

Add the Name field

  1. Drag and drop the Add Form Field button into the second vertical container as shown below:

  1. Double-click the Name column in the tree view for this new FormField, and then rename it to Name.

  1. Select the Value cell and then click the Edit Expression button.

  1. Enter the following expression in the SemQL Editor and then 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, unselect Visible.
  3. Save your work.

Add the Title field

  1. Drag and drop the Title attribute after the Name field as shown below:
  2. Enter the following values in the General section of the Properties view:
  1. In the Component section, set the Typography to subhead.
  2. In the Label tab, unselect Visible.

  1. Save your work.

Add the Subsidiary field

  1. Drag and drop the Subsidiary attribute after the Title field.
  2. Enter the following values in the General section of the Properties view:
  1. In the Component section, set the Typography to subhead.
  2. In the Label section, unselect 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, enter the following values:
  1. In the Component section, enter the following values:

  1. In the Label section, unselect 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. Double-click the Name column in the tree view for the new FormField and rename it to Contractor.
  3. Select the Value cell and then click the Edit Expression button.

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

Add the Hired field

  1. Drag and drop the Add Form Field button after the Contractor field.
  2. Set the Name to Hired, select the Value cell, and then click the Edit Expression button.

  1. Enter the following expression in the SemQL Editor and select 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, unselect 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. Set the Name to Ended, select the Value cell, and then click the Edit Expression button.

  1. Enter the following expression in the SemQL Editor and then click OK:
SEM_CONCAT(' ', '1', 'Ended', to_char(EndDate , 'DD-Mon-YYYY'))
  1. In the General section, enter the following values:
  1. Select SemQL in the value type drop down of the Visible property, and then click the Edit button to open the SemQL Editor.

  1. Enter the following expression in the SemQL Editor and then click OK:
EndDate is not null
  1. In the Component section, set the Text Color to md:red.
  2. In the Label section, unselect 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. Set the Name to ID, select the Value cell, and then click the Edit Expression button.

  1. Enter the following expression in the SemQL Editor and select 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, unselect Visible.
  2. Save your work.

Add the Phone field

  1. Drag and drop the Phone attribute 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 and drop the Add Form Field button into the Contact form tab, after the Phone field.
  2. Set the Name to PhoneStatus. Select the Value cell, and then click Edit Expression.

  1. Enter the following expression in the SemQL Editor and then 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, enter the following values:
  1. In the Component section, select SemQL in the value type drop down of the Text Color property, and then click the Edit button to open the SemQL Editor. Enter the following expression and then 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, unselect Visible.

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 then click the Edit Expression button. Enter the following expression in the SemQL Editor and then click OK:
SEM_CONCAT('', '1', 'mailto:', Email)
  1. In the General section, enter the following values:
  1. In the Component section, select SemQL in the value type drop down of the Display Text property, and then 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 the EmployeeBrowsingForm and then click OK.

  1. Save your work.
  2. Validate your model: right-click the root node in the Model Design View - element HRTutorial [0.0] and select 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, click the Alexis Bull record to see the new browsing form.

  1. Browse the employees Jack Livingston and Julie Nayer to see how the user interface adapts.

Congratulations

You have successfully completed the second step of this tutorial by creating a browsing form for your Employee entity.

What we've covered

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

Data authoring forms should be optimized for the best user experience when entering data in steppers. Layout, field positions and formatting can differ from the browsing experience.

In this step, you will enhance the Employee authoring form.

What you'll learn

Modify the existing form

Now that you know how to build a form, let's 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 entity, and double-click EmployeeForm.

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

  1. Click OK on the confirmation popup.
  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 and drop the Add Form Tab button after the ContactInfo Form Tab and set the Name 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 then 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. Set the Layout Direction to Vertical in the General section of the Properties view for these 2 nested containers.

Contact Info - First column

  1. Drag and drop the FirstName attribute from the Attributes list into the first nested Container of the ContactInfo tab.

  1. Select the FirstName form field and then enter the following values in the Properties view:
  1. Drag and drop the LastName attribute into the same container, after the FirstName form field.
  2. Select this field and then select Use Floating Label in the Label section of the Properties view.
  3. Drag and drop the Salutation and Subsidiary attributes after LastName.

Contact Info - Second column

  1. Drag and drop the IsContractor attribute into the second nested Form Container of the ContactInfo tab.

  1. Drag and drop a Form Container just after the field IsContractor, and drag and drop the Phone attribute into this container.

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

  1. Select the EnrichedPhone_Country field and then enter the following values in the General section of the Properties view:
  1. In the Label section, select the Use Floating Label option.
  2. Drag and drop a Form Field into the second vertical form container. It is automatically inserted after the container that holds the Phone and EnrichedPhone_Country fields. Set the Name of this Form Field to PhoneStatus.

  1. Click the Edit Expression button in the Value cell of the PhoneStatus field.

  1. Enter the following expression in the SemQL Editor and then select 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. Unselect Visible in the Label section of the Properties view.
  2. Drag and drop the Email attribute below the PhoneStatus field.
  3. Select the Email field. In the General section of the Properties view, set the Helper Text to Note: email is mandatory for contractors.
  4. In the Label section, select Use Floating Label.

Contact Info - Third column

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

  1. Click the Edit Expression button in the Value cell of the ID field.

  1. Enter the following expression in the SemQL Editor and then select OK:
LPAD(SEM_TO_CHAR(ID), 6 , '0')
  1. Enter the following values in the General section of the Properties view:
  1. Drag and drop the Picture attribute after the ID field.
  2. Select the Picture Form Field and then set Component Type to Image in the Properties view.

  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. Drag and drop the FDN_Department attribute into the first container of the HR form tab.

  1. Select this Form Field and then enter the following values in the Component section of the Properties view:

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

  1. Select the Title form Field. In the Label section of the Properties view, unselect Use Floating Label.

HR - Second column

  1. Drag and drop the HireDate attribute into the second container of the HR form tab.

  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 2-step stepper.

  1. In the Application Builder, expand the Steppers node under the Employee entity, and then double-click AuthorEmployees.
  2. In the Steps tree table, select the second line. Enter the following values in the General section of the Properties view:

  1. In the Form Enrichers tab, unselect On Form Open for the DefaultHireDate enricher. This enricher will be triggered on the second step (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.

  1. Select again the step ContactInfo in the Steps table and then select the Step Transition Validations tab of the Property Editor. Select the following lines (hold Ctrl and then select items one by one), right-click the selection, and then select Skip:

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

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

  1. Select the HR step and, in the Form Enrichers tab, select On Form Open for the DefaultHireDate enricher.


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

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

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

  1. Save your work.

Deploy your changes

  1. In the Application Builder, right-click the root node in the Model Design View, corresponding to the HRTutorial [0.0] model, and then select Validate. No errors should be displayed.

  1. Go to the Management perspective of the Application Builder, right-click the EmployeeTutorial, and then select Deploy Model Edition.

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

See the authoring form in action

Good job! The application is deployed and ready to use. Let's create an employee to see the new authoring form.

  1. Connect to the Employee Tutorial application, select the Employees business view in the Navigation Drawer.

  1. Open the actions menu and select Create.

  1. Notice the following:
  1. Enter the following values in the Contact tab then select NEXT:

  1. Enter the following values in the HR tab then select 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 actions menu on the top right corner of the browsing form and select Edit.

  1. Enter the following values in the Contact tab then select NEXT:
  1. Leave the HR tab as it is and select FINISH.
  2. Wait until the toaster at the bottom-left corner of the screen indicates "Changes successfully applied", and then select CLICK TO REFRESH:

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

Congratulations

You have successfully completed the third step of this tutorial by customizing the authoring form for your Employee entity.

What we've covered

The next step will focus on customizing a collection view.

Collections display a set of records in a table, a list, or a grid. You control which of these view types are available for business users.

Collections are composed of table columns, similar to form fields. You can customize which columns will be available to users, visible or hidden by default.

The next steps will guide you to customize the employee collection view as depicted here.

What you'll learn

Modify the Employee collection

Building a collection is simpler than a form: collection columns have nearly the same set of properties as the form attributes, but collections have a much simpler layout.

  1. In the Design perspective of the Application Builder, go to Entities > Employee > Collections and then double-click EmployeeCollection.
    the
  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. 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 then 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, select SemQL in the value type drop down of the Color property, and then 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 and then unselect Visible By Default in the General section of the Properties view.

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

  1. Enter the following values in the Component section of the Properties view:
  1. Drag and drop the Add Table Column button between the FDN_Department and HireDate fields. 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 then 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 and drop the existing Email column between VerifiedPhone and HireDate and then 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 then 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 Component section, select SemQL in the value type drop down of the Display Text property, and then set the Display Text to Email.

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

  1. Enter the following values in the Component section of the Properties view:
  1. In the Format tab, set the Link Target to popup-image.
  2. Select the IsContractor column in the tree view, press and hold the Shift key, and then select the Phone column. In the Properties view, unselect Visible By Default.

  1. Save your work.

See the collection view in action

As you didn't change any rules besides the collection layout, you do not need to re-deploy the model but only need to refresh your application.

  1. On the Welcome Page, open your Employee Tutorial application and select Refresh application from the user menu.
  2. Select Employees in the Navigation Drawer.
  3. Notice the following enhancements of the new collection view:

  1. Open the actions menu and select Select columns.

  1. Drag and drop the Title column between Title and Department, select the checkbox next to it to make it visible, and then click APPLY.

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

Congratulations

You have successfully completed the fourth and last step of this tutorial by customizing the collection view for your Employee entity.

What we've covered

Excellent job following this tutorial! With this unit, you learned how to customize the user interface with display cards, forms, and collections within your first data authoring application.

What we've covered

What's next?

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