Skip to content

List

The list element works differently depending on what else has been added to the screen:

  • If there are only selector, singleton and markdown elements and a single list element on the page, the list element will be shown as a full list in the lower part of the screen, underneath the other elements
  • If there are other types of element or more than one list element on the page, each list element will be displayed as a button which can be used to navigate to a page just showing the full list

On mobile devices, it is quite often the case that the device does not have good enough performance to show all items in a list at once. To improve this situation the platforms came up with a concept called virtualization. When you scroll down items are added to the bottom of the screen and existing item no longer on the screen are removed from the top.

Marble

list CcCaseContactList for CcCaseContact {  
   label = "Case Contacts";  
   card CcCaseContactCard;  
}  

Custom create command

When a details page is provided for a list the user is presented with a create button. This button allows them to go to the details page with a new record prepared. Sometimes it is instead desirable to send the user to an assistant. This can be done using a custom create command:

  • Create a new command named [ListName]_Create containing the command to run when the create button is clicked. For example: CcCaseContactList_Create. The _Create postfix is mandatory to replace the built in create functionality.
  • Mark the command's mode as Global
  • Add this command to the list definition (not the card).
list WorkOrderList for WorkOrders {  
   card WorkOrderCard;  
   command WorkOrderList_Create;  
}  

command WorkOrderList_Create {  
   mode = Global;  
   execute {  
      // Executions  
   }  
}  

Custom details command

When using the list on a page, a details property is used to define the page that the app should navigate to when a list item is clicked - this can be seen in the Details Page example metadata earlier. More advanced click actions, for example opening a dialog or navigating to one of several pages depending on a condition, can be be defined instead as follows:

  • Do not define a details property when adding the list to the page
  • Create a new command named [CardName]_Details containing the action to be run for each item click. For example, for the metadata example, the command would be called CcCaseContactCard_Details. The _Details postfix is mandatory to mark this command as the new click action.
  • Add this command to the card definition.

Item count display for collapsed lists

By default, if a list is derived from an entity set, it will display the count of items when in the collapsed state. However, in the case of a list that is derived from a function, this is not done automatically for performance reasons. In such case, you may use the count keyword to indicate a function that will return the numeric count to be displayed. This can be set when defining the list at the root-level and within a page. The function that is defined in page-level will take precedence over the root-level function. It is possible to pass in attribute names as parameters to this function for which the values will be fetched from the current record.

// root-level definition  
list CustomersListFunction for Customers {  
   card CustomerCard;  
   count = FnGetCustomersCount;  
}  

// page-level definition  
page CustomersPage using Customers {  
   list CustomerList {  
      details = CustomerDetail(CustomerNo);  
      count = FnGetCustomersCount2(CompanyId);  
   }  
}  

Attachments

An attachments button can be added to list items. This will show a paperclip button under the list item allowing the user to go directly to the attachments screen. For performance reasons the button does not show a count for the number of currently attached files.

list CustomersList for Customers {  
   card CustomerCard;  
   attachments {  
      enabled = [true];  
   }  
}  

Limitations

  • The web client allows list items to be edited in line. This is not possible in the native client since it leads to a bad user experience on small screen sizes. Instead the UI should be designed so the user would click an item in the list to go to a detail screen where they can edit.
  • Column / grid layout is not supported. The fields are always displayed as a card. If no card is defined on the list the highest-ranking fields will be displayed as a card. (1 image, 4 texts and 2 other)

Supported elements & properties

  • card
  • details
  • badge
  • field
  • static
  • label
  • visible
  • count
  • attachments