In our foundations we use modules to split our interface logic, where modules are simply a folder containing a module.cfg file. Upon rendering an Intranet or Extranet site following a login, the system will scan the local folder hierarchies and compile the basics of the main menu, while evaluating the different ACL rules to render each module and sub modules.
The scanning is recursive, so its useful to keep the tree structure in mind when defining your own ACLs.
We've slowly biased the module construction for the past 2 years towards providing a completely portable module methodology, our goal is to provide the means to include language files, templates, database scripts and user interfaces under the same module hierarchy so as to make portability a matter of copy&paste.
Alas, there remains one minor detail with our engine which makes module portability limited to the same hierarchical levels. A change in level within the hierarchy usually incurs a slight source code change to account for the binding to the configuration files which is done relatively instead of absolutely. (It would be a minor change to make it absolute really, but doesn't help with programmer-introduced links between different modules, for which, the hierarchical level does matter enormously.). So, rather than seeing this as a blockage, we prefer to consider it as a judicious constraint, because as developers get involved in the system, we don't want to see changing hierarchies, we want to limit hierarchical levels for security reasons as well.
Important note: Modules are defined from a file-system perspective, but our engine also includes the notion of "data-driven" modules. Both can be used jointly (albeit not on the same module!) and intermixed. We recommend reading up on the data-driven modularity concepts for more information.
First off, they're .ini style configurations. Which means they can be [sectioned] in order to modularize settings across different modules and rendering frameworks.
Blank lines and lines starting with // (double forward slashes) are simply ignored when parsed.
In the following example, we can make out the default section (the first entries without a [header]), and a [specs] section:
id=Users
entrypoint=Users_List.php
icon=fa-user
name.en=Users
name.fr=Usagers
name.es=Usuarios
[specs]
dependson=m:Groups,l:Groups - System-wide,l:User.OrganizationTypes,l:User.Access_Level,l:User.Type,l:UserStatus
if_allow=Intranet,Extranet
lang_file=Users
authorid=selt.kopel
As the default section, these parameters only need to be listed before any other section is started. They should always reside at the top of the module.cfg file.
| id | mandatory, string, max 80chars | the unique identification/name for this module. This should be unique in the Universe as we know it if possible. |
| entrypoint | string, mandatory, max 200 chars | the default index page to present in the module when accessed through the Administrative or Extranet module menu. |
| icon | string, optional, max 64 chars | a reference to a FontAwesome or UI icon. Currently we support the FontAwesome 4 shortened annotation ("fa-icon"), and the FontAwesome 5 long annotation ("fab fab-brandname" for example) |
| name.langcode | string, max 120 chars, you should always provide one for your default language ("en" by default) | Display name to be rendered in the UI, you should detail as many languages as you possibly can, given that your module might be running in languages outside of your original conceptual realm. Good practice to make sure all your supported languages are defined, although the system *should* fallback to English when in doubt, or the ID itself. |
| default_lv2_module | optional, string, max 80chars | ID of a sub-module which should be used as the "default" entrypoint in the hierarchy. Useful if your root module has a sub-module serving as an entrance point, like for example the Backend module which points to the User_List.php page in the Backend/User module. |
| dependency | optional, string, max 80chars | NOT USED, the only supported value currently is "top", referring to a top-level module in the menu hierarchy. |
| type | optional, string, max 80chars | defaults to "empty", this field has been deprecated a while ago. (You might still encounter it, but its not used right now.) |
| priority | integer, values between 0 and 100 | not used anymore, was used to provide a presentation order, but we've made do with this feature by allowing sorting in the UI in a wysiwyg fashion. |
| access_level | comma-separated list of access levels | List the allowed access levels, this will limit the menu generation making the items available only for those users with one of the appropriate access levels. Permissible access levels in the system are user, manager & admin. This list should not be quoted. |
| dashboard_card | filename (max 120 chars) | this should point to a file that we can use in the welcome dashboard to present a summary of activities for dashboard purposes. It might be that some modules don't have one, so this setting is entirely optional. New from May 2019. |
New as of 2019, the specs section is meant to impart some packaging logic to modules so we can migrate modules between systems and apps more easily. As of January 2020, these parameters are entirely optional and not used in the framework itself. It's meant to be a developer hook for sharing modules mostly.
Section name : [specs]
| lang_file | string, 80chars | "Object name" of a language file that should be associated with the string elements of this module. Typically if your language file is used under the framework, as per the framework rule, it should be located under APP_ROOT/APPLICATION_LISTS/Language.ListObjectName.txt | |
| if_allow | string | List of Interfaces where this module is allowed, typically a comma-separated list of 2 possible values: Intranet, Extranet. Without quotes. (Its very very rare to have a module that can span both Interfaces, but a good example is the bundled File Manager and Backend/User modules which are specially programmed to allow this behavior, securely) | |
| dependson | comma-separated list of dependency declarations |
This is a prototype feature meant to instruct the installer mechanism of dependencies on different Framework objects such as: Groups, Modules, DB Table Objects, Lists and Language files. Format for the dependency specifications are as follows:
|
|
| authorid | a user.system ID | A universal ID (which should be meaningful to the deployment and the Universe of deployments.) We don't recommend putting an email in there, but a user.EnterpriseName which could be registered on our official supporter page could be more useful for all (less spam, ability to know who is who, etc..) | |