MConsole

Présentation

MConsole est une classe php pour afficher des tableaux de bord à partir de fichiers de configuration et de données passées en paramètre.

Avec un code php comme celui-ci :

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

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

$console->run();

et un fichier "console.conf" (voir plus bas), voici le genre de tableau que l'on peut créer :

Dans cet exemple, un grand nombre des possibilités offertes par MConsole ont été utilisées (toolbar, footer, lignes extensibles ...), mais selon les besoins vous pourrez n'en utilier que quelques-unes.

Le fichier de configuration qui a permis de générer ce tableau : mconsole_sample.conf

Le fichier de configuration

Les fichiers de configuration pour MConsole sont des fichiers de type MConfig (voir ici).

Un fichier de configuration doit contenir un bloc 'columns' contenant les définitions de toutes le colonnes du tableau :

<columns>

  <nom_de_colonne>
    type = le_type
    label = le_label
    ...
    ...
  </nom_de_colonne>

  ...
  ...
  ...

</columns>

Paramètres communs aux définitions de colonnes, quelque soit le type :

Requis :

• type : une des valeurs parmis : data, link, mailto, custom ou un des trois types spéciaux details, modify et delete
• label : le libellé en tête de colonne

Optionnels (hors types spéciaux):

• width : la largeur de la colonne
• max_width : la largeur maximale de la colonne
• align : left, center, right
• sortable : booleen
• sort_method : client ou server
• sort_url : requis si sort_method est server
• responsive : booleen
• responsive_level : un entier qui définira le comportement de la colonne vis à vis de la largeur de l'écran

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

Le fichier de configuration peut contenir des blocs et paramètres supplémentaires :

• un bloc toolbar
• un bloc footer
• les paramètres :
  • width ou min_width (exclusifs) : en pixels ou en pourcentage (si en pixels ne rien indiquer)
  • expandable (booléen) : si les lignes peuvent être dépliées ou non
  • expand_url (obligatoire si le paramètre du dessus est defini à true) : une base d'url pour les appels ajax de ce qui sera affichés quand la ligne sera "dépliée" (même principe que pour les colonnes delete ou modify, voir ici)

Les différents types

data

Le type data est le type le plus utlisé. Il peut être utilisé pour des données comme des chaines de caractères ou des données numériques.

link

Le type link permet d'afficher des liens dans la console
Dans les données passées en paramètre de la console (methode setDatas()), on pourra, pour les données de type link passer un tableau de type array('url', 'label')

Paramètre optionnel :

• external (booléen) : si le lien doit ouvrir un nouvel onglet

mailto

Similaire au type link, le type mailto permet de créer des lliens mailto cliquables

Paramètre optionnel :

• encoded (booléen) : si les adresses mail doivent être obfusquées ou non\
  Ce paramètre peut être utilise si on affiche des liste de mail sur des pages publiques.\
  Il rend la récupération des adresses un peu plus compliquée

custom

Le type custom permet de faire un contenu de cellules personnalisé (pour des icones par exemple).

Les types spéciaux

details

Le type details permet d'afficher une petite loupe qui sera soit un lien vers une url qui renvoie les détails de la ligne, soit les détails fournis avec les données de la console, selon que le paramètre url est utilisé ou non.
Le tout est affiché dans une boite modale.

Paramètres optionnels :
* url : l'url qui doit être appelée pour afficher les détails d'une ligne
* title : le titre de la boite modale
* window_width : la largeur de la boite modale
* window_height : la hauteur de la boite modale

delete

Le type delete permet d'afficher une petite corbeille qui sera un lien vers une url pour supprimer une ligne

Paramètre obligatoire :

• url : l'url qui doit être appelée pour une suppression

modify

Le type modify permet d'afficher un petit crayon qui sera un lien vers une url pour modifier une ligne

Paramètre obligatoire :

• url : l'url qui doit être appelée pour une modification

Le paramètre url

Le paramètre url qui est passé pour ces trois types de colonnes est une base d'url.
L'appel se fera toujours avec la methode GET et bien évidemment l'url finale qui sera appelée ne sera pas la même sur une ligne ou sur une autre.

Un identifiant sera ajouté en paramètre à l'url.

Le nom du paramètre est id, et c'est vous qui décidez de sa valeur dans les données passées à mconsole : valeur de console_id

Le controleur à cette adresse devra donc appréhender le paramètre id

Les données à passer à MConsole

La methode setDatas($datas) prend en paramètre un tableau contenant les données de la console.

Chaque élément du tableau est un tableau associatif qui contient les données d'une ligne de la console : 'nom_de_colonne' => 'valeur'

'valeur' dépend du type de la colonne

• data :

  Une chaine de caractères
  La valeur peut aussi être un tableau de 2 éléments. Si tel est le cas, le deuxième élément sera utilisé si la colonne est 'sortable' avec 'sortmethod = client'. Cela peut être utile si le tri est différent de l'ordre alphabétique.

• link :

  Un tableau de 1, 2 ou 3 éléments
  Le premier élément est l'url du lien
  Le deuxième élément est le libellé du lien s'il est fourni, sinon le libellé sera l'url
  Le troisième élement est un booléen qui dit si le lien est externe ou pas (defaut : false).
  Si le lien est externe, une petite icone est ajoutée à la suite du lien et le lien s'ouvre dans un nouvel onglet.

• mailto :

  Un tableau de 1 ou 2 éléments
  Le premier élément est l'adresse mail
  Le deuxième élément est le libellé du lien mailto s'il est fourni

• delete :

  true ou false
  Indique si la petite corbeille doit apparaitre ou non sur la ligne

• modify :

  true ou false
  Indique si le petit crayon doit apparaitre ou non sur la ligne

En plus des paires clé/valeur données chaque colonne défnie dans le fichier de configuration, le tableau correspondant à une ligne de la console, doit contenir :

• "console_id" => 'identifiant'

• "console_display" => 'un libellé'

Obligatoire si une colonne de type "delete" ou "details" a été définie
Il permet d'afficher une boite modale plus parlante

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

Obligatoire si une colonne de type "details" a été définie sans préciser d'url
À ce moment là, la boite modale des détails concernant une ligne affiche les données passées ici
C'est un tableau de tableaux, chaque tableau définissant un groupe de valeurs
Pour chaque pair clé/valeur, valeur peut être un tableau

Extras

Toolbar

On peut, à la racine du fichier de configuration, définir un bloc toolbar pour ajouter des boutons à notre console.

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

    ...
    ...

</toolbar>

Si toolname est add, pdf, export ou spreadsheet, le bouton aura une icone
MConsole ne prend pas en charge ce qui est fait lors de l'appel à l'url du bouton. Vous en êtes seul(e) responsable.

Il existe 2 bouton spéciaux intégrés à MConsole. Ces deux boutons ont une action écrite en javascript et on ne doit donc pas spécifier d'url.

native_printable

<native_printable>
    label = Version imprimable
    columns = nom_colonne_1,nom_colonne_4, ...
</native_printable>

Ce bouton affichera uniquement le tableau dans un nouvel onglet (seulement les colonnes indiquées), dépourvu de sa toolbar, des éventuelles colonnes details, delete ou modify, et bien sur de tout ce qu'il pouvait y avoir autour dans la page.

native_export

<native_export>
    label = Exporter
    columns = nom_colonne_1,nom_colonne_4, ...
    filename = export.csv
</native_export>

Ce bouton permet de télécharger un fichier csv contenant les données du tableau (seulement les colonnes indiquées) avec la ligne d'entête.

Footer

On peut, à la racine du fichier de configuration, définir un bloc footer pour ajouter une ligne spéciale à notre console

<footer>
    colgroups = n1,n2,...
    align = left,right,...
</footer>

colgroups définit les colspans : la somme des colgroups doit être égal au nombre de colonnes
align definit les alignements : il doit y en avoir autant que de colgroups

Si un footer est défini dans le fichier de configuration, il faudra appeler la méthod setFooterDatas($footer_datas) pour que des choses y apparaissent.

$footer_datas est un tableau qui doit contenir le même nombre de valeurs que le nombre de colgroups. Les valeurs peuvent être des chaines de caractères ou des valeurs numériques.
Certaines valeurs peuvent aussi être null ou une chaine vide. Dans ce cas la case du footer apparait vide et plus foncée.