Melis Platform V2. Back-Office. Functionment of modules. Content: Date Version 2.0

Transcription

1 4, rue du Dahomey Paris, France ( Melis Platform V2 Back-Office Functionment of modules Content: This document explains how to create a module for Melis Platform's backoffice. Date Version Melis Technology

2 1. MELIS PLATFORM S MODULES ARCHITECTURE Filesytem of modules Public folder and AssetManager MELIS PLATFORM S INTERFACE RENDERING SYSTEM Reminder on ZF2 s module config merging system Melis Platform s interface principle Forward plugin Melis Platform modules App.interface.php Introduction Structure of the config file Interface s nested children views Generating parts of the interface only: route /melis/zoneview Creating repeating blocks in the app.interface.php config file MelisModuleConfig : Arranging order of blocks / Not showing blocks Interface exclusions: deactivation of rendering of interface s blocks on a user basis Melis Platform s Javascript rendering Helpers ZoneReload Helper TabOpen Helper TabClose Helper TabSwitch Helper CreateModal Helper MelisOkNotification Helper MelisKoNotification Helper MELIS PLATFORM S ACTION SYSTEM Introduction Actions through DISPATCH or custom event and session sharing Actions through custom events Principle Advanced example... 18

3 1. MELIS PLATFORM S MODULES ARCHITECTURE 1.1. Filesytem of modules All Melis Platform s modules are typical ZF2 modules. They are organized with the typical folders and files of a ZF2 project: - /config - /language - /src - /view - Module.php Added to this are the following folders: - /install/sql: where your setup SQL creation files can be created for an initial setup o setup_structure.sql o setup_datas.sql Those 2 files will be executed if found by the setup upon full installation of the platform. - /public : where all assets of the module must be present to be available when called 1.2. Public folder and AssetManager Melis Platform uses the AssetManager module to handle assets of every modules, meaning that every module is one and only one folder containing everything. There is no need to copy/paste your assets into the main public folder and all files can stay organized in their own modules. Melis Platform implements only one rules to access the assets: calls must start with the module s name. Examples: - /MelisCore/styles/styles.css - /MelisCalendar/css/calendar.css - /MelisCore/js/core/melisSidebar.js Every module has to declare its resolver config alias in its module.config.php: 'asset_manager' => array( 'resolver_configs' => array( 'aliases' => array( 'MelisCms/' => DIR. '/../public/',

4 2. MELIS PLATFORM S INTERFACE RENDERING SYSTEM 2.1. Reminder on ZF2 s module config merging system Zend Framework 2 uses a configuration merging system between the activated modules. All module.config.php files are merged together to end up with one configuration array containing everything. Here s an example of the configuration that results from 2 modules: Config Module 1 Config Module 2 Final config 'router' => array( 'routes' => array( 'route1' => array(... 'router' => array( 'routes' => array( 'route2' => array(... 'router' => array( 'routes' => array( 'route1' => array(... 'route2' => array(... This system allows different modules to add or alter the configuration of other modules, but the order of loading of modules can become very important Melis Platform s interface principle Melis Platform uses the same configuration merging system to create its interfaces. Every module defines its own interfaces and can modify or add the ones of others modules in order to add new functionalities to the platform. The whole interface has been thought this way, which means that absolutely every part of the interface leads to a configuration file describing the part of interface it deals with. Example of the main structure defined in MelisCore config file: 'meliscore' => array( 'meliscore_header' => array(... 'meliscore_leftmenu' => array(... 'meliscore_center' => array(... Example of the structure of MelisCms config file: 'meliscore' => array( 'meliscore_leftmenu' => array( 'meliscms_sitetree' => array(... 'meliscms' => array( 'meliscms_sitetree' => array(... 'meliscms_toolstree' => array(... This config file gives a good example of the merging process as we can see that MelisCms module is altering MelisCore config to add some datas into the leftmenu key, and defines its own interfaces inside the meliscms key.

5 2.3. Forward plugin ZF2 implements a Forward plugin that allows to execute a controller action and get the resulting view in return: This plugin is the base on which Melis Platform is building interfaces. Every interface defined in the configuration is linked to a forward key defining how to render it. The view returned is then associated to its parent, making it nested. Example: Config IndexController View 'meliscore_header' => array( 'forward' => array( 'module' => 'MelisCore', 'controller' => 'Index', 'action' => 'header',... Public function headeraction <div> Header </div> 2.4. Melis Platform modules App.interface.php Introduction Every Melis Platform module comes with an app.interface.php file located in the config folder of the module. Some modules may come with more than one app.interface.php file, depending on the complexity of the module and the functionalities to implement. The file is added to the config in the Module.php getconfig function. This file is the definition of all the interfaces that the module is bringing, and it is read and exploited by two files: - /melis-core/src/service/meliscoreconfigservice.php: the service in charge of reading the configuration file - /melis-core/src/controller/pluginviewcontroller.php: the controller in charge of generating all views and nested children views Structure of the config file All app.interface.php config files are starting with the key plugins followed by the name of the plugin: return array( 'plugins' => array( 'meliscore' => array(... ;

6 The config file is then composed of different sections: 'conf' => array( 'id' => 'id_melis_core', // Put here any configuration datas you could need 'datas' => array( // Put here any additional datas 'ressources' => array( 'js' => array( '/MelisCore/assets/components/library/jquery/jquery.min.js?v=v1.2.3', // Add here all the JS files needed for this module 'css' => array( '/MelisCore/assets/css/styles.css', // Add here all the CSS files needed for this module // describe your interface here - conf section: this is made to put configuration datas of your modules. - datas section: this is made to add some more datas about your module, but not categorized as configuration - ressources section: with its 2 sub keys js and css, it will list all the assets that the module will need. All those files, from every module, will be added to the HTML source at the generation of the back-office, making the features inside fully available for the interface. Extract from the layout code for adding CSS files: <?php foreach ($pluginsfiles['css'] as $cssfile $this->headlink(->appendstylesheet($this->basepath($cssfile; echo $this->headlink(;?> - interface section: the description of all the module s interface and children interfaces Extract from the MelisCore interface: 'meliscore_header' => array( 'conf' => array( 'id' => 'id_meliscore_header', 'meliskey' => 'meliscore_header', 'name' => 'tr_meliscore_header', 'forward' => array( 'module' => 'MelisCore', 'controller' => 'Index', 'action' => 'header', 'jscallback' => '', 'jsdatas' => array( 'meliscore_header_flash_messenger' => array( 'conf' => array(... 'forward' => array(......

7 Interface s nested children views As seen in the precedent paragraph, the interface key is the most important one in defining the module s interface. Cutting the code into several sub interfaces will allow other modules to add content and functionalities through their own app.interface.php. But in order to make this system working, it is necessary to understand how ZF2 s MVC is working with nested views. In ZF2, in order to to attach a view to another one as a child, you will need to do this: In the controller, attach the subview to the current one and link it to a key: $view->addchild($subview, mysubview ; In the view, make an echo of the key so that the view will be displayed at the right position: <div> <?= echo $this->mysubview;?> </div> Melis Platform s back-office rendering engine will follow the exact same process, except that the engine will do all the work of automatically generating the views from the config file (using forward plugin and attach them together. But it will be needed to place the keys inside the views so that the children views will be displayed. The key s name will be the interface s key. It is also highly recommended to loop on the config s sub-interfaces so that this can be dynamic as, in every view and controller, the corresponding part of the config file is automatically added in the zoneconfig variable: Config file 'meliscore_header' => array( 'conf' => array( 'id' => 'id_meliscore_header', 'meliskey' => 'meliscore_header', 'name' => 'tr_meliscore_header', 'forward' => array( 'module' => 'MelisCore', 'controller' => 'Index', 'action' => 'header', 'jscallback' => '', 'jsdatas' => array( 'meliscore_header_flash_messenger' => array( 'conf' => array(... 'forward' => array( Index/header view Specific positioning <h1>header</h1> <div> <?= $this->meliscore_header_flash_messenger;?> </div> List positioning (modular <h1>header</h1> <div> <?php if (!empty($this->zoneconfig['interface'] foreach ($this->zoneconfig['interface'] as $keyconfig => $detailsconfig echo $this->$keyconfig;?> </div>

8 Generating parts of the interface only: route /melis/zoneview The fact that all the interface are separated in different parts makes it easy to generate only parts of the interface, allowing to make ajax calls to reload some zones of your interface. In order to generate a subpart of the interface, you basically need to provide a key telling which part is to be used for the generation. To follow the previous example, generating the meliscore_header_flashmessenger part corresponds to accessing to this path in the config array: /meliscore/interface/meliscore_header/interface/meliscore_header_flashmessenger But this would be very boring to use when it comes to go through 10 levels of sub-interfaces. This is why the meliskey has been created in the conf section of every block. This meliskey, which must be unique all along the platform (therefore highly recommended to prefix your key with the module s name will be translated into the correct path by the MelisCoreConfigService, resulting in the correct part returned. Example of defined meliskey for the meliscore_header block: 'meliscore_header' => array( 'conf' => array( 'id' => 'id_meliscore_header', 'meliskey' => 'meliscore_header', 'name' => 'tr_meliscore_header', 'forward' => array( In this example, the meliscore_header block is accessible by using this 2 keys: - /meliscore/interface/meliscore_header - meliscore_header Melis Platform comes with a /melis/zoneview route, dispatching to the PluginViewController. Giving a cpath GET parameter to this URL corresponding to your block key will give in return the content of this block and all children views. Example of URL: /melis/zoneview?cpath=meliscore_header Calling the route /melis/zoneview in a browser will give you an HTML response and, within this HTML, a script tag will be written to add jscallbacks and jsdatas that might be inside the block s forward (to activate some JS effects for example. Calling the same route in an Ajax call will activate the Json Strategy and a Json response will be sent containing the following elements: - html: the HTML content - jscallbacks: callbacks that have to be done after replacing the old content by the new one (to activate some JS effects for example - jsdatas: any JS variable that needs to be sent Note: JsCallbacks and JsDatas will be brought back on a post-order traversal way, so that sub-blocks can be initialized before their parents are.

9 Example of treatment of jscallbacks and jsdatas: 'meliscore_header' => array( 'conf' => array( 'id' => 'id_meliscore_header', 'meliskey' => 'meliscore_header', 'name' => 'tr_meliscore_header', 'forward' => array( 'module' => 'MelisCore', 'controller' => 'Index', 'action' => 'header', 'jscallback' => 'my_callback1(;', 'jsdatas' => array( 'meliscore_header_flash_messenger' => array( 'conf' => array(... 'forward' => array( 'module' => 'MelisCore', 'controller' => 'Index', 'action' => 'header', 'jscallback' => 'my_callback2(;', 'jsdatas' => array(... Results: HTML call: <script> my_callback2(; my_callback1(; </script> Ajax call: JSON answer html :., jscallbacks : [ my_callback2(;, my_callback1(; ], jsdatas : []

10 Creating repeating blocks in the app.interface.php config file Sometimes, the interface s design will need to repeat itself. For example, you might want to open 2 different tabulations that have the same structure, yet are different because of the datas you display inside. Best example is the opening of Melis CMS pages where the structure is the same, but the id of the page vary. The problem is that it would be very hard to maintain, and time consuming, to copy/paste many times the same configuration of your blocks. This is why it is possible to refer a block to another one using the type key in the conf section of every interface. Example of blocks using the type key: 'plugins' => array( 'meliscore' => array( 'meliscore_leftmenu' => array( 'meliscms_sitetree' => array( 'conf' => array( 'id' => 'id_meliscms_menu_sitetree', 'name' => 'tr_meliscms_menu_sitetree_name', 'type' => '/meliscms/interface/meliscms_sitetree', 'meliscms' => array( 'conf' => array(... 'ressources' => array(... 'datas' => array(... 'meliscms_sitetree' => array( 'conf' => array( 'id' => 'id_meliscms_menu_sitetree', 'name' => 'tr_meliscms_menu_sitetree_name', 'meliskey' => 'meliscms_sitetree', 'rightsdisplay' => 'referencesonly', 'forward' => array( 'module' => 'MelisCms', 'controller' => 'TreeSites', 'action' => 'get-tree-pages-by-page-id', 'jscallback' => 'treecallback(;', 'jsdatas' => array( Type key defined here will make the link to the block in /meliscms/interface/meliscms_sitetree When processing, the rendering engine of Melis Platform will merge the block from MelisCms into the MelisCore block. The merge will be made conserving the keys defined in MelisCore, so that overidding some keys from the MelisCms block is possible.

11 MelisModuleConfig : Arranging order of blocks / Not showing blocks Because of Melis Platform s configuration system, based on the ZF2 merging system of configuration file, it will inevitably end up into modules adding elements into menus, but not in the order that you would like. The order in which modules are loaded has a big importance because it will lead to merging elements into one order or another. Example: Config Module 1 Config Module 2 Final config with loading: Module1 Module2 'router' => array( 'routes' => array( 'route1' => array(... 'router' => array( 'routes' => array( 'route2' => array(... 'router' => array( 'routes' => array( 'route1' => array(... 'route2' => array(... Final config with loading: Module2 Module1 'router' => array( 'routes' => array( 'route2' => array(... 'route1' => array(... Technically, there is no problem with this. Functionally, it is a problem because order has a meaning. For this reason, Melis Platform comes with a configuration module called MelisModuleConfig that is foundable in the /module folder. This module contains nothing but an app.interface.php that is meant for re-organizing some parts of the blocks if needed. When the BO engine reads the configuration of interfaces, it will also look into the root key interface_ordering and interface_disable in order to reorder or not to render some blocks. Those arrays just take the keys of blocks in the specific order needed (if keys are missing compared to what s defined in the modules, they will just be added at the end. Of course, this module is not mendatory for the platform to be fuly working. Example: 'plugins' => array( 'interface_ordering' => array( 'meliscore_leftmenu' => array( 'meliscore_leftmenu_identity', 'meliscore_leftmenu_dashboard', 'meliscms_sitetree', 'meliscore_toolstree', 'meliscore_footer', 'interface_disable' => array( 'meliscore_dashboard_recent_activity',

12 Interface exclusions: deactivation of rendering of interface s blocks on a user basis The BO s engine is in fine rendering an array. It means that this array can be easily shown as a tree. This is exactly what is displayed in the user s management tool. The array is displayed (with little arrangement and the user start by default with access to everything, which means that the rendering is taking the app.interface.php normally. Upon checking some nodes, blocks which have to be excluded are saved for every user. The engine then make restrictions by comparing the limitation if the user while rendering the interface s blocks. This can be a powerful tool to make limitations of access in tools or any parts of the interface for users. In the app.interface.php, it possible to adjust the display of nodes in the user s management by using the defined keys in the conf block: - rights_checkbox_disable : true, makes the checkbox not appearing (just a node - rightsdisplay : none to skip the display, referencesonly when it has to be shown only from the type block calling it and not directly where it is defined 2.5. Melis Platform s Javascript rendering Helpers Melis Platform comes with a few helpers to help developers build their interfaces. Those helpers will help creating notifications, new tabs, new modals or to reload zones using the previously explained concept of MelisKey. This helpers are available anywhere under the javascript object melishelper ZoneReload Helper ZoneReload makes a direct call to the /melis/zoneview route. It will get back HTML and JsCallbacks. Those callbacks will be executed one after the other once the content is replaced, allowing to activate effects or other JS design related components. Prototype of helper: function zonereload(zoneid, meliskey, parameters Parameters: zoneid String The id of the block in which the generated content will be put/replaced. meliskey String The MelisKey defining the block to generate in the app.interface.php config file of the module. parameters Object Object of parameters to send along the request

13 Example of call: melishelper.zonereload('id_of_the_block', 'meliskey_of_the_block', idpage:5; In this example, the reload will occur by generating the block with meliskey meliskey_of_the_block, giving a parameter idpage equal to 5 and the content generated and received will be placed in a container with id id_of_the_block TabOpen Helper TabOpen is used to open a new main tabulation: This helper will be very useful when creating new modules that need to have their own content displayed in a full page, switchable with other content being edited at the same time. Prototype of helper: function tabopen(title, icon, zoneid, meliskey, parameters Parameters: title String Title written in the new tab icon String CSS class used for the icon displayed Predefined icon list can be found here: zoneid String The id of the block in which the generated content will be put/replaced. meliskey String The MelisKey defining the block to generate in the app.interface.php config file of the module. parameters String Object of parameters to send along the request Example of call: melishelper.tabopen('my new tab', 'fa-file-text-o', 'id_of_my_block_in_tab', 'meliskey_of_the_content', iditem: 3 ; TabClose Helper This helper closes an open tab. Prototype of helper: function tabclose(id Parameters: ID String The id of the tab as defined during creation Example of call: melishelper.tabclose('id_of_my_block_in_tab';

14 TabSwitch Helper This helper switches a tabulation from the one opened to the one asked. Prototype of helper: function tabswitch(tabid Parameters: tabid String The id of the tab as defined during creation Example of call: melishelper.tabswitch('id_of_my_block_in_tab'; CreateModal Helper This helper helps creating modals by generating one and using the meliskey system to put content in it. It is also possible to customize the modal itself by providing a different layout. Prototype of helper: function createmodal(zoneid, meliskey, hasclosebtn, parameters, modalurl, callback Parameters: zoneid String The id of the block in which the generated content will be put/replaced. meliskey String The MelisKey defining the block to generate in the app.interface.php config file of the module. hasclosebtn Boolean Whether to put a close button or not parameters Object Object of parameters to send along the request modalurl String If not provided, it will use the generic modal of Melis Platform, otherwise a URL to the layout of the modal is required callback String Callback function after generating the modal Example of call: melishelper.createmodal('id_of_my_block_in_tab', 'meliskey_of_the_content', false, iditem: 3 ; MelisOkNotification Helper This helper will pop a notification on the right top corner that lasts a few seconds. Typically used for showing results of action like Page saved : Prototype of helper: function melisoknotification(title, message, color Parameters: title String Title of the notification message String Message displayed in the notification color String Color of the notification, can be an hexadecimal code of color Example of call: melishelper.melisoknotification('saving page', 'Page has been saved', '#72af46';

15 MelisKoNotification Helper This helper will pop a notification of error that will be centered and auto-formatting the errors in a list resulting in the following modal: Prototype of helper: function meliskonotification(title, message, errors, closebybuttononly Parameters: title String Title of the notification message String Message displayed in the notification errors Array An array of errors that will be displayed. See below for array formatting. closebybuttononly String closebybuttononly => the modal will close only on button click Errors will be formatted in the following way: "errors": "page_name": "isempty":"please enter the page name", "label":"name", "page_type": "notinarray":"invalid page type selection", "isempty":"please select a page type", "label":"type", "plang_lang_id": "isempty":"please select a page language", "label":"language", "page_menu": "notinarray":"invalid page menu selection", "isempty":"please select a page menu", "label":"show Menu", "page_tpl_id": "isempty":"please select a template", "label":"template",

16 Every entry in errors corresponds to a key. Inside each key must be a key label that will make a subtitle, and a list of errors (the key of errors is not used but can reflect an error code. Multiple errors are supported. If the errors are linked to a form, then the form fields will be highlighted in red, depending if the keys sent back correspond to fields names. Example of call: melishelper.meliskonotification('title of the error', 'message of the error', errors, 'closebybuttononly';

17 3. MELIS PLATFORM S ACTION SYSTEM 3.1. Introduction Modules actions must implement an event system. Using events is the only way to allow other modules to interact with the action of another module, allowing to add more functionalities, additional savings, etc. There are different ways to achieve this goal, catching the DISPATCH event (or custom one and use sessions to communicate around an action or triggering a custom event to allow other modules to catch it and add actions before returning the datas to the main action Actions through DISPATCH or custom event and session sharing Lots of Melis CMS module actions are using this system. When an ajax call is made to post a form to a specific MVC URL, it triggers a DISPATCH event (or a custom one inside the framework. Actions are then attached to this event in order to really do the job, saving their results inside a session container that will in the end be formatted by the main function called. The main URL called is in fact not doing anything but formatting results that were treated brefore through listeners. savepageaction( Init session for subactions Trigger meliscms_page_save_start Format results using session variable Trigger meliscms_page_save_end Listener: check rights Listener: save page tree Listener: save page Properties Listener: save page SEO All listeners add their success or errors in a session variable that will be read at the end and sent back formatted. SESSION: Array( success => 1, errors => array( datas => array( ; Response

18 3.3. Actions through custom events Principle Another way to make modular actions is to directly trigger an event and to use the ZF2 prepareargs( function. See ZF2 documentation: The principle is simple, prepareargs will create an object from an array of parameters that will act as a pointer would be in C. Triggering an event with this object as a parameter then allow the listeners to modify them and the modification will be available for any other listener that would activate after. In the end, you can also retrieve your modified parameters in your main function just after the trigger call. This has many advantages with the most important ones being: - It is possible to raise a lot of events that will modify the datas transmitted - Additional modules can modify the datas in order to add more functionalities, computation or any business logic Example of a sendevent method that can be defined in an abstract or generic controller class: public function sendevent($eventname, $parameters $parameters = $this->eventmanager->prepareargs($parameters; $this->eventmanager->trigger($eventname, $this, $parameters; $parameters = get_object_vars($parameters; return $parameters; Example of call: $arrayparameters = array('variable1' => 'test', 'variable2' => 'test2'; $arrayparameters = $this->sendevent('mymodule_myevent', $arrayparameters; In this example, $arrayparameters is initialized, then passed along to the sendevent function. SendEvent function will prepare the parameters, meaning that any listener can modify the variables variable1 or variable2. Printing those variables after the sendevent function would show the modifications Advanced example One interesting point would be to trigger an event at the start and the end of any function or service, so that the parameters given, and the result sent back could be changed by another module listening to that event. Example: public function myservice($param1, $param2 $arrayparameters = array('param1' => $param1, 'param2' => $param2; $arrayparameters = $this->sendevent('mymodule_myevent_start', $arrayparameters; // Implement business logic here // Store result $arrayparameters['results'] = true; $arrayparameters = $this->sendevent('mymodule_myevent_end', $arrayparameters; return $arrayparameters['results'];

19 In this example, the parameters given to the service are then sent in parameters along the first event. So any listener can do changes in the parameters in order to apply pre computation for example. Likewise, the result is added to te parameters so that any listener can operate some post computation before it is sent back. Of course, in between, the regular business logic is implemented and even more events can be triggered on the same system. One last improvement that can be made is the automatic transformation of the function s parameters into an array where the keys are the function s parameters names and the values are the ones passed to the function. This can be done by using the Reflection object: public function makearrayfromparameters($class_method, $parametervalues if (empty($class_method return array(; // Get the class name and the method name list($classname, $methodname = explode('::', $class_method; if (empty($classname empty($methodname return array(; /** * Build an array from the parameters * Parameters' name will become keys * Values will be parameters' values or default values */ $parametersarray = array(; try // Gets the data of class/method from Reflection object $reflectionmethod = new \ReflectionMethod($className, $methodname; $parameters = $reflectionmethod->getparameters(; // Loop on parameters foreach ($parameters as $keyparameter => $parameter // Check if we have a value given if (!empty($parametervalues[$keyparameter] $parametersarray[$parameter->getname(] = $parametervalues[$keyparameter]; else // No value given, check if parameter has an optional value if ($parameter->isoptional( $parametersarray[$parameter->getname(] = $parameter->getdefaultvalue(; else // Else $parametersarray[$parameter->getname(] = null; catch (\Exception $e // Class or method were not found return array(; return $parametersarray; Update of the previous example: public function myservice($param1, $param2 $arrayparameters = $this->makearrayfromparameters( METHOD, func_get_args(; $arrayparameters = $this->sendevent('mymodule_myevent_start', $arrayparameters; // Implement business logic here // Store result $arrayparameters['results'] = true; $arrayparameters = $this->sendevent('mymodule_myevent_end', $arrayparameters;