List

Intro

List View is a component in Activator designed to display dynamic data in an HTML table. It leverages the JavaScript DataTable component to provide a robust and streamlined solution for efficiently presenting and managing large amounts of data. By utilizing a specified data source, the List View simplifies the implementation of interactive and responsive tables while offering advanced features such as sorting, pagination, and search. This component optimizes data display while reducing development time required for creating interactive tables.

Graphic example

Structurally, once interpreted, a list renders like the image above. However, let's highlight the different structures that make up the List component

The breakdown reveals nine main parts:

1. List icon
2. Title List
3. Button to change list view
4. Search bar to find an element in the view
5. button to collapse the list. The idea is to collapse the list container in order to create another container to display more details about an element in a list view.
6. Buttons a actions for a list view.
7. Line for the titles of each column.
8. list view element container

9. view list header.

   Before going into detail about the various structures resulting from the decomposition of a ListView (illustrated in the image above ☝️), let's start by focusing on the creation of a List component on Activator Admin🤫.

Creation

The creation of List View components on Activator Admin allows us to build a visual representation of a data collection on several views. This user interface widget is managed by four main components:

1. List View: Contains the definition of the main elements of the table, including views and action buttons.
2. List View Driver: Manages behaviors and events related to the List View.
3. View: Defines the main view by binding the data source, arranging the columns, and managing security privileges.
4. View Driver: Customizes the view and handles behaviors for events and actions in the List View.

List View

This is the main component responsible for defining the main elements of the data table, such as the different views taken into account, the different action buttons, etc.

Creation

In Activator Admin , the List view component is located within the menu container, among the items listed under List📑. As shown at (1) on the image below.

NB🚨: Make sure you are in the System Component main module.

After initiating the creation of the List view, by clicking on the +Add new button (illustrated at (2) on the image above), you’ll observe a form (illustrated at (3) on the image above) appearing on the right side with some fields.

🔬After filling in the name and description fields, let's focus on the Definition and Meta Data fields.

The Meta Data field gathers and provides additional information for the component, such as configuration and parameters, as well as the accessibility and security measures associated with this component. Please refer to Meta Data for the complete list of additional information related to this component.

As for the Definition field, let's take a closer look at its JSON content.

{
    "resourceName": "",
    "title": "List View",
    "description": "Sample List View",
    "titleResKey": "",
    "descResKey": "",
    "driver": "",
    "icon": "far fa-address-card",
    "views": [
        {
            "name": "",
            "index": 0,
            "visibleFor": {
                "roles": [
                    "sys.everyone"
                ]
            }
        }
    ],
    "buttons": [
        {
            "name": "new",
            "index": 0,
            "title": "New",
            "titleResKey": "",
            "icon": "tio-add",
            "options": [],
            "visibleFor": {
                "roles": [
                    "sys.everyone"
                ]
            }
        },
        {
            "name": "options",
            "index": 1,
            "title": "Options",
            "titleResKey": "",
            "icon": "tio-more-vertical",
            "options": [
                {
                    "id": "option1",
                    "title": "Option 1",
                    "icon": "fas fa-edit",
                    "visibleFor": {
                        "roles": [
                            "sys.everyone"
                        ]
                    }
                },
                {
                    "id": "option2",
                    "title": "Option 2",
                    "icon": "fas fa-edit",
                    "visibleFor": {
                        "roles": [
                            "sys.everyone"
                        ]
                    }
                }
            ],
            "visibleFor": {
                "roles": [
                    "sys.everyone"
                ]
            }
        }
    ]
}

Description

[
    {
        "name": "",
        "index": 0,
        "visibleFor": {
            "roles": [
                "sys.everyone"
            ]
        }
    }
]

[
    {
        "name": "new",
        "index": 0,
        "title": "New",
        "titleResKey": "",
        "icon": "tio-add",
        "options": [],
        "visibleFor": {
            "roles": [
                "sys.everyone"
            ]
        }
    },
    {
        "name": "options",
        "index": 1,
        "title": "Options",
        "titleResKey": "",
        "icon": "tio-more-vertical",
        "options": [
            {
                "id": "option1",
                "title": "Option 1",
                "icon": "fas fa-edit",
                "visibleFor": {
                    "roles": [
                        "sys.everyone"
                    ]
                }
            },
            {
                "id": "option2",
                "title": "Option 2",
                "icon": "fas fa-edit",
                "visibleFor": {
                    "roles": [
                        "sys.everyone"
                    ]
                }
            }
        ],
        "visibleFor": {
            "roles": [
                "sys.everyone"
            ]
        }
    }
]

List View Driver

The List View Driver is an essential component that acts as a controller for the List View. It allows specific behaviors to be attached to various events and actions related to the data table.

Creation

In Activator Admin , the List view driver component is located within the menu container, among the items listed under List📑. As shown at (1) on the image below.

NB🚨: Make sure you are in the System Component main module.

After initiating the creation of the List view driver, by clicking on the +Add new button (illustrated at (2) on the image above), you’ll observe a form (illustrated at (3) on the image above) appearing on the right side with some fields.

🔬After filling in the name and description fields, let's focus on the Definition and Meta Data fields.

The Meta Data field gathers and provides additional information for the component, such as configuration and parameters, as well as the accessibility and security measures associated with this component. Please refer to Meta Data for the complete list of additional information related to this component.

As for the Definition field, let's take a closer look at its JavaScript content.

$activator.ui.jsmodules.define(function () {
    // Called to initialize the driver
    this.initialize = function (context) {
        return new Promise((resolve, reject) => {
            //this.__ui.on("load", function (args) {
            //});
            //this.__ui.on("rowselected", function (args) {
            //});
            //this.__ui.on("buttonclick", function (args) {
            //});
            resolve();
        });
    };
});w

Description

Note🛑: Logging the arg argument of the above events, we have👇 :

View

The View component is responsible for managing the detailed definition of a view within the List View. It handles everything from binding the data source to the definition of column layouts, ensuring that the data is displayed accurately and efficiently. Additionally, it takes into account security aspects by managing access privileges, ensuring that only authorized users can view or interact with certain data or features. This component plays a critical role in providing a flexible and secure data presentation layer while maintaining a clean separation between data handling and the user interface.

Creation

In Activator Admin , the View component is located within the menu container, among the items listed under List📑. As shown at (1) on the image below.

NB🚨: Make sure you are in the System Component main module.

After initiating the creation of the view, by clicking on the +Add new button (illustrated at (2) on the image above), you’ll observe a form (illustrated at (3) on the image above) appearing on the right side with some fields.

🔬After filling in the name and description fields, let's focus on the Definition and Meta Data fields.

The Meta Data field gathers and provides additional information for the component, such as configuration and parameters, as well as the accessibility and security measures associated with this component. Please refer to Meta Data for the complete list of additional information related to this component.

As for the Definition field, let's take a closer look at its Json content.

{
    "resourceName": "",
    "title": "View",
    "description": "A sample View",
    "titleResKey": "",
    "descResKey": "",
    "isCustom": "false",
    "driver": "",
    "dataBinding": {
        "dataSource": ""
    },
    "columns": [
        {
            "name": "firstName",
            "index": 0,
            "title": "First Name",
            "titleResKey": "",
            "dataBinding": {
                "dataMember": "firstName"
            },
            "visibleFor": {
                "roles": [
                    "sys.everyone"
                ]
            }
        },
        {
            "name": "lastName",
            "index": 0,
            "title": "Last Name",
            "titleResKey": "",
            "dataBinding": {
                "dataMember": "lastName"
            },
            "visibleFor": {
                "roles": [
                    "sys.everyone"
                ]
            }
        }
    ]
}

Description

{
    "dataSource": ""
}

[
    {
        "name": "firstName",
        "index": 0,
        "title": "First Name",
        "titleResKey": "",
        "dataBinding": {
            "dataMember": "firstName"
        },
        "visibleFor": {
            "roles": [
                "sys.everyone"
            ]
        }
    },
    {
        "name": "lastName",
        "index": 0,
        "title": "Last Name",
        "titleResKey": "",
        "dataBinding": {
            "dataMember": "lastName"
        },
        "visibleFor": {
            "roles": [
                "sys.everyone"
            ]
        }
    }
]

View Driver

The View Driver component allows for detailed customization of a List View by adjusting its appearance and behavior. It provides the ability to modify specific elements of the view, such as the column layout, visual styles, or the addition of interactive features. In addition to customizing the view, the View Driver enables the attachment of behaviors to various events and actions related to the List View, such as clicks on rows or buttons, using events similar to those defined in the List View Driver.

Creation

In Activator Admin , the View component is located within the menu container, among the items listed under List📑. As shown at (1) on the image below.

NB🚨: Make sure you are in the System Component main module.

After initiating the creation of the view driver, by clicking on the +Add new button (illustrated at (2) on the image above), you’ll observe a form (illustrated at (3) on the image above) appearing on the right side with some fields.

🔬After filling in the name and description fields, let's focus on the Definition and Meta Data fields.

The Meta Data field gathers and provides additional information for the component, such as configuration and parameters, as well as the accessibility and security measures associated with this component. Please refer to Meta Data for the complete list of additional information related to this component.

As for the Definition field, let's take a closer look at its JavaScript content.

$activator.ui.jsmodules.define(function () {

    // Called to initialize the driver
    this.initialize = function (context) {
        return new Promise((resolve, reject) => {
            //this.__ui.on("load", function (args) {
            //
            //});
            //this.__ui.on("columnDataBind", function (args) {

            //
            //});
            //this.__ui.on("columnDataBind", function (args) {

			//
            //});
            resolve();
        });
    };

    //Render the content
    this.render = function (context) {
        return new Promise((resolve, reject) => {
            resolve();
        });
    };


    //Builds the data source arguments
    this.buildDataSourceArgs = function (context) {
        return new Promise((resolve, reject) => {

            //for stored functions
            //resolve({
            //    arguments: []
            //});

            //for stored queries
            resolve({
                parameters: []
            });
        });
    };

});

View Driver Configuration

NB🚨: The context provided as an argument in the following list of events encompasses both the information passed during the instantiation of the List View and the current contextual data related to the user interface of the view.

• initialize() 

  View initialization.

  Inside, we can access the property this.__ui, which allows us to listen to and attach different behaviors to events such as:

// Attach the `columnDataBind` event to customize the display of columns.
this.__ui.on('columnDataBind', function (args) {
    // Retrieve column information and data related to the current record.
    const columnName = args?.column?.columnName; // Name of the column
    const record = args?.record; // Data of the current row

    // Validate the data before proceeding
    if (!columnName || !record) return;

    // Customization based on the column name
    switch (columnName) {
        case 'name': // "name" column
            return {
                skip: true, // Skip the default rendering
                value: `${record.firstName} ${record.lastName}`, // Display first and last name
            };

        case 'city': // "city" column
            return {
                skip: true,
                value: record.city || '-', // Display the city or "-" if no data
            };

        case 'country': // "country" column
            return {
                skip: true,
                value: record.country || '-', // Display the country or "-" if no data
            };

        default:
            return; // Do nothing for unspecified columns
    }
});

this.__ui.on('columnDataBind', function (args) {
    switch (args.record.isActive) {
        case false:
            return {
                skip: true
        };
            break;
    }
});

• render()

  It provides developers with the ability to customize the display logic of the view, tailoring its content and behavior to meet specific needs.

• buildDataSourceArgs()

  Allows the developer to design or customize the arguments or parameters of the data source bound to the view.

NB🚨: The developer must ensure that the appropriate information is provided based on the type of data source bound to the view:

• Use resolve({ parameters: [] }); if a storedQuery is bound to the view.
• Use resolve({ arguments: [] }); if a storedFunction is bound to the view.

How To Instanciate A List View

To instantiate a list view, the following method is used:

$activator.ui.renderListView({
        container: "", // The JQuery DOM container
        name: "", // The List View name
        model: {
        // Add the necessary data for the List View here
        // If your List View does not expect any param, just send an empty object {}
    }
}).then((listView) => {
    //Stuffs to do after the listView is rendered
});

 ✋IMPORTANT: List View Initialization can be done anywhere in component of type Driver (Helper, Content Provider, Driver, Menu Item Driver, Tabbar Driver, etc…).

Conclusion

In conclusion, the List View component in Activator provides a powerful and flexible solution for displaying and managing data in an interactive table. Through its various sub-components, such as the List View Driver, View, and View Driver, it enables advanced customization, efficient event handling, and precise configuration of columns and actions. This component ensures an optimized user experience while reducing development complexity. After exploring the numerous possibilities offered by the List View, it is only natural to turn to the Form component, which complements this dynamic by simplifying data entry and management.