Module settings

Settings options for modules

• During installation
  • Configuration file
• Managed by system administration
  • Options counter
  • Example – using option at the server
• Managed by client
  • Store the settings
  • get the settings
  • View for values settings
  • Clip or detail?
  • Settings usage by the client applications
  • loading to the application
  • Using settings in the application

AyMINE modules has several types of configuration and settings.

During installation

Installation process is described in the section here.
Each module should be installed to the AyMINE environment to be available. Installation supports files that can make configuration in relation to the environment, other modules and their configuration or other data.

• Configuration file Conf
• Installation backend class Install based on the baseJSONImport class
• Language installation – each module could define its own language strings and language objects for back-end translations
• Role installation – definition of the system roles related with module. File is created from AyMINE using the role-export functionality

Configuration file

Module configuration file defines:

• What objects are available. Depending on the system configuration might remove some objects
• List of client-defined counters with default values. (Currently translation for default values is not supported, so that they could be defined only in single language. However, each client defines its own and the default values are intended to the recommendation of common values.)
• Text attributes – Values are manageable for each client independently and can be used both by server or in the orchestration (?)
• rights – Common module rights. It is recommended use primarily rights defined here instead of object-specific rights. However, both are supported and there is no difference in the behaviour. The advantage of rights defined here is better overview about them.
• backendRights – Rights that are not loaded to the client. The advantage of the backend rights is that client application has no possibility to find out that user has the right. Hiding system rights in the backend only might make application more safe. The major reason for back-end rights is to reduce amount of data loaded to the client application.
• Event handlers – Registration of methods that to the messaging middleware. Event handlers are called automatically by the middleware when the linked event occurs. Single event might have more handlers but in that case and order of their call is accidental.

Managed by system administration

Options counter

Each module can define options that are managed by the system administration (client cannot set them). The options are defined in the counter as the <module>Options counter.

Counter with module options are loaded for client settings in the system client administration. Values are always client-specific.

Example – using options in the evaluation condition in the application

user.hasModuleOption('mod','ABC')

The condition returns true if client has set the option ABC from the mod module

Example – using option at the server

$isOption = sysClient::hasModuleOption(
   $sysClientID, 
   'tsk', 
   tskTsk::tskOpt_sabre
);

Function checks the client option. It is recommended to created option constants as the regular programme constants. (Use the AyMINE framework PHP counter constant generator to create them automatically.)

Managed by client

Client-defined options could each module define independently. Framework supports their definition, storing and loading.

Store the settings

/** Set the client-relates and module-related setting value
 * @param string $module, – module related with settings
   * @param string $settingAttrName – name of the settings attributes
   * @param $sysClientID = null – id of the client, 
   *     when null / empty client of the currently logged user is used, 
   * value 0 is also accepted for globally defined values
   */
frmFrm:: setModuleSettings(
   string $module,    
   string $settingAttrName, 
   string $attrVal, 
   $sysClientID = null
);

Value can be up to 300 characters long – it is enough for simple object with several values (in the json format) but the framework function does no convert it.

get the settings

Counterpart method to get the settings is

/** Returns single attribute field value for module
 * Values are permanently stored in database and always per-client related.
   * @param string $module, – module related with settings
   * @param string $settingAttrName – name of the settings attributes
   * @param $sysClientID = null – id of the client, 
   *     when null / empty client of the currently logged user is used, 
   * value 0 is also accepted for globally defined values
   * @return string – stored value, null – when value is not defined
   */
frmFrm::getModuleSettings(
   string $module, 
   string $settingAttrName, 
   $sysClientID = null
): string|null

Recomendation: Use the frmFrm::moduleSettings methods only if module has only a few settings to store. Use module-specific settings object if there is more values to store. Naturally, decision also depends on the way how the setting data are used.

View for values settings

View for values settings should be defined as a clip or view

Clip or detail?

Clip is recommended for simpler settings when only few values is defined. If module needs complex client settings it is recommended to create module-specific settings object with all settings fields and create detail for its editing.

Although reading of several settings values would be faster when all are defined in a single object – i.e. single table row line.

Integrate settings view

For client-defined settings AyMINE defined frmAymine object view systemAdmin.

User the frmAyMINE object extension to add module settings:

Example:

// ****************   Extensions ***************
"extensions":{

   // ********            frmAymine extension             *********
   "frmAymine":{
      // Extension for hr module
      "extParameters":{ "uright":"hr@hrEverybody"  },
      "about":{"langModules":[ "hr/langs/@/hrCommon"]  },
      "views":{ 
         "details":{ 
            "systemAdmin":{ 
               "tabs":{ 
                  "hrSettings":{ 
                     "icon":"staffer__COadministration", 
                     "view":"form.hrStaffer.clip.moduleAdmin" 
                  }
               }
            }
         }
      }
   }  // end of frmAymine extension
   
}  // end of extensions

Settings usage by the client applications

loading to the application

Each module can load the settings to the application. It should create method

class <module>Init
   /** Generate module userInfo data for client application */
   public static function getUserInfo(): object {}

The object that methods returns is loaded to the users application and renewed every few minutes.

Remember: Data sent to the client application could combine module settings with other data that module needs at the client application.

Using settings in the application

The loaded object data area globally available in the application and can be used by java script libraries as well as by the evaluated methods using the `user.mParam command:

/** Returns user module info.
  * Content is generated by backend function <module>Info.getUserInfo() method
 * @param module: string – name of the module
 */
user.mParam(module: string): object|false 

Example:_

"right":"=user.mParam('mod').modIsVal"

Method in the example is used set right to show some field and right depends on loading module-specific and user-specific settings.