One of the great features of SugarCRM is its extensibility and one way to utilize that extensibility is by creating modules. Modules are generally developed to meet a business need such as the functionality provided by forums, teams or social media integrations. These SugarCRM modules are packaged as zip files and contain a manifest.php file in the root directory that defines how SugarCRM will install the module. This guide will outline and detail all aspects of the SugarCRM manifest file so that you can develop modules more efficiently and with less guess work.
There are three main arrays in the manifest.php file; $manifest, $installdefs, and $upgrade_manifest.
$manifest = array(
Defines which editions of SugarCRM that the package can be installed on. Acceptable values: CE, PRO, and ENT
Example:
‘acceptable_sugar_flavors’ => array(
‘CE’, ‘PRO’ ,‘ENT’
),
Defines which versions of SugarCRM that the package is supported on. There are two options for matching versions; exact_matches or regex_matches.
Example:
‘acceptable_sugar_versions’ => array (
‘exact_matches’ => array (
‘5.5.0’, ‘5.5.1a’
),
),
OR:
‘acceptable_sugar_versions’ => array (
‘regex_matches’ => array (
‘5\.5\.0*’,
),
),
(Optional) The Module Builder will allow the author to set a README text within a text box to be displayed during installation. If this is desired for a hand built package instead create a README.txt in the root directory of the zip and the installer will pick it up and display it.
Example:
‘readme’ => ‘Please make sure to visit our documentation at…’,
(Optional) The Module Builder will force the author to define a key so that the module will not conflict with other similar modules. For example, there may be multiple twitter modules out there that. To avoid stepping on toes (such as overwritting the modules/Twitter/.. directory) a key can be used to help ensure uniqueness. For example ‘crmstage’ could be used which would create the module directory and tables with a crmstage_prefix (modules/crmstage_Twitter).
Example:
‘key’ => ‘crmstage’,
The author(s) who created the package.
Example:
‘author’ => ‘CRMStage’,
(Optional) A short description of the package.
Example:
‘description’ => ‘Yet another Twitter module,
(Optional) An icon that will be displayed during installation.
Example:
‘icon’ => ‘/icon/CRMStage.png’,
Defines whether the package can be uninstalled. It is highly suggested that any module be uninstallable.
Example:
‘is_uninstallable’ => true,
Name of the package. This will be displayed both during the installation and also on the Module Loader list.
Example:
‘name’ => ‘Twitter Module’,
The date that the package was created and published.
Example:
‘published_date’ => ‘2010/01/04’,
>From http://www.sugarcrm.com/wiki/index.php?title=Manifest.php#type: The package type. Accepted values include: langpack, module, patch, full, and theme.
* Packages of type langpack will be automatically added to the “Language” dropdown on the Sugar Login screen. They are installed using the Upgrade Wizard.
* Packages of type module are installed using the Module Loader.
* Packages of type patch are installed using the Upgrade Wizard.
* Packages of type theme will be automatically added to the “Theme” dropdown on the Sugar Login screen. They are installed using the Upgrade Wizard.
Example:
‘type’ => ‘module’,
The version of the package. This can be any combination of alphanumeric characters.
Example:
‘version’ => ‘2.5’,
(Optional) By default the uninstaller will assume this to be set to ‘true’. If the user should be allowed to choose whether to remove the database tables or not ‘prompt’ should be used. This is suggested to help avoid accidental data loss.
Example:
‘remove_tables’ => ‘prompt’,
(Optional) An array that defines what modules need to be installed before the current package can be installed.
Example:
‘dependencies’ => array(
array(
‘id_name’ => ‘twitter_helper’,
‘version’ => ‘1.0’
),
),
Closing the $manifest array
);
Similar to the README.txt mentioned above a license can be displayed by dropping a LICENSE.txt file into the root zip directory. The license will be displayed during installation and will force the installer to choose whether to accept the license or not. Choosing to not accept the license will cause the installation to abort.
$installdefs
$installdefs= array(
Closing the $installdefs array
);
The name of the module. This MUST be unique.
Example:
‘id’ => ‘Twitter’,
The path to the images that should be added to the default theme directory. These images may include module icons, etc.
Example:
‘image_dir’ => ‘/images’,
An array of Sugar Beans included as part of the module.
* module: The module’s name
* class: The name of the class defined in the bean file
* path: The path containing the bean’s definition (the file that extends the core SugarBean.php)
* tab: Determines whether a tab should be created for the module
Example:
‘beans’ => array(
array(
‘module’ => ‘Twitter’,
‘class’ => ‘Twitter’,
‘path’ => ‘modules/Twitter/Twitter.php’,
‘tab’ => true,
)
),
Used to define what files or directories to copy. Generally these are the core files to the module. This may also be used for copying over include files, libraries, etc.
Example:
‘copy’ => array(
array(
‘from’ => ‘/modules/Twitter’,
‘to’ => ‘modules/Twitter’,
),
),
Used to define what files or directories to copy. Generally these are the core files to the module. This may also be used for copying over include files, libraries, etc.
Example:
‘mkdir’ => array(
‘/cache/twitter/images/’,
),
Defines the display text for various labels for specific modules or for the application as a whole.
Example:
‘language’ => array(
/** ENGLISH en_us */
array(
‘from’ => ‘/language/application/en_us.twitteradmin.php’,
‘to_module’ => ‘application’,
‘language’ => ‘en_us’
),
array(
‘from’ => ‘/language/modules/Administration/en_us.twitteradmin.php’,
‘to_module’ => ‘Administration’,
‘language’ => ‘en_us’
),
array(
‘from’ => ‘/language/modules/Contacts/en_us.twitter.php’,
‘to_module’ => ‘Contacts’,
‘language’ => ‘en_us’
),
/** END ENGLISH en_us */
/** SPANISH es_es */
array(
‘from’ => ‘/language/application/es_es.twitteradmin.php’,
‘to_module’ => ‘application’,
‘language’ => ‘es_es’
),
array(
‘from’ => ‘/language/modules/Administration/es_es.twitteradmin.php’,
‘to_module’ => ‘Administration’,
‘language’ => ‘es_es’
),
array(
‘from’ => ‘/language/modules/Contacts/es_es.twitter.php’,
‘to_module’ => ‘Contacts’,
‘language’ => ‘es_es’
),
/** END SPANISH es_es */
),
Custom menu links can be defined and added to any module with the menu array.
Example:
‘menu’ => array (
array(
‘from’ => ‘/menu/modules/Twitter/menu.php’,
‘to_module’ => ‘Twitter’
)
),
Add any custom dashlets that need to be installed to this array.
Example:
‘dashlets’ => array (
array(
‘from’ => ‘/dashlets/modules/Twitter/TwitterDashlet/’,
‘name’ => ‘TwitterDashlet’
)
),
Used to define customized subpanel layouts for modules. Add, remove, or reorder subpanels with this array.
Example:
‘layoutdefs’ => array(
array(
‘from’ => ‘/layoutdefs/modules/Contacts/twitter_contacts_layoutdefs.php’,
‘to_module’ => ‘Contacts’,
),
),
Although any custom field may be defined in these files they are generally used to define non-database custom fields such as those of type link or those that are meant for display only info such as calculated fields or data from external systems.
Example:
‘vardefs’ => array(
array(
‘from’ => ‘/vardefs/modules/Contacts/twitter_contacts_vardefs.php’,
‘to_module’ => ‘Contacts’,
),
),
The array holds definition files for adding link options to the Admin page.
Example:
‘administration’ => array(
array(
‘from’ => ‘/administration/twitter_adminoption.php’,
),
),
Here is where any relationships between the custom module and any other module is defined. The module and meta_data indexes are required.
Example:
‘relationships’ => array(
array(
‘module’ => ‘Contacts’,
‘meta_data’ => ‘/relationships/modules/Contacts/twitter_contacts_metadata.php’,
‘module_vardefs’ => ‘/relationships/modules/Contacts/twitter_contacts_vardefs.php’,
‘module_layoutdefs’ => ‘/relationships/modules/Contacts/twitter_contacts_layoutdefs.php’
),
),
Generally used to add custom fields to existing modules. From http://www.sugarcrm.com/wiki/index.php?title=Manifest.php#custom_fields:
* name: The internal name of your custom field. Note that your custom field will be referred to as _c, as “_c” indicates a custom field.
* label: The visible label of your custom field
* type: The type of custom field. Accepted values include text, textarea, double, float, int, date, bool, enum, and relate.
* max_size: The custom field’s maximum character storage size
* require_option: Used to mark custom fields are either required or option. Accepted values include optional and required.
* default_value: Used to specify a default value for your custom field
* ext1: Used to specify a dropdown name (only applicable to enum type custom fields)
* ext2: Unused
* ext3: Unused
* audited: Used to denote whether or not the custom field should be audited. Accepted values include 0 and 1.
* module: Used to specify the module where the custom field will be added.
Example:
‘custom_fields’ => array(
array(
‘name’ => ‘twitter_name’,
‘label’ => ‘Twitter Name’,
‘type’ => ‘varchar’,
‘max_size’ => 255,
‘require_option’ => ‘optional’,
‘default_value’ => ’ ‘,
‘ext1’ => ‘’,
‘ext2’ => ‘’,
‘ext3’ => ’ ‘,
‘audited’ => 0,
‘module’ => ‘Contacts’,
),
),
Defines what logic hooks (workflows) that the module needs installed. See http://www.sugarcrm.com/wiki/index.php?title=Logic_Hooks for more information.
Example:
‘logic_hooks’ => array(
array(
‘module’ => ‘Contacts’,
‘hook’ => ‘after_save’,
‘order’ => 100,
‘description’ => ‘Misc Twitter Hooks’,
‘file’ => ‘custom/modules/Twitter/TwitterHook.php’,
‘class’ => ‘TwitterHook’,
‘function’ => ‘process_tweets’,
),
),
There are four scripts that can be defined as part of the module install/uninstall process. To make use of this ability add a scripts directory to the base directory of the module zip and add one or more of the following files:
* scripts/pre_install.php
* scripts/post_install.php
* scripts/pre_uninstall.php
* scripts/post_uninstall.php
These files can be used for anything from pre-installation checks to module satisfaction surveys to even simply display author information and help links.
(Optional) Defines the upgrade path between versions. The installer will check to see if the module has been installed already. If so, it will check the current version of the module installed and will process the instructions defined in the corresponding upgrade_path. For example, if the Twitter module has been installed already and is at version 1.0 it will process the 1.0 instructions which specifies to copy the Twitter module directory and to add a new custom field to the Contacts module. If the currently installed version is 2.0 it will just copy the Twitter module directory (since it is assumed that the custom field has already been created).
Example:
$upgrade_manifest = array(
‘upgrade_paths’ => array(
‘1.0’ => array(
‘id’ => ‘Twitter’,
‘copy’=>array(
array(
‘from’=> ‘/modules/Twitter’,
‘to’=> ‘modules/Twitter’,
),
),
‘custom_fields’ => array(
array(
‘name’ => ‘twitter_name’,
‘label’ => ‘Twitter Name’,
‘type’ => ‘varchar’,
‘max_size’ => 255,
‘require_option’ => ‘optional’,
‘default_value’ => ’ ‘,
‘ext1’ => ‘’,
‘ext2’ => ‘’,
‘ext3’ => ’ ‘,
‘audited’ => 0,
‘module’ => ‘Contacts’,
),
),
),
‘2.0’ => array(
‘id’ => ‘Twitter’,
‘copy’ => array(
array(
‘from’=> ‘/module/Twitter’,
‘to’=> ‘modules/Twitter’,
),
),
),
),
);
$manifest = array(
‘acceptable_sugar_flavors’ => array(
‘CE’, ‘PRO’ ,‘ENT’
),
‘acceptable_sugar_versions’ => array (
‘regex_matches’ => array (
‘5\.*’,
),
),
‘readme’ => ‘Please make sure to visit our documentation at…’,
‘key’ => ‘’,
‘author’ => ‘CRMStage’,
‘description’ => ‘Yet another Twitter module,
‘icon’ => ‘/icon/CRMStage.png’,
‘is_uninstallable’ => true,
‘name’ => ‘Twitter Module’,
‘published_date’ => ‘2010/01/04’,
‘type’ => ‘module’,
‘version’ => ‘2.5’,
‘remove_tables’ => ‘prompt’,
‘dependencies’ => array(
array(
‘id_name’ => ‘twitter_helper’,
‘version’ => ‘1.0’
),
),
);
$installdefs = array(
‘id’ => ‘Twitter’,
‘image_dir’ => ‘/images’,
‘beans’ => array(
array(
‘module’ => ‘Twitter’,
‘class’ => ‘Twitter’,
‘path’ => ‘modules/Twitter/Twitter.php’,
‘tab’ => true,
)
),
‘copy’ => array(
array(
‘from’ => ‘/modules/Twitter’,
‘to’ => ‘modules/Twitter’,
),
),
‘mkdir’ => array(
‘/cache/twitter/images/’,
),
‘language’ => array(
/** ENGLISH en_us */
array(
‘from’ => ‘/language/application/en_us.twitteradmin.php’,
‘to_module’ => ‘application’,
‘language’ => ‘en_us’
),
array(
‘from’ => ‘/language/modules/Administration/en_us.twitteradmin.php’,
‘to_module’ => ‘Administration’,
‘language’ => ‘en_us’
),
array(
‘from’ => ‘/language/modules/Contacts/en_us.twitter.php’,
‘to_module’ => ‘Contacts’,
‘language’ => ‘en_us’
),
/** END ENGLISH en_us */
/** SPANISH es_es */
array(
‘from’ => ‘/language/application/es_es.twitteradmin.php’,
‘to_module’ => ‘application’,
‘language’ => ‘es_es’
),
array(
‘from’ => ‘/language/modules/Administration/es_es.twitteradmin.php’,
‘to_module’ => ‘Administration’,
‘language’ => ‘es_es’
),
array(
‘from’ => ‘/language/modules/Contacts/es_es.twitter.php’,
‘to_module’ => ‘Contacts’,
‘language’ => ‘es_es’
),
/** END SPANISH es_es */
),
‘menu’ => array (
array(
‘from’ => ‘/menu/modules/Twitter/menu.php’,
‘to_module’ => ‘Twitter’
)
),
‘dashlets’ => array (
array(
‘from’ => ‘/dashlets/modules/Twitter/TwitterDashlet/’,
‘name’ => ‘TwitterDashlet’
)
),
‘layoutdefs’ => array(
array(
‘from’ => ‘/layoutdefs/modules/Contacts/twitter_contacts_layoutdefs.php’,
‘to_module’ => ‘Contacts’,
),
),
‘vardefs’ => array(
array(
‘from’ => ‘/vardefs/modules/Contacts/twitter_contacts_vardefs.php’,
‘to_module’ => ‘Contacts’,
),
),
‘administration’ => array(
array(
‘from’ => ‘/administration/twitter_adminoption.php’,
),
),
‘relationships’ => array(
array(
‘module’ => ‘Contacts’,
‘meta_data’ => ‘/relationships/modules/Contacts/twitter_contacts_metadata.php’,
‘module_vardefs’ => ‘/relationships/modules/Contacts/twitter_contacts_vardefs.php’,
‘module_layoutdefs’ => ‘/relationships/modules/Contacts/twitter_contacts_layoutdefs.php’
),
),
‘custom_fields’ => array(
array(
‘name’ => ‘twitter_name’,
‘label’ => ‘Twitter Name’,
‘type’ => ‘varchar’,
‘max_size’ => 255,
‘require_option’ => ‘optional’,
‘default_value’ => ’ ‘,
‘ext1’ => ‘’,
‘ext2’ => ‘’,
‘ext3’ => ’ ‘,
‘audited’ => 0,
‘module’ => ‘Contacts’,
),
),
‘logic_hooks’ => array(
array(
‘module’ => ‘Contacts’,
‘hook’ => ‘after_save’,
‘order’ => 100,
‘description’ => ‘Misc Twitter Hooks’,
‘file’ => ‘custom/modules/Twitter/TwitterHook.php’,
‘class’ => ‘TwitterHook’,
‘function’ => ‘process_tweets’,
),
),
);
$upgrade_manifest = array(
‘upgrade_paths’ => array(
‘1.0’ => array(
‘id’ => ‘Twitter’,
‘copy’=>array(
array(
‘from’=> ‘/modules/Twitter’,
‘to’=> ‘modules/Twitter’,
),
),
‘custom_fields’ => array(
array(
‘name’ => ‘twitter_name’,
‘label’ => ‘Twitter Name’,
‘type’ => ‘varchar’,
‘max_size’ => 255,
‘require_option’ => ‘optional’,
‘default_value’ => ’ ‘,
‘ext1’ => ‘’,
‘ext2’ => ‘’,
‘ext3’ => ’ ‘,
‘audited’ => 0,
‘module’ => ‘Contacts’,
),
),
),
‘2.0’ => array(
‘id’ => ‘Twitter’,
‘copy’ => array(
array(
‘from’=> ‘/modules/Twitter’,
‘to’=> ‘modules/Twitter’,
),
),
),
),
);