Difference between revisions of "Module ModuleBuilder"

Latest revision as of 17:46, 7 May 2024

Foundations
Numero/ID of module	3300
User doc. of module	This page
Developer doc. of module

Introduction

The ModuleBuilder is a module for developpers only, to help you to develop a module. It is RAD, No Code or Low Code tool.

Installation

This module is included with the Dolibarr distribution, so there is no need to install it.

Configuration

To use this module, you must first enable it using an administrator account, via the menu option "Home - Setup - Modules".

Choose the tab where the module is listed. Then click on "Activate".

The module is now activated.

If a cog icon appears on module thumb or at end of the line of the module, click on it to access the setup page specific to the module.

Usage

The ModuleBuilder within Dolibarr presents a lot of features designed for the comprehensive management and development of module.

Creating a new module

Click on the "Bug" picto on top right in the menu bar to reach the ModuleBuilder tool.

First, create a new module by clicking on the link "New module".

Choose a name and some options. First files to have a working module will be generated. You can already enable and disable your module from the common page to enabled/disable module of Dolibarr. However, it is recommended to work on the other steps of development of your module, with the module not enabled.

Work on your new module

Language Support

This function allows developers to introduce additional languages into a module, enhancing its accessibility and usability across different linguistic demographics.
It involves integrating new language files or entries that translate the module's interface and messages.

Menus

Enables the crafting of custom menus within the module's UI, allowing users to navigate through the module's features more efficiently. This might include adding new menu items linked to specific functionalities or adjusting the module's navigation structure.

Creating menus in the system is achieved through two distinct methods: Initially, when an object is created, three menus are automatically generated and displayed on the left sidebar. Alternatively, menus and sub-menus can be manually added by utilizing the form at the top of the table, which requires filling in specific fields such as title, URL, and position. Furthermore, permissions can be assigned to each menu to ensure they are only visible to users with the appropriate rights.
The editing process mirrors this approach closely.
For deletion, one needs to click on the trash can icon and confirm to proceed with the removal.

Object

To add an object, simply enter the name, choose an icon, and specify the name of an existing table, if nothing is specified, it creates a new table.
The three check-boxes depend on your preference: one for enabling automatic numbering generation, the second for enabling PDF document creation, and the third to generate permissions for the object created.

Add Object

In the description of an object within a Dolibarr module developed using ModuleBuilder, several essential components and functionalities are outlined. These include :

PHP DAO CRUD Class: This is the core PHP class that handles database operations such as create, read, update, and delete for the object, ensuring seamless data management.
Icon Representation: An icon specified for visual representation of the object in the user interface, aiding in quick identification.
Module API: Defines the application programming interface for the module, enabling external interactions and integrations.(one file contain CRUD methods for each object created).
Unit Testing: A set of PHP unit tests designed to verify the functionality and reliability of the object, ensuring robust operation.
Library Files: Comprise both a common library file for module-wide functions and an object-specific library file, which includes functions unique to the object's logic and operations.
SQL Scripts: Include the main SQL script for creating the object's database table, along with additional scripts for keys, indexes, and extra fields, ensuring optimized database structure and performance.
User Interface Pages:
- A listing page for viewing all records of the object,
- A detailed card page for creating, modifying, and displaying individual records,
- Dedicated pages for managing related contacts, documents, notes, and events, each providing specialized functionalities within the object's context.

The setup also features a button, facilitating the generation, modification, or deletion of these components as needed. This system offers a comprehensive framework for extending and customizing the object within the module, providing developers with a robust set of tools for module customization and functionality enhancement.

Property Addition:

This feature permits the extension of entities or modules by adding new properties. These properties can be utilized to store additional information, customize behavior, or integrate with other modules, enhancing the module's flexibility and capability.

To add an additional attribute to a specific object, simply click on the "+" button to the right of the properties list, which will display a form allowing you to fill in fields such as label, type, code, etc.
To modify, simply click on the pencil icon that appears in the same row of the list, which brings up a form for editing.
For deletion, the trash can icon allows for the removal of a property after confirmation.

Permissions

For permissions, there are two ways to create them:

By ticking the box at the bottom of the form during the creation of the object and it creating the 3 default permissions (create, write, delete).
By manually creating them in the rights section, which provides a list of permissions for each object. The form at the top of the table allows you to select the object and choose a permission; the ID is automatically assigned, as well as the label, although you have the option to change it if desired.

Dictionaries

To create a dictionary, there is a dedicated section for this purpose. A create button (+) on the right displays a form to enter the name of the dictionary, which will become the name of the table in the database, preceded by "c_".

The other fields are automatically filled in, and it is recommended to leave them as they are. For editing, you have the option to change the label, the fields for sorting, and for inserting or editing.

Add dictionary

Hooks

Define in the module_parts['hooks'] property within the module descriptor the contexts in which the hooks should be executed (the list of contexts can be found by searching for 'initHooks(' in the core code). Then, edit the hook file to add the code for your hooked functions (hookable functions can be found by searching for 'executeHooks' in the core code).
Click the "+" button to generate the hooks code.

Triggers

In a module, the triggers part of the module_parts array indicates whether the module includes its own directory for triggers within Dolibarr's core triggers system, To generate the trigger file, simply use the "+" button provided by the ModuleBuilder interface in triggers section .

CSS / JS / CLI

CSS : Once generated, you can use the file to define custom styles that will be applied to the module's frontend, improving its appearance and user experience. You can specify styles for layout, colors, fonts, and more, ensuring your module aligns with the desired aesthetic and usability standards.

JavaScript (JS) : After generating a JS file, you can write scripts to handle user interactions, perform validations, manipulate DOM elements.

The Command Line Interface (CLI) file plays a crucial role in facilitating module interaction via the command line, allowing for the execution of scripts, or functions without a graphical interface. This is particularly useful for automating processes.

By utilizing the ModuleBuilder to generate these files, you simplify the initial setup process for incorporating CSS, JS, and CLI functionalities into your module. Each file serves a distinct purpose, contributing to the module's visual design, interactivity, and operational flexibility, ultimately enhancing its overall utility and integration within the Dolibarr ecosystem.

All these configurations was added in modYourModuleName.class.php file in folder htdocs/custom/YourModuleName/core/modules and you can edit it if you want but you should be careful when you manipulate this file specially with comments.

@@ Line 1: / Line 1: @@
-{{Template用户手册}} {{Template开发文档}} {{TemplateMainPageZh}}<br />
+<!-- BEGIN interlang links -->
-=Activation of ModuleBuilder=
+<!-- Do NOT edit this section
-从Dolibarr 10.0.0 开始，可以使用ModuleBuilder创建模块，为激活ModuleBuilder，按以下步骤：
+     Links below are automatically managed by PolyglotBot
+     You can edit links on the English source page : ModuleBuilder用户手册 -->
+[[zh:ModuleBuilder用户手册]]
+<!-- END interlang links -->
-*在'''主页-设置-模块'''中激活 ModuleBuilder.
+[[Category:Core]]
+{{TemplateDocUser}}
+{{TemplateModEN}}
+{{BasculeDevUserEn|
+name=Foundations|
+num=3300|
+devdoc=|
+userdoc=This page|}}
-[[File:激活modulebuilder.png|800px]]
+=Introduction=
+The ModuleBuilder is a module for developpers only, to help you to develop a module.
+It is RAD, No Code or Low Code tool.
-*点击右上角的‘Bug’图标开始使用（或者在浏览器中输入'yourhost/modulebuilder'）
+=Installation=
+{{NoInstallModuleEn}}
-[[File:Buglogo.png]]
+=Configuration=
+{{ActivationModuleEn}}
-*运行的ModuleBuilder界面如下：
+=Usage=
+The ModuleBuilder within Dolibarr presents a lot of features designed for the comprehensive management and development of module.
-[[File:Modulebuilder.png|800px]]
+==Creating a new module==
-=使用ModuleBuilder创建主模块文件=
+Click on the "Bug" picto on top right in the menu bar to reach the ModuleBuilder tool.
-在下图‘模块名’处填入模块名，然后点击右侧的‘创建’按键，完成创建模块主文件。
-*改变模块ID值： $this->numero = 100000（将此100000变更为你为模块设置的ID值）。为了避免与其他模块发生冲突，您可以查阅列出已保留ID号的页面： [[List of modules id|List of modules id]].
+First, create a new module by clicking on the link "New module".
-*修改构造函数中定义的其他变量 (参考[[主模块代码框架]]中的注释内容).
-*您的模块主文件已准备就绪。
-[[file:模块名.png|800px]]
+Choose a name and some options.
-=使用ModuleBuilder生成PHP DAO类文件=
+First files to have a working module will be generated. You can already enable and disable your module from the common page to enabled/disable module of Dolibarr. However, it is recommended to work on the other steps of development of your module, with the module not enabled.
-*使用ModuleBuilder生成PHP DAO类文件，简单至在下图中选对'对象'选项卡，输入'对象名'，然后点击创建，即可生成相关一切文档。
+==Work on your new module==
-[[File:新对象.png|800px]]
+===Language Support===
-*创建完成后，仍可继续创建受模块管理的其他“对象”
+*This function allows developers to introduce additional languages into a module, enhancing its accessibility and usability across different linguistic demographics.
-*“对象”选顶卡的界面如下：
+*It involves integrating new language files or entries that translate the module's interface and messages.
-[[file:myObject.png|800px]]
+<br />
+[[File:AddLanguage.png|center|thumb|1446x1446px]]
+<br />
-如图所示，ModuleBuilder自动帮我们建好了以下文件：
+===Menus===
- * PHP DAO CRUD类的文件 : '''mymodule/class/myobject.class.php '''
+Enables the crafting of custom menus within the module's UI, allowing users to navigate through the module's features more efficiently. This might include adding new menu items linked to specific functionalities or adjusting the module's navigation structure.
- * PHP API类的文件 : '''mymodule/class/api_mymodule.class.php'''
- * PHP单元测试类的文件 : '''mymodule/test/phpunit/MyObjectTest.php'''
- * PHP库的文件 : '''mymodule/lib/myobject.lib.php'''
+*Creating menus in the system is achieved through two distinct methods: Initially, when an object is created, three menus are automatically generated and displayed on the left sidebar. Alternatively, menus and sub-menus can be manually added by utilizing the form at the top of the table, which requires filling in specific fields such as title, URL, and position. Furthermore, permissions can be assigned to each menu to ensure they are only visible to users with the appropriate rights.
- * Image : '''mymodule/img/object_myobject.png'''
+*The editing process mirrors this approach closely.
+*For deletion, one needs to click on the trash can icon and confirm to proceed with the removal.
- * Sql文件 : '''mymodule/sql/llx_mymodule_myobject.sql'''
+<br />
- * Sql文件用于附加字段 : '''mymodule/sql/llx_mymodule_myobject_extrafields.sql '''
+[[File:Menus.png|center|frameless|1482x1482px]]
- * Sql文件（创建索引） : '''mymodule/sql/llx_mymodule_myobject.key.sql'''
- * 用于显示记录列表的PHP页面 : '''mymodule/myobject_list.php'''
+===Object===
- * 用于创建/编辑/查看记录的PHP页面 : '''mymodule/myobject_card.php?action=create（mymodule/myobject_card.php）'''
- * 事件选项卡的PHP页面 : '''mymodule/myobject_agenda.php '''
- * 文档选项卡的PHP页面 : '''mymodule/myobject_document.php '''
- * 注释选项卡的PHP页面 : '''mymodule/myobject_note.php'''
- * ScriptFile : '''mymodule/scripts/myobject.php '''
+*To add an object, simply enter the name, choose an icon, and specify the name of an existing table, if nothing is specified, it creates a new table.
-点击每一条右侧的图标，即可以MB中编辑该文件，按下方保存按键保存。
+*The three check-boxes depend on your preference: one for enabling automatic numbering generation, the second for enabling PDF document creation, and the third to generate permissions for the object created.
-另有“重新生成类文件和SQL文件”“生成丢失文件”两按键可以使用。
+<br />
+[[File:AddObject.png|center|thumb|1301x1301px|'''Add Object''']]
-“对象”选项卡的最下方，就是对象包含的字段。每行一个字段，可以增加名删除字段。
-[[File:MBobject字段.png|800px]]
+In the description of an object within a Dolibarr module developed using ModuleBuilder, several essential components and functionalities are outlined. These include :
-=为模块添加语言文件=
-打开ModuleBuilder，选中模块。
-选中"语言"，在语言框中选择"zh_CN － 中文"，然后点击添加语言文件。 如图： [[File:创建语言文件.png]]
+*'''PHP DAO CRUD Class''': This is the core PHP class that handles database operations such as create, read, update, and delete for the object, ensuring seamless data management.
+*'''Icon Representation''': An icon specified for visual representation of the object in the user interface, aiding in quick identification.
+*'''Module API''': Defines the application programming interface for the module, enabling external interactions and integrations.(one file contain CRUD methods for each object created).
+*'''Unit Testing''': A set of PHP unit tests designed to verify the functionality and reliability of the object, ensuring robust operation.
+*'''Library Files''': Comprise both a common library file for module-wide functions and an object-specific library file, which includes functions unique to the object's logic and operations.
+*'''SQL Scripts''': Include the main SQL script for creating the object's database table, along with additional scripts for keys, indexes, and extra fields, ensuring optimized database structure and performance.
+*'''User Interface Pages''':
+**A listing page for viewing all records of the object,
+**A detailed card page for creating, modifying, and displaying individual records,
+**Dedicated pages for managing related contacts, documents, notes, and events, each providing specialized functionalities within the object's context.
+'''The setup also features a button, facilitating the generation, modification, or deletion of these components as needed. This system offers a comprehensive framework for extending and customizing the object within the module, providing developers with a robust set of tools for module customization and functionality enhancement.'''
+<br />
+<br />
+[[File:DolObject.png|center|thumb|1408x1408px]]
+<br />
+==='''Property Addition''':===
+This feature permits the extension of entities or modules by adding new properties. These properties can be utilized to store additional information, customize behavior, or integrate with other modules, enhancing the module's flexibility and capability.
+*To add an additional attribute to a specific object, simply click on the "+" button to the right of the properties list, which will display a form allowing you to fill in fields such as label, type, code, etc.
+*To modify, simply click on the pencil icon that appears in the same row of the list, which brings up a form for editing.
+*For deletion, the trash can icon allows for the removal of a property after confirmation.
+<br />
+[[File:PropertiesObject.png|center|thumb|1402x1402px]]
+<br />
+[[File:AddProperties.png|border|center|thumb|1413x1413px]]
+<br />
+===Permissions===
+For permissions, there are two ways to create them:
+*By ticking the box at the bottom of the form during the creation of the object and it creating the 3 default permissions (create, write, delete).
+*By manually creating them in the rights section, which provides a list of permissions for each object. The form at the top of the table allows you to select the object and choose a permission; the ID is automatically assigned, as well as the label, although you have the option to change it if desired.
+<br />[[File:PermissionsList.png|center|thumb|1463x1463px]]
+<br />
+===Dictionaries===
+*To create a dictionary, there is a dedicated section for this purpose. A create button (+) on the right displays a form to enter the name of the dictionary, which will become the name of the table in the database, preceded by "c_".
+*The other fields are automatically filled in, and it is recommended to leave them as they are. For editing, you have the option to change the label, the fields for sorting, and for inserting or editing.
+<br />
+[[File:ListDict.png|center|thumb|1477x1477px]]
+[[File:AddDictionnaire.png|center|thumb|1485x1485px|Add dictionary ]]
+===Hooks===
+*Define in the <code>module_parts['hooks']</code> property within the module descriptor the contexts in which the hooks should be executed (the list of contexts can be found by searching for 'initHooks(' in the core code). Then, edit the hook file to add the code for your hooked functions (hookable functions can be found by searching for 'executeHooks' in the core code).
+*Click the "+" button to generate the hooks code.
+===Triggers===
+*In a module, the <code>triggers</code> part of the <code>module_parts</code> array indicates whether the module includes its own directory for triggers within Dolibarr's core triggers system, To generate the trigger file, simply use the "+" button provided by the ModuleBuilder interface in triggers section .
+===CSS / JS / CLI===
+*'''CSS''' :  Once generated, you can use the file to define custom styles that will be applied to the module's frontend, improving its appearance and user experience. You can specify styles for layout, colors, fonts, and more, ensuring your module aligns with the desired aesthetic and usability standards.
+*'''JavaScript (JS)''' : After generating a JS file, you can write scripts to handle user interactions, perform validations, manipulate DOM elements.
+*The '''Command Line Interface (CLI)''' file plays a crucial role in facilitating module interaction via the command line, allowing for the execution of scripts, or functions without a graphical interface. This is particularly useful for automating processes.
+By utilizing the ModuleBuilder to generate these files, you simplify the initial setup process for incorporating CSS, JS, and CLI functionalities into your module. Each file serves a distinct purpose, contributing to the module's visual design, interactivity, and operational flexibility, ultimately enhancing its overall utility and integration within the Dolibarr ecosystem.
+All these configurations was added in '''modYourModuleName.class.php''' file in folder '''htdocs/custom/YourModuleName/core/modules'''  and you can edit it if you want but you should be careful when you manipulate this file '''specially with comments'''.