* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * JivaCore New Module * * * * I. Create a new module in https://gitlab.jivaveda.com/jivacore/modules and clone to local work * * environment * * * * II. Create Parant Module Permission in databse * * * * III. Create _lang folder with menu translation * * * * IV. Create subModule folder and subsequent appOptions.js, moduleApp.js, mainPage.html and toolBar.html * * files inside. * * * * V. Create permission for Page * * * * VI. Create the _install folder and subsequent dispatch.php file * * * * VII. Create the _routes folder and relative functionName.php files associated to the endpoints in the * * dispatch.php files in step [VI.] * * * * VIII. Create the table.json in the _lang folder * * * * IX. Create the Section Permission and it's Execution and Button sub-Permission * * * * X. Create the buttons.json file and Add the 'Save', 'Edit' and 'Delete' button permissions * * * * XI. Create the module_edit_form in the database 'core_assests' table * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * ------------------------------------------------------------------------------------------------------------ Create a New Module [I.] Go to https://gitlab.jivaveda.com/jivacore/modules and create a new module by clicking 'New Project'. Once the module has been created, click on the new module then click 'clone with SSH'. Open the terminal and navigate to your JivaCore/modules/ directory and give the command 'git clone' + cloned_URL. The module folder should now appear in your local work environment. [II.] Create a new module bank in the 'core_permissions' table in the database. See Parant Module Permission in the JivaCore Permissions Section below! Once complete, save and reload the JivaCore web app. "NULL" should now be visible in the web app menu. [III.] Create the '_lang' folder in the your Parant Module folder created in step [I.]. Inside the '_lang' folder create the provided language folders ex. en-EN || it-IT. Inside each language folder create the menu.json file, setting the "key" to the module's name given as the 'permission_name' column in step [II.]. Set the a string "value" according to the language of translation. [IV.] Create the subModule folder in the Parant Module folder and create the following files inside: - appOptions.js - moduleApp.js - mainPage.html - toolBar.html * These files can be copied from different modules but variables must be changed according to the name given to the Parant Module, hence html element ids (such as sections, buttons and inputs) and endpoints in the appOptions.js must all be modified! The mainPage.html contains the two sections (View and Edit section). The sections should be called as the following example: ex.1 - moduleName_subModule_list_view ex.2 - moduleName_subModule_list_edit In each section the JivaCore app will append the appropriate toolbar (created in the toolBar.html file) in each section. The toolbar sections in the toolBar.html file should be called as the following example: ex.1 - moduleName_subModule_list_view_toolbar ex.2 - moduleName_subModule_list_edit_toolbar The buttons in the toolBar.html file are generally associated to the functions in the table below. These functions may be found in the sub_module/moduleApp.js file. |----------------|------------------| | Buttons | Function | |----------------|------------------| | Add Button | objectAdd() | | | | | Edit Button | objectEdit() | | | | | Delete Button | objectDelete() | | | | | Save Button | objectSave() | | | | | Back Button | getObjects() | |-----------------------------------| [V.] Create a Page Permission (see 'Page Permission' in the JivaCore Permission's Section below). [VI.] In the Parant Module folder, create an '_install' folder. Inside, create the dispatch.php file. Set the "method" (ex. 'GET', 'PUT', 'POST' and 'DELETE'), "endpoint" (ex. /api/v1/module/subModule/:id) and relative back-end php "functionName" to be called. These "endpoints" will also have to be set in the appOptions.js file created in step [IV.] under each endpoint "key". [VII.] Create the '_routes' folder in the Parant Module folder. Inside create all the functionName.php files associated to the endpoints created in step [VI.] ex. getSubModule.php || updSubModule.php || delSubModule.php || addSubModule.php Each time an endpoint will be called from appOptions.endpoint, the appropriate back-end php function will be triggered. These php functions contain the database queries, therefore reference to the correct table used in the module must be set in the query. [VIII.] * Create the table.json file in the _lang/language/ folder created in step [III.]. Set the "keys" to the appOptions.objectsTableColumns translate values, ex. table_module_subModule_columnName. Set the "values" to the according column translation string. This will translate the field values of the table in the database and reconstruct the appropriate table in the Module's View Section. [IX.] Create the View Section Permission (see Section Permission in the JivaCore Permissions section below). Create the subsequent Execution Permissions (see also JivaCore Permissions below). Save all files and reload the JivaCore web app. You should now have a module and a subModule page in the menu and returned data table in the view section of the page. * Repeat this step for the Edit Section Permission and its subsequent Execute and Button Permissions. Under the View Section the following permissions should be set: - Add Button - Edit Button - Delete Button - Get Execute () Under the Edit Section the following permissions should be set: - Save Button - Back Button - Save Execute - Update Execute - Add Execute For all Execution Permissions, the 'Function' field should be set to a back-end functionName.php file defined in the _routes folder created in step [VII.] [X.] After having created the toolBar.html file in step [IV.] with each button defined in its relative section, create a buttons.json file in the _lang/languages folder. Set the "keys" as the button's html id, defined in the toolBar.html file. Set the "values" according to the appropriate language translation. Once the button has been defined and its translation set in the json file, proceed by creating its relative permission. See Button Permission in the JivaCore Permissions Section below. See also step [IX.] for a reference to button permissions under each section. Here is a brief description on button functionality: - Add Button: The "Add" button in the toolBar.html file should have an 'onclick' attribute set to "objectAdd()" function. This activates the "Edit Section" (created in step [IX.]) from the mainPage.html file. This Button id must always be added to the appOptions.enabledButton object and condition set to determine its enabled status. The condition for an add button to be set is as follows: "rows >= 0" This condition will always have the button enabled. - Edit Button: The "Edit" button in the toolBar.html file should have an 'onclick' attribute set to "objectEdit()" function. This button also activates the "Edit Section" though it calls a different save method. This Button id must always be added to the appOptions.enabledButton object and condition set to determine its enabled status. The condition for an edit button to be set is as follows: "rows == 1" This will enable the button only if one selectable data type is selected. - Delete Button The "Delete" button in the toolBar.html file should have an 'onclick' attribute set to "objectDelete()" function. This deletes selected data from the table. This Button id must always be added to the appOptions.enabledButton object and condition set to determine its enabled status. The condition for a delete button to be set is as follows: "rows >= 1" This will enable the button only if one or more selectable data types are selected. * These three buttons are usually visible in the View Section of the Page, hence are defined in the toolBar.html's View Toolbar. - Save Button The "Save" button in the toolBar.html file should have an 'onclick' attribute set to "objectSave()" function. This saves selected data from the table. There is no need to set this button in the appOptions.enabledButton object. - Back Button The "Back" button in the toolBar.html file should have an 'onclick' attribute set to "getObjects()" function. This will simply reload the View Section. There is no need to set this button in the appOptions.enabledButton object. * These two buttons are usually visible in the Edit Section of the Page, hence are defined in the toolBar.html's Edit Toolbar. [XI.] Create the module_subModule_form in the 'core_assets' table in the database. Create a new form by setting the 'asset_type' field to "form". In the 'asset_name' set the name of the form ex. module_subModule_form. This form 'asset_name' will also have to be set in the appOptions.objectsForm. Set a description in the 'description" field and the html code in the 'asset_innerHtml' field. Create a form.json in the _lang/language folder and set the "keys" to the form's label element's innerHtml refernce, created in the 'asset_innerHtml' field. Set the "values" according to the language translation to be viewed above the form's Input Fields. * The form's input element 'name' attribute should be set as the field "values" in appOptions.objectsTableColumns. These fields should be exactly the same as the columns in the database table. This form will be visible when activating the "Edit Section" of the Page. A permission will need to be created to access the "Edit Section" if it has not yet been done. See Step [IX.] END ******************************************************************************************************************* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * JivaCore Permissions * * * * JivaCore Permissions are used to grant access to modules, pages, sections, buttons and executions depending * * on the logged-in user. One user might have access to view a specific button while another might not. * * Permissions are added in the settings -> permissions section of the JivaCore web app. Simply click on the * * module tab under which you would like to add a permisison and then click Add. To create the access/viewing * * permission for a new Parant Module Permission, see Parant Module Permisison below. * * * * * * * ** * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * Parant Module Permission - Is the Permission for the first module created where the subsequent Child Modules will be appended to. This permission will need to be added directly from the database table 'core_permissions'. To create a new Parant Module Permission: 1) Go into the databse and open the 'core_permissions' table. Add a new row, thereby creating a new permission. In the 'Code' column, create a new unique code using 'M' for module, follwed by another six letters indicating your modules name. ex. MMODNAM. (for Module Name) 2) Insert a unique name in the 'permission_name' column ex. moduleName, set the 'parant' column to 'null'. The 'permission_namespace' and the 'module' column should both have the same name as the 'permission_name'. Add a description in the 'description' column and set the 'permisison_type' to "MOD" for module. Finally set an icon in the 'icon' column for a visual representaion of this module. Click 'Save'! * The same 'permission_name' should also be set in the module/_lang/language/menu.json file as an object "key". Set a string "value" to this "key" for translation to appear in the menu of the web app. We have now created a permission for a new Parant Module. Log out of the JivaCore web app and reload, login and navigate to the settings -> permission section. A new tab with the module's name should now be visible. * To create a child module, click on the Parante Module Permission's tab and click "Add". Page Permission - The Page Permissions is a child of a Parant Module and grants viewing access to a page in a module. It generally will be added by the settings -> permissons section in the web app. Click the Parant Module tab under which you wish to create a Page Permission and click "Add". . 1) Insert a unique code in the 'code' field using 'P' for "page" as the first letter, followed by another six letters identifying your page name. ex. PNAMPAG (for Name Page) 2) Set a unique name in the 'name_authorisation' field ex. module_name_page. This unique name will also be set in the module/_lang/language/menu.json file as a "key" and a string "value" associated to it for translation in the JivaCore web app's menu. 3) Set the 'module' field to the Parant Module this page is being appended to. 4) Set the 'function' field to "getObjects". This calls the function called 'getObjects()' in the module/submodule/moduleApp.js file, which activates the page for which this permission is being created. * leave the 'child default' as "child_default". 5) Since this is a page, set the 'Type of Autherisation' field to "Page", give a brief description of this permission in the 'Description' field and set an icon in the 'Icon' field. 6) Set the 'Namespace' to the url called, usually set by seperating parants and child modules by a "/". ex. module/child/page. We can now proceed by creating a Section Permission which will give permission to view a section in this page. Section Permission - The Section Permission is a child of a Page Permission and is used to grant access to html content defined in the module/sub_module/mainPage.html file. Generally there are two main sections in any given module: - View Section - Edit Section Each section will require its corresponding permission. Navigate to the page permission created above and click 'Add'. To create any of the Section Permission for the sections mentioned above: 1) Insert a unique code in the 'code' field using 'S' for "section" as the first letter, followed by another six letters identifying your section name. ex. SNAMSEC (for Name Section) 2) Set the 'Type of Autherisation' field to "Section" and add a description in the 'Description' field. Set the same 'Namespace' as the Page Permission's 'Namespace'. 3) Set a unique name in the 'name_authorisation' field ex. module_name_section. This unique name will be exactly the same as the section element's id in the module/sub_module/mainPage.html file and will also have to be set in the sub_module/appOptions.js file under the 'objectsViewPage' or 'objectsEditPage' "values". * The function field will be left blank in a Section Permission We can now proceed by creating a Execute Permission which will give permission to execute a php function Execute Permission - This permission is added under the Section Permission and is used to give access to execute back-end php query functions which manipulate database data. These execution permissions are generally used to 'GET', 'PUT', 'POST' or 'DELETE' data from database tables. Navigate to the section under which you wish to add an Execute Permission and click "Add". To create an Execute Permission: 1) Insert a unique code in the 'Code' field using 'X' for "execute" as the first letter, followed by another six letters identifying your execution method. ex XSECGET (for SECTION GET) Set the 'Type of Autherisation' to "Execute". 2) Set the 'Name_authorisation' field, possibly describing the module, child and function. ex. module_child_section_get Set the same 'Namespace' as the Parant Page and Section Permission. 3) Set the php function to be called in the 'Function' field and a brief description in the 'Description' field. * The php function will be called from the module_name/_routes/functionName.php file. This function will also have to be set in the module_name/_install/dispatch.php file associated with its relative enpoint and method (ex. 'GET', 'PUT', 'POST' or 'DELETE'). Button Permission - This permission is also added under the Section Permission and grants access to view and use a button defined in the module/sub_module/toolBar.html file. Navigate to the section under which you wish to add an Button Permission and click "Add". To create a Button Permission: 1) Insert a unique code in the 'Code' field using 'B' for "button" as the first letter, followed by another six letters identifying your button function. ex BROWADD (for ROW ADD ) 2) Set a unique name in the 'name_authorisation' field ex. module_section_add_button. This unique name will be exactly the same as the section button's id in the module_name/sub_module/toolBar.html file and will also have to be set in the module/_lang/language/button.json file as an object "key". Set a string "value" to this "key" for translation to appear in the button. 3) Add an icon in the 'Icon' field and a description in the 'Description' field. Set the same 'Namespace' as the Parant Page and Section Permission. * The function field will generally be left blank since the function associated to the button elements are defined in thier 'onclick' attribute. All Sections, Execute and Button Permission will all have the same 'Namespace' as the Parant Page Permission. ex. moduleName/child/page END ***************************************************************************************************************