MConsole

Overview

MConsole is a php class for displaying dashboards from configuration files and passed data parameters.

With PHP code like this:

$console = mlib\ui\console\MConsoleFactory::createFromFile(__DIR__."/path/to/console.conf");
$console->registerAssetsPath("path/to/assets_libs/mlib/MConsole");

$console->setData($datas);
$console->setTitle("Users");
$console->setFooterDatas(array(count($datas), 'Total users'));

$console->run();

and a "console.conf" file (see below), here's the kind of table that can be created:

In this example, many of MConsole's features are being used (toolbar, footer, expandable rows...), but you can choose to use only the ones you need.

The configuration file used to generate this table: mconsole_sample.conf

Configuration File

MConsole configuration files are of type MConfig (see here).

A configuration file must contain a 'columns' block with the definitions of all table columns:

<columns>

  <column_name>
    type = the_type
    label = the_label
    ...
    ...
  </column_name>

  ...
  ...
  ...

</columns>

Common parameters for column definitions, regardless of type:

Required:

• type: one of these values: data, link, mailto, custom, or one of the three special types: details, modify, and delete
• label: the column header label

Optional (except for special types):

• width: column width
• max_width: maximum column width
• align: left, center, right
• sortable: boolean
• sort_method: client or server
• sort_url: required if sort_method is server
• responsive: boolean
• responsive_level: an integer that will define the column's behavior relative to screen width

En fonction du type renseigné, un certain nombre d'autre directives seront à fournir de manière obligatoire ou optionnelle.

The configuration file can contain additional blocks and parameters:

• a toolbar block
• a footer block
• parameters:
  • width or min_width (mutually exclusive): in pixels or percentage (if in pixels, don't specify a unit)
  • expandable (boolean): whether rows can be expanded or not
  • expand_url (required if the above parameter is set to true): a base URL for AJAX calls that will be displayed when the row is "expanded" (same principle as for delete or modify columns, see here)

Different Types

data

The data type is the most commonly used. It can be used for string or numeric data.

link

The link type allows displaying links in the console.
In the data passed to the console (setDatas() method), for link type data, you can pass an array like array('url', 'label').

Optional parameter:

• external (boolean): whether the link should open in a new tab

mailto

Similar to the link type, the mailto type creates clickable mailto links.

Optional parameter:

• encoded (boolean): whether email addresses should be obfuscated or not
  This parameter can be used when displaying email lists on public pages.
  It makes email harvesting slightly more difficult

custom

The custom type allows for custom cell content (for icons, for example).

Special Types

details

The details type displays a small magnifying glass that will either be a link to a URL returning the row details, or display the details provided with the console data, depending on whether the url parameter is used or not.
Everything is displayed in a modal window.

Optional parameters:
* url: the URL to be called to display the row details
* title: the modal window title
* window_width: the modal window width
* window_height: the modal window height

delete

The delete type displays a small trash can that will be a link to a URL for deleting a row.

Required parameter:

• url: the URL to be called for deletion

modify

The modify type displays a small pencil that will be a link to a URL for editing a row.

Required parameter:

• url: the URL to be called for modification

The url Parameter

The url parameter passed for these three column types is a base URL.
The call will always be made using the GET method, and obviously, the final URL called will not be the same from one row to another.

An identifier will be added as a parameter to the URL.

The parameter name is id, and you decide its value in the data passed to mconsole: value of console_id

The controller at this address will therefore need to handle the id parameter

Data to Pass to MConsole

The setDatas($datas) method takes as a parameter an array containing the console data.

Each element of the array is an associative array containing the data for one row of the console: 'column_name' => 'value'

'value' depends on the column type:

• data:

  A string
  The value can also be an array of 2 elements. If so, the second element will be used if the column is 'sortable' with 'sortmethod = client'. This can be useful if the sort order is different from alphabetical order.

• link:

  An array of 1, 2, or 3 elements
  The first element is the link URL
  The second element is the link label if provided, otherwise the label will be the URL
  The third element is a boolean indicating if the link is external or not (default: false).
  If the link is external, a small icon is added after the link and the link opens in a new tab.

• mailto:

  An array of 1 or 2 elements
  The first element is the email address
  The second element is the mailto link label if provided

• delete:

  true or false
  Indicates whether the small trash can should appear on the row

• modify:

  true or false
  Indicates whether the small pencil should appear on the row

In addition to the key/value pairs for each column defined in the configuration file, the array corresponding to a console row must contain:

• "console_id" => 'identifier'

• "console_display" => 'a label'

Required if a column of type "delete" or "details" has been defined
It allows displaying a more meaningful modal

• "console_details" => array(array( ... ), ..., array( ...))

Required if a column of type "details" has been defined without specifying a URL
In this case, the details modal for a row will display the data passed here
This is an array of arrays, with each array defining a group of values
For each key/value pair, the value can be an array

Extras

Toolbar

You can define a toolbar block at the root of the configuration file to add buttons to your console.

<toolbar>
    <toolname>
        label = libellé du bouton
        url = url du bouton
    <toolname>

    ...
    ...

</toolbar>

If toolname is add, pdf, export, or spreadsheet, the button will have an icon. MConsole does not handle what happens when the button's URL is called. You are solely responsible for this.

There are 2 special built-in buttons in MConsole. These buttons have JavaScript actions, so you don't need to specify a URL.

native_printable

<native_printable>
    label = Printable Version
    columns = column_name_1,column_name_4, ...
</native_printable>

This button will display only the table in a new tab (only the columns indicated), deprived of its toolbar, any optional details, delete or modify columns, and of course of everything that might be around the page.

native_export

<native_export>
    label = Export CSV
    columns = column_name_1,column_name_4, ...
    filename = export.csv
</native_export>

This button will download a CSV file containing the table data (only the indicated columns) with a header row.


<a id="footer"></a>

### Footer

You can define a `footer` block at the root of the configuration file to add a special row to your console.

```

colgroups defines the colspans : the sum of colgroups must equal the number of columns
align defines the alignments : there must be as many alignments as there are colgroups

If a footer is defined in the configuration file, you'll need to call the setFooterDatas($footer_datas) method for anything to appear in it.

$footer_datas is an array that must contain the same number of values as the number of colgroups. Values can be strings or numeric.
Some values can also be null or an empty string. In this case, the footer cell will appear empty and darker.