List (from data source)

Hooks

The List (from data source) component exposes hooks that you can use to modify the component data and behavior. Here are the hooks and their specific life cycle:

flListDataBeforeGetData

The hook is run before data is retrieved for rendering.

Fliplet.Hooks.on('flListDataBeforeGetData', fn);

Parameters

  • fn (Function(data) Callback function with an object parameter.
    • data (Object) A map of data containing the following.
      • config (Object) Configuration used to initialize the component.
      • id (Number) Component instance ID.
      • uuid (String) Component instance UUID.
      • container (jQuery object) jQuery object for the component container element.

Usage

Overwriting data to be rendered


Fliplet.Hooks.on('flListDataBeforeGetData', function (data) {
  data.config.getData = function() {
    return Promise.resolve([
      {
        id: 1,
        data: { name: 'Nick' }
      },
      {
        id: 2,
        data: { name: 'Tony' }
      }
    ]);
  };
});

Note: data.config.getData must return an array of objects. Each object must contain both id and data properties.

flListDataAfterGetData

The hook is run after data is retrieved for rendering.

Fliplet.Hooks.on('flListDataAfterGetData', fn);

Parameters

  • fn (Function(data) Callback function with an object parameter.
    • data (Object) A map of data containing the following.
      • config (Object) Configuration used to initialize the component.
      • id (Number) Component instance ID.
      • uuid (String) Component instance UUID.
      • container (jQuery object) jQuery object for the component container element.
      • records (Array) Collection of records to be used for the component.

flListDataBeforeDeleteConfirmation

The hook is run before delete confirmation pop up shows.

Fliplet.Hooks.on('flListDataBeforeDeleteConfirmation', fn);

Parameters

  • fn (Function(data) Callback function with an object parameter.
    • data (Object) A map of data containing the following.
      • config (Object) Configuration used to initialize the component.
      • id (Number) Component instance ID.
      • uuid (String) Component instance UUID.
      • container (jQuery object) jQuery object for the component container element.
      • entryId (Number) Data source entry ID of the record to be deleted.

flListDataBeforeDeleteEntry

The hook is run before deleting an entry.

Fliplet.Hooks.on('flListDataBeforeDeleteConfirmation', fn);

Parameters

  • fn (Function((data)) Callback function with an object parameter.
    • data (Object) A map of data containing the following.
      • config (Object) Configuration used to initialize the component.
      • id (Number) Component instance ID.
      • uuid (String) Component instance UUID.
      • container (jQuery object) jQuery object for the component container element.
      • entryId (Number) Data source entry ID of the record to be deleted.

Usage

Before deleting an entry

Fliplet.Hooks.on('flListDataBeforeDeleteEntry', function onBeforeDeleteEntry(data) {
  data.config.deleteData = function(id) {
    // Execute a custom third-party entry deletion operation
    return $.ajax({
      url: 'http://example.com/api/entry/' + id,
      method: 'DELETE'
    });
  };
});

Configuration

Using the available hooks, component instance configuration can be used to modify component data and behavior. The available configuration properties are listed below:

  • getData (Function(data)) Function used to retrieve data. Each entry must include the following properties, which the Fliplet.DataSources JS API follows. Note This function is best set using the flListDataBeforeGetData hook and must return a Promise.
    • id (Number) Entry ID
    • data (Object) Entry data
  • beforeOpen (Function(data)) Function executed before loading entry details. The data parameter contains the following properties. Return a rejected Promise if you need to stop the entry from opening.
    • config (Object) Configuration used to initialize the component
    • entry (Object) Entry being opened
    • entryId (Object) ID for entry being opened
    • entryTitle (Object) Title for entry being opened
  • beforeShowDetails (Function(data)) Function executed before showing the entry detail view, after the entry detail data is ready. The data parameter contains the following properties. Return a rejected Promise if you need to stop the entry from opening.
    • src (String) HTML source for the detail view template
    • data (Object) Data being used for rendering the detail view template
  • afterShowDetails (Function(data)) Function executed after the entry detail view is shown. The data parameter contains the following properties.
    • config (Object) Configuration used to initialize the component
    • src (String) HTML source for the detail view template
    • data (Object) Data being used for rendering the detail view template
  • deleteData (Function(data)) Function used to delete an entry. The data parameter contains the following properties.
    • entryId
    • config (Object) Configuration used to initialize the component
    • id (Number) Component instance ID
    • uuid (String) Component instance UUID
    • container (jQuery object) jQuery object for the component container element
  • searchData (Function(data)) Function used to execute a data search. The data parameter contains the following properties.
    • config (object) Configuration used to initialize the component
    • query (String) Query string entered by user

Query parameters

When navigating to a screen that contains a List (from data source) component, you can use queries to execut logic accordingly, e.g. load a specific list item, apply filters and/or search, or add a new pre-filter.

Use the following query parameters when linking to a screen with List (from data source) components.

  • dynamicListOpenId Entry ID to be opened after the list is rendered.
  • dynamicListSearchValue Search term to be applied after the list is rendered. Search will be executed according to the component configuration or custom configuration. If only one entry is found, the entry will be automatically opened.
  • dynamicListSearchColumn Column to execute a search against. If provided, the component configuration will be ignored. (Optional)
  • dynamicListFilterValue A comma-separated list of filter options to select.
  • dynamicListFilterHideControls (true|false) Hide the filter controls when filter values are applied from the query. (Default: false)
  • dynamicListPrefilterColumn Pre-filter list based on the provided list of comma-separated column names.
  • dynamicListPrefilterValue Pre-filter list based on the provided list of comma-separatedvalues for the column names.
  • dynamicListPrefilterLogic Pre-filter list based on the provided list of comma-separated logic operators to be applied on the columns and values. The valid operators are:
Operator URL encoded operator Description
== %3D%3D Equals
!= %21%3D Not equal
> %3E Greater than
>= %3E%3D Greater than or equal
< %3C Less than
<= %3C%3D Less than or equal
contains contains Contains
notcontain notcontain Not contain
regex regex RegExp

Examples

Open entry with ID 123

dynamicListOpenId=123

Execute a search with the search term “hello”

dynamicListSearchValue=hello

Render with a filter and hide the filter bar

dynamicListFilterValue=England,Monthly&dynamicListFilterHideControls=true

Load only data that match names containing John and age less than 29

dynamicListPrefilterColumn=Name,Age&dynamicListPrefilterValue=John,29&dynamicListPrefilterLogic=contains,%3C

Persistent Variable Queries (deprecated)

The Persistent Variable Queries method has been deprecated.

With the List (from data source) you can programatically load a specific list item, apply filters and/or search, and even add a new pre-filter. (pre-filter is a filter applied before the list is rendered - this won’t override the filters added in component settings)

This can be achieved by setting a persistant variable using the Fliplet.App.Storage. Read more here The persistant variable, by default, will be removed automatically after running.

Fliplet.App.Storage.set('flDynamicListQuery:simple-list', { ... });

The persistant variable is namespaced with flDynamicListQuery: plus the list layout name. Below are all the layout names you can use.

List layouts

The key of the persistant variable includes the layout name of the List (from data source). Here is a list of all the layouts available in the List (from data source) component:

  • small-card Small Expandable Cards
  • news-feed Cards with Description
  • agenda Agenda
  • small-h-card Small Horizontal Cards
  • simple-list Simple List

Let’s have a look at how to use the feature.

Fliplet.App.Storage.set('flDynamicListQuery:simple-list', options);
  • options (Object) A map of options to pass as the value of the persistant variable.
    • prefilter (Array) (Array of objects) Use this if you want to pre-filter your list.
      • column (String) [Required] The name of the column that you want to use to filter by.
      • logic (String) [Required] The logic operator for the filtering. See the possible logic operators below.
      • value (String) [Required] The value that will determine the filter.
    • open (Object) Use this if you want to open a specific list item.
      • id (String) The id of the list item that you want to open.
      • column (String) The column where the value will be queried for.
      • value (String) The value used to query the column.
    • search (Object) Use this if you want to load your list with a search applied. If only one list item is returned, it will automatically open it.
      • value (String) [Required] The search value.
      • column (String or Array) The column or columns where the value will be searched for. If the column is defined, it will override the component’s settings.
    • filter (Object) Use this if you want to load your list with one or multiple filters applied.
      • value (String or Array) [Required] A value or list of values containing the filters that you want activated on load.
      • hideControls (Boolean) Use this option to hide or show the filters buttons when the page loads (Default: true)
    • goBack (Object) Use this if you want to set a new back button or hijack the top bar’s back button
      • enableButton (Boolean) This will render a new button at the top of the component that will trigger a Fliplet.Navigate.back() (Default: false)
      • hijackBack (Boolean) This will hijack the action of the back button (arrow left) on the top bar menu (Default: false)
      • action (Function) The function will be executed before the user is returned to the previous screen. The function must be written as a String, because functions can’t be saved to Fliplet.Storage.
    • previousScreen (Boolean or Function) If you want to return to the previous screen when closing a list item, set to true or write a function. The function will be executed before the user is returned to the previous screen. We recommend only using this option when you know there will only be one entry as a result. (Default: false)
    • persist (Boolean) Use this if you want to prevent the persistant variable from being deleted. (Default: false)

Let’s see a few examples on how to use all these options:

Open specific list item

// Open by ID
Fliplet.App.Storage.set('flDynamicListQuery:simple-list', {
  open: {
    id: 1234
  }
});

// Open by column and value
Fliplet.App.Storage.set('flDynamicListQuery:simple-list', {
  open: {
    column: "First Name",
    value: "John"
  }
});

Load list with search value

// Search by value only
Fliplet.App.Storage.set('flDynamicListQuery:simple-list', {
  search: {
    value: "business apps"
  }
});

// Search by value on a specific data column
Fliplet.App.Storage.set('flDynamicListQuery:simple-list', {
  search: {
    column: "Title",
    value: "business apps"
  }
});

// Search by value on an array of data columns
Fliplet.App.Storage.set('flDynamicListQuery:simple-list', {
  search: {
    column: ["Title", "Category"],
    value: "business apps"
  }
});

Load list with a filter

// Applying one filter
Fliplet.App.Storage.set('flDynamicListQuery:simple-list', {
  filter: {
    value: "Apps"
  }
});

// Applying multiple filters
Fliplet.App.Storage.set('flDynamicListQuery:simple-list', {
  filter:{
    value: ["Apps", "London"]
  }
});

Pre-filter the list

Fliplet.App.Storage.set('flDynamicListQuery:simple-list', {
  prefilter: [
    {
      column: "Title",
      logic: "contains",
      value: "apps"
    }
  ]
});

Other options

Fliplet.App.Storage.set('flDynamicListQuery:simple-list', {
  search: { ... },
  goBack: {
    enableButton: true,
    action: "(function () { console.log('run code') })"
  },
  persist: true
});

Chain features

A pre-filter and a search

Fliplet.App.Storage.set('flDynamicListQuery:simple-list', {
  prefilter: [
    {
      column: "Title",
      logic: "contains",
      value: "apps"
    }
  ],
  search: {
    column: ["Title", "Category"],
    value: "business apps"
  }
});

Operators for the logic key

  • == Equals
  • != Not equal
  • > Greater than
  • >= Greater than or equal
  • < Less than
  • <= Less than or equal
  • contains Contains
  • notcontain Not contain
  • regex RegExp

Back to API documentation