CSInstallationPlugin
extends CSPlugin
in package
This Plugin is executed during installation and datamodel update processes.
It may be used to manipulate data and or to define static Records To be included, it must be placed in any plugins/core subfolder with a file ending with Installation.php
Tags
Table of Contents
- __call() : mixed|string
- All method calls which are not defined within the plugin are forwarded to the module Therefore it is possible to get, e.g. the label by calling the getSuiteName() method.
- _construct() : void
- The construct method may be used to initialize custom plugin properties it is called immediately after instantiating the plugin all arguments passed to the getPlugins method are also available in this method.
- addAlternativePluginFolder() : void
- A path to a specific folder in which should be search for plugins.
- afterInstallationFromFolder() : void
- This method is called after all backup files have been installed from the backup folder. It allows to install custom data from the backup after everything else is done.
- beforeZipBackupFolder() : void
- This method is called shortly before the created backup folder with all its backup files is zipped. It can be used to add custom backup data into the CS backup.
- defineAdditionalRecords() : void
- This method can be used to define additional records.
- getAdditionalRecordsEditableFields() : array<string|int, mixed>
- This method is called to check for editable fields in additionalRecord.
- getAlternativePluginFolder() : array<string|int, mixed>
- getLevel() : int
- The getLevel method may be overwritten in the plugins and defines the order, the plugins are called, where the highest level is called first.
- getMetaData() : CSMetaData
- Returns the CSMetaData of the current plugin.
- getModule() : CSModule
- Returns the module, if the plugin is defined within a module.
- getPlugin() : CSPlugin|null
- Returns a CSPlugin for the given plugin type and plugin class name.
- getPluginChooser() : array<string|int, mixed>
- Returns an array all defined CSPlugins for the current plugin type
- getPluginData() : mixed
- getPluginDefinitionFile() : string
- Returns the path to the file, the plugin is defined.
- getPluginName() : mixed
- getPlugins() : array<string|int, CSPlugin>
- Returns all defined CSPlugins for the current plugin type It should be used to get all matching plugins for a given plugin api.
- getPluginsInModule() : array<string|int, mixed>
- Returns all CSPlugins for the current plugin type which are defined within the given module It should be used to get all matching plugins for a given plugin api.
- isAvailable() : bool
- This method is called to check, whether the plugin is available.
- may() : void
- Checks any "May" event of additional record to be able to handle them without in one global class without the need of a CSEventPlugin.
- onAfterInstallation() : void|array<string|int, mixed>
- This method is called when a module has been installed
- onBeforeInstallBackupFile() : bool
- This method is called shortly before a single backup file is installed into the DB. It allows to prevent custom backup files from being installed automatically by CS.
- resetLoadedPlugins() : mixed
- reset the internal plugins cache for loaded plugins
Methods
__call()
All method calls which are not defined within the plugin are forwarded to the module Therefore it is possible to get, e.g. the label by calling the getSuiteName() method.
public
__call(mixed $methodName, mixed $methodArguments) : mixed|string
Parameters
- $methodName : mixed
- $methodArguments : mixed
Tags
Return values
mixed|string —_construct()
The construct method may be used to initialize custom plugin properties it is called immediately after instantiating the plugin all arguments passed to the getPlugins method are also available in this method.
public
_construct() : void
Tags
Return values
void —addAlternativePluginFolder()
A path to a specific folder in which should be search for plugins.
public
static addAlternativePluginFolder(mixed $sPluginFolder) : void
Parameters
- $sPluginFolder : mixed
Tags
Return values
void —afterInstallationFromFolder()
This method is called after all backup files have been installed from the backup folder. It allows to install custom data from the backup after everything else is done.
public
afterInstallationFromFolder(string $sFolder) : void
Parameters
- $sFolder : string
-
The path to the backup folder.
Tags
Return values
void —beforeZipBackupFolder()
This method is called shortly before the created backup folder with all its backup files is zipped. It can be used to add custom backup data into the CS backup.
public
beforeZipBackupFolder(string $sFolder, string $sBackupModule) : void
Parameters
- $sFolder : string
-
The path to the backup folder.
- $sBackupModule : string
-
A string with the information which module is currently backed up. In case of a complete backup, this variable is null.
Tags
Return values
void —defineAdditionalRecords()
This method can be used to define additional records.
public
defineAdditionalRecords(string $moduleName) : void
It may use negative IDs to ensure that the records may not be deleted. If you define negative records please use the following convention to avoid conflicts:
- IDs between -11 and -1000 are for CONTENTSERV core only.
- IDs between than -1000 and -10000 are for other module developers
- IDs lower than -10000 are free to use in projects.
You have to create, update (and delete) your custom records in the method. Per default those negative records are editable. If you want to make some fields non editable use the getAdditionalRecordsEditableFields method to define the editable fields . If you want the whole record not be editable cancel the "MayCreate" event in the may method of this plugin.
Parameters
- $moduleName : string
-
the name of the module for which the additional records should be added
Tags
Return values
void —getAdditionalRecordsEditableFields()
This method is called to check for editable fields in additionalRecord.
public
getAdditionalRecordsEditableFields(Record $additionalRecord) : array<string|int, mixed>
If some fields are marked as editable, all other are not editable. If no fields are marked all fields are editable.
Parameters
- $additionalRecord : Record
-
the Record which is edited at the moment
Tags
Return values
array<string|int, mixed> —the name of the fields which are editable
getAlternativePluginFolder()
public
static getAlternativePluginFolder() : array<string|int, mixed>
Tags
Return values
array<string|int, mixed> —getLevel()
The getLevel method may be overwritten in the plugins and defines the order, the plugins are called, where the highest level is called first.
public
getLevel() : int
The method can also be set for all plugins within a module by overwriting the modules getLevel method.
Tags
Return values
int —the level of the plugin where it is called
getMetaData()
Returns the CSMetaData of the current plugin.
public
getMetaData() : CSMetaData
Tags
Return values
CSMetaData —getModule()
Returns the module, if the plugin is defined within a module.
public
getModule() : CSModule
This method can be used in the plugin api and the plugin wherever access to the defining module is required. If it is used in the Api, it should be noticed that this method may return null, if the plugin is directly defined in the projects or admin.local plugins directory.
Tags
Return values
CSModule —the module object, if the plugin defined in a module or null otherwise
getPlugin()
Returns a CSPlugin for the given plugin type and plugin class name.
public
static getPlugin(string $pluginApiPath, string $className[, mixed $arguments = NULL ]) : CSPlugin|null
As standard behaviour the module subfolder is guessed from the forward URL parameter. If a plugin should point to something in a special module subfolder, this scope can be added by adding the module name in squared bracket at the end of the $pluginApiPath, e.g. 'core/api/plugins/CSRecordPlugin.php[pms]' to get all CSRecordPlugins defined for pms records.
Parameters
- $pluginApiPath : string
-
The relative path in filesystem for the requested plugin api (optional: ending with the module subfolder).
- $className : string
-
The target plugin class name, which should be loaded.
- $arguments : mixed = NULL
-
one or multiple arguments which should be passed to the isAvailable method.
Tags
Return values
CSPlugin|null —Returns the requested plugin for the given parameter.
getPluginChooser()
Returns an array all defined CSPlugins for the current plugin type
public
static getPluginChooser(string $pluginApiPath[, mixed $arguments = NULL ]) : array<string|int, mixed>
Parameters
- $pluginApiPath : string
-
the relative path in filesystem for the requested plugin api (optional: ending with the module subfolder).
- $arguments : mixed = NULL
-
one ore multiple arguments which should be passed to the isAvailable method.
Tags
Return values
array<string|int, mixed> —of CSPlugins in the form [CLASSNAME => LABEL] where the CLASSNAME may be used in the CSPlugin::getPlugin method
getPluginData()
public
getPluginData() : mixed
Tags
Return values
mixed —getPluginDefinitionFile()
Returns the path to the file, the plugin is defined.
public
getPluginDefinitionFile() : string
Tags
Return values
string —the path to the plugin
getPluginName()
public
getPluginName() : mixed
Tags
Return values
mixed —getPlugins()
Returns all defined CSPlugins for the current plugin type It should be used to get all matching plugins for a given plugin api.
public
static getPlugins(string $pluginApiPath[, mixed $arguments = NULL ]) : array<string|int, CSPlugin>
As standard behaviour the module subfolder is guessed from the forward URL parameter. If a plugin should point to something in a special module subfolder, this scope can be added by adding the module name in squared bracket at the end of the $pluginApiPath, e.g. 'core/api/plugins/CSRecordPlugin.php[pms]' to get all CSRecordPlugins defined for pms records.
Parameters
- $pluginApiPath : string
-
the relative path in filesystem for the requested plugin api (optional: ending with the module subfolder).
- $arguments : mixed = NULL
-
one ore multiple arguments which should be passed to the isAvailable method.
Tags
Return values
array<string|int, CSPlugin> —array of CSPlugin objects matching the defined plugin criteria
getPluginsInModule()
Returns all CSPlugins for the current plugin type which are defined within the given module It should be used to get all matching plugins for a given plugin api.
public
static getPluginsInModule(string $moduleName, string $pluginApiPath[, mixed $sFileNamePattern = '' ][, mixed $arguments = NULL ]) : array<string|int, mixed>
Parameters
- $moduleName : string
-
the module which should be searched for plugins
- $pluginApiPath : string
-
the relative path in filesystem for the requested plugin api.
- $sFileNamePattern : mixed = ''
- $arguments : mixed = NULL
-
one ore multiple arguments which should be passed to the isAvailable method.
Tags
Return values
array<string|int, mixed> —of CSPlugin objects matching the defined plugin criterias
isAvailable()
This method is called to check, whether the plugin is available.
public
isAvailable() : bool
If further arguments are added to the CSPlugin::getPlugins call, they are added as arguments to this method.
For simpler usage of the plugin concept: This method should be overwritten with the correct signature for a plugin call, if arguments are passed.
Tags
Return values
bool —whether the plugin is available for the given arguments
may()
Checks any "May" event of additional record to be able to handle them without in one global class without the need of a CSEventPlugin.
public
may(CSEvent $event) : void
The method cancel can be used to cancel the event for some or all IDs. For Further informations see the may method in the CSEventPlugin
Parameters
- $event : CSEvent
-
the Event containing informations about the Record, the event type, the ids, ...
Tags
Return values
void —onAfterInstallation()
This method is called when a module has been installed
public
onAfterInstallation(string $moduleName) : void|array<string|int, mixed>
Parameters
- $moduleName : string
-
the name of the module which had been installed
Tags
Return values
void|array<string|int, mixed> —If an array is returned, the strings stored there are shown as additional messages in the update data model output.
onBeforeInstallBackupFile()
This method is called shortly before a single backup file is installed into the DB. It allows to prevent custom backup files from being installed automatically by CS.
public
onBeforeInstallBackupFile(string $sBackupFile) : bool
Parameters
- $sBackupFile : string
-
The complete path to the backup file that should be installed.
Tags
Return values
bool —TRUE (default) if the backup file should be installed by CS, FALSE if this file should be skipped.
resetLoadedPlugins()
reset the internal plugins cache for loaded plugins
public
static resetLoadedPlugins() : mixed