FormItem

form-item

The FormItem component is used to display a single row of a Priority form. It is used by the FormList to display the items in the list.

Jump to the FormItem API…

• Contents
• Basic Item
• Card Item
• Display Columns
• Columns Options
• Item Options
• Styling
• FormItem API

Basic Item

The FormItem component should be used with a Form object returned from the ‘startForm’ method of the formService.

The Item represents a single row of a form’s rows retrieved by the getRows method of the formService.

Use the form-item in any custom list that is different from Priority Ionic’s FormList.

<ion-list>
    <form-item
         *ngFor="let item of form.rows | objToIterable"
         [Form]="form"
         [Item]="item">
    </form-item>
</ion-list>

Card Item

By default, an item is displayed as a regular Ionic item. To display it as a card item, add the card attribute to the form-item component.

<form-item
   card
   [Form]="form"
   [Item]="item">
</form-item>

Display Columns

By default, the form-item displays no data. To display the row’s data, configure the form columns that should be displayed with the ColumnsOptions input property.

For each column add an entry to the ColumnsOptions where the key is the column’s name and the value is the ColumnOptions object.

To display a column’s value, set isShow to true. To display the column’s title - set isShowTitle to true, or provide a different title with the title property. Set concat to another column’s name to concatenate that column’s value with the current column’s value (see example below). Set pos to a relative number to define the column’s position within the item.

let ordersColumnsOptions: ColumnsOptions = {
    // show the order number and title
    'ORDNAME': {
      isShow: true,
      isShowTitle: ture,
      pos: 1
    }
    // show the order status with an overridden title
    'ORDSTATUSDES': {
      isShow: true,
      pos: 2,
      title: 'Status'
    },
    // show the order price concatenated with the currency
    'DISPRICE': {
      isShow: true,
      pos: 3,
      concat: 'CURRENCY'
    }
  }

Then set the ColumnsOptions input property.

<form-item
   [Form]="form"
   [Item]="item"
   [ColumnsOptions]="ordersColumnsOptions">
</form-item>

Columns Options

There are a few more column options that can be set in the ColumnOptions to configure more advanced display of the item.

Avatar

Setting the avatar property as true for a specific column will display the column’s value as an avatar. This option is suitable for columns that contain an image url as their value. The avatar property can also be set with a string pointing to a default image url that will be displayed when the column’s value is empty. Only a single column in a form can be set with the avatar property. You can set a list as an avatar list or thumbnail list, but not both.

Thumbnail

Similar to avatar, setting the thumbnail property will display the column’s value as a thumbnail in the item. Only a single column in a form can be set with the thumbnail property. You can set a list as an avatar list or thumbnail list, but not both.

Icons

To display an icon for the column, set the icon property with an Ionic icon name.

Click

To add a click functionality to a specific column, set the click property with a handler function that receives the item and column as parameters.

let partsColumnsOptions: ColumnsOptions = {
    // display the part image as a thumbnail
    'EXTFILENAME': {
      thumbnail: true
    },
    // clicking on the part description will allow the user to edit it.
    'PARTDES': {
      isShow: true,
      pos: 1,
      click: (item,column) => {
        //functionality for editing the part description
      }
    },
    // show a pricetag icon next to the price
    'PRICE': {
      isShow: true,
      pos: 2,
      icon: 'pricetag'
    }
  }

Item Options

The ItemOptions input property is used for setting other advanced options to the item.

Click

To add a click functionality to the form-item, set the click property of the ItemOptions with a handler function. The click handler receives the clicked item object and the form object as parameters. “Tappable” styling is applied to an item that has the click property set.

CSS Class

Additional CSS classes for custom styles, can be added to the form-item. Set the cssClass property with a function that receives the item as a parameter and returns a CSS class to apply to it, using the ngClass format (object or string).

Title

A custom title can be given to the form-item with the title property of ItemOptions.

Sliding Buttons

Set the slidingButtons property to turn the form-item into a [sliding] (https://ionicframework.com/docs/components/#sliding-list) item that can be swiped to the left or right to reveal these buttons. slidingButtons is an array where each button is a ButtonOption object, which defines the icon, color, text, side and click handler for the button.

Subforms

A form-item can be expanded to display data from subforms of the item by setting the subforms property. Add an entry to subforms for each subform to be displayed, where the key is the subform’s name and the value is a FormOptions object. In the FormOptions, use the title property to override the subform’s Prioirty title. Set pos to a relative number to define the subform’s position in the item. To add functionality to the subform, set the click property with a click handler.

Expand/collapse functionality is automatically added to an item with the subforms property set. When the item’s expand button is clicked, the subform’s data for the item is fetched (by the FormService) and displayed.

The title is displayed for all subforms, but subform data is displayed differently for each subform type. A normal subform displays the number of rows it contains. A single row subform display its data, in accordance to the item row data configured in the ColumnsOptions defined in the FormOptions for that subform. A text-form subform displays the text it contains.

let itemOptions = {
  // clicking on the item will navigate to a single item page preview.
  click: (item,form) => {
    // add functionality to navigate to a single item page
  },
  // add a different CSS class to each item according to it's status.
  cssClass: (item) => {
    return item['STATUS'];
  },
  // the item will include 'edit' and 'delete' options as sliding buttons.
  slidingButtons: [
    {
      text: 'edit',
      icon: 'create',
      color: 'favorite',
      side: 'right',
      click: (item) => {
        // edit item
      }
    },
    {
      text: 'delete',
      icon: 'trash',
      side: 'right',
      color: 'danger',
      click: (item) => {
        // delete item
      }
    }
  ],
  // display the text and order-items subforms
  subforms:  {
    'ORDERSTEXT': {
      title: 'Remarks',
      pos: 2
    },
    'ORDERITEMS': {
      title: 'Items',
      pos: 1,
      click: (subform,item) => {
        // functionality for navigating to the order items page.
      }
    }
  }
}

Styling

Custom styling is possible for each column, column title, column value, and subform elements displayed in the item.

A CSS class with the same name as the column name is added to the container element of each column displayed. This class is added for both the column’s title element and value element with the addition of a ‘title’ and ‘value’ class, respectively. A subform name CSS class is added for subform elements as well.

Use these CSS Classes to apply different styling to each piece of data displayed in the item, such as left aligning the record’s date, or setting a bigger font size for the record’s name.

FormItem API

Attributes

Input Attributes

Input Properties