Commit 3fba2cfd authored by KevinLevie's avatar KevinLevie
Browse files

Update README.md, info.xml and other info - and rename resources directory to $1_examples

parent ddbaf424
......@@ -55,7 +55,7 @@ class CRM_Civiconfig_ParamsProvider_ResourcesDir extends CRM_Civiconfig_ParamsPr
$params = json_decode($jsonData, true);
if($params === null || !is_array($params)) {
throw new \CRM_Civiconfig_EntityException("Could not parse JSON file '{$this->_jsonFile}'.");
throw new \CRM_Civiconfig_EntityException("Could not parse JSON file '{$jsonFile}'.");
}
return $params;
......
Package: org.iida.civiconfig
Copyright (C) 2016, Erik Hommel <erik.hommel@civicoop.org>
Package: org.civicoop.configitems
Copyright (C) 2016, IIDA / CiviCooP <helpdesk@civicoop.org>
Licensed under the GNU Affero Public License 3.0 (below).
-------------------------------------------------------------------------------
......
CAREFUL! We have renamed the GitHub repo to avoid confusion on a specific project but NOT yet renamed the overall extension. That will be the next step :-)
org.civicoop.configitems
========================
=======
# org.civicoop.configitems
CiviCRM native extension to load all kinds of configuration
This CiviCRM native extension allows you to define all kinds of configuration items from JSON files, and create or update them in CiviCRM using the *Civiconfig.LoadJson* API method.
Thanks to Emphanos and their customer IIDA for funding the original version of this extension.
This extension loads configuration items from the JSON files in the resources folder and creates or updates them in the CiviCRM installation when you run the API IidaConfig Update. Obviously the extension has been developed for one specific project (thanks to Emphanos and their customer IIDA for funding!) but the principle can easily be copied and re-used.
_Note: the extensions also removes 'old' custom fields from custom groups that are in the JSON files. So if I have a custom group 'test_erik' with custom fields 'test1' and 'test2' in my CiviCRM database and the JSON custom data file has a custom group named 'test_erik' with only the custom field 'test1', running the update job will remove the field 'test2'._
### How to use
The extension can deal with:
- Install the latest version of this extension (see [Releases](releases)).
- Create a resources directory where you'll keep your custom JSON configuration files. For instance */sites/default/modules/civicrm_resources* or */wp-content/uploads/civicrm/resources*, or a directory within another (generic) extension. It's a good idea to version your resources directory using Git.
- Call the API method Civiconfig.LoadJson, and pass the full path to your resources directory in the *path* parameter.
- The configuration items will then be added or updated from the JSON files in this directory (or you'll see an error if the parameters or configuration files weren't valid). See below for the items types that are supported.
### Configuration support
The extension can work with the following types of items:
- activity types
- contact types
- custom groups with custom fields
......@@ -19,3 +26,31 @@ The extension can deal with:
- relationship types
- tags
Refer to the example files (that contain config items for IIDA) in the
[resources_examples](resources_examples) directory as a start to create your own configuration files.
For some more explanation on how this works exactly, check
[this blog post on civicrm.org](https://civicrm.org/blog/erikhommel/extension-to-configure-civicrm-items).
### Tips and notes
- The extensions also removes 'old' custom fields from custom groups that are in the JSON files! So if I have a custom group 'test_erik' with custom fields 'test1' and 'test2' in my CiviCRM database and the JSON custom data file has a custom group named 'test_erik' with only the custom field 'test1', running the updater will remove the field 'test2'.
- For backwards compatibility reasons, the API method doesn't require the *path* parameter. If you don't specify a path, the script will check if a */resources* folder exists in the extension's own directory.
- Feeling adventurous? We've made it relatively easy to use a different file format instead of JSON, or fetch the configuration in a different way entirely (database, url, smoke signals, ...). If you want to do this, create your own class that extends CRM_Civiconfig_ParamsProvider to provide config item data, then call the CRM_Civiconfig_Config->updateConfiguration method passing an instance of your custom class.
### Ideas for future improvements
- Add support for more CiviCRM entity types.
For one, support for ProfileGroups/ProfileFields could probably be borrowed from [this extension](https://github.com/catorghans/net.trinfinity.orgis.mi.dataquality).
- Add support to set certain CiviCRM core settings automatically (using the Setting.create API).
- Add functionality to export config items from an existing CiviCRM installation, for the types of data we support?
- Make it possible to use this extension from an admin page (configuring resource path and running the loader) instead of having to call the API?
- ...and more? Code contributions and/or funding to improve this extension are of course most welcome!
......@@ -175,7 +175,7 @@ function _civiconfig_civix_civicrm_managed(&$entities) {
$es = include $file;
foreach ($es as $e) {
if (empty($e['module'])) {
$e['module'] = 'org.iida.civiconfig';
$e['module'] = 'org.civicoop.configitems';
}
$entities[] = $e;
}
......@@ -204,7 +204,7 @@ function _civiconfig_civix_civicrm_caseTypes(&$caseTypes) {
// throw new CRM_Core_Exception($errorMessage);
}
$caseTypes[$name] = array(
'module' => 'org.iida.civiconfig',
'module' => 'org.civicoop.configitems',
'name' => $name,
'file' => $file,
);
......@@ -230,7 +230,7 @@ function _civiconfig_civix_civicrm_angularModules(&$angularModules) {
$name = preg_replace(':\.ang\.php$:', '', basename($file));
$module = include $file;
if (empty($module['ext'])) {
$module['ext'] = 'org.iida.civiconfig';
$module['ext'] = 'org.civicoop.configitems';
}
$angularModules[$name] = $module;
}
......
<?php
/**
* CiviCRM Configuration Loader (org.civicoop.configitems)
* For information about this extension, see README.md and info.xml.
*
* @author Erik Hommel (CiviCooP) <erik.hommel@civicoop.org>
* @author Johan Vervloet (Chirojeugd-Vlaanderen vzw) <helpdesk@chiro.be>
* @author Kevin Levie <kevin.levie@civicoop.org>
*
* @package org.civicoop.configitems
* @license AGPL-3.0
* @link https://github.com/civicoop/org.civicoop.configitems
*/
require_once 'civiconfig.civix.php';
......@@ -13,10 +25,9 @@ function civiconfig_civicrm_config(&$config) {
/**
* Implements hook_civicrm_xmlMenu().
* @link http://wiki.civicrm.org/confluence/display/CRMDOC/hook_civicrm_xmlMenu
*
* @param $files array(string)
*
* @link http://wiki.civicrm.org/confluence/display/CRMDOC/hook_civicrm_xmlMenu
*/
function civiconfig_civicrm_xmlMenu(&$files) {
_civiconfig_civix_civicrm_xmlMenu($files);
......@@ -60,15 +71,11 @@ function civiconfig_civicrm_disable() {
/**
* Implements hook_civicrm_upgrade().
* @link http://wiki.civicrm.org/confluence/display/CRMDOC/hook_civicrm_upgrade
*
* @param $op string, the type of operation being performed; 'check' or 'enqueue'
* @param $queue CRM_Queue_Queue, (for 'enqueue') the modifiable list of pending up upgrade tasks
*
* @return mixed
* Based on op. for 'check', returns array(boolean) (TRUE if upgrades are pending)
* for 'enqueue', returns void
*
* @link http://wiki.civicrm.org/confluence/display/CRMDOC/hook_civicrm_upgrade
* @return mixed Based on op. for 'check', returns array(boolean) (TRUE if upgrades are pending) for 'enqueue', returns void
*/
function civiconfig_civicrm_upgrade($op, CRM_Queue_Queue $queue = NULL) {
return _civiconfig_civix_civicrm_upgrade($op, $queue);
......@@ -79,7 +86,6 @@ function civiconfig_civicrm_upgrade($op, CRM_Queue_Queue $queue = NULL) {
*
* Generate a list of entities to create/deactivate/delete when this module
* is installed, disabled, uninstalled.
*
* @link http://wiki.civicrm.org/confluence/display/CRMDOC/hook_civicrm_managed
*/
function civiconfig_civicrm_managed(&$entities) {
......@@ -121,18 +127,3 @@ _civiconfig_civix_civicrm_angularModules($angularModules);
function civiconfig_civicrm_alterSettingsFolders(&$metaDataFolders = NULL) {
_civiconfig_civix_civicrm_alterSettingsFolders($metaDataFolders);
}
/**
* Functions below this ship commented out. Uncomment as required.
*
/**
* Implements hook_civicrm_preProcess().
*
* @link http://wiki.civicrm.org/confluence/display/CRMDOC/hook_civicrm_preProcess
*
function civiconfig_civicrm_preProcess($formName, &$form) {
}
*/
<?xml version="1.0"?>
<extension key="org.iida.civiconfig" type="module">
<extension key="org.civicoop.configitems" type="module">
<file>civiconfig</file>
<name>CiviCRM configuration for IIDA</name>
<description>Native extension to generare configuration items for IIDA</description>
<name>CiviCRM Configuration Loader</name>
<description>CiviCRM extension to load custom configuration items from JSON files</description>
<license>AGPL-3.0</license>
<maintainer>
<author>Erik Hommel (CiviCooP)</author>
<email>erik.hommel@civicoop.org</email>
</maintainer>
<urls>
<url desc="Main Extension Page">https://github.com/CiviCooP/org.iida.civiconfig</url>
<url desc="Documentation">https://github.com/CiviCooP/org.iida.civiconfig</url>
<url desc="Main Extension Page">https://github.com/CiviCooP/org.civicoop.configitems</url>
<url desc="Documentation">https://github.com/CiviCooP/org.civicoop.configitems</url>
<url desc="Support">https://www.civicoop.org</url>
<url desc="Licensing">http://www.gnu.org/licenses/agpl-3.0.html</url>
</urls>
<releaseDate>2016-01-13</releaseDate>
<version>1.0</version>
<releaseDate>2016-08-12</releaseDate>
<version>1.2.0</version>
<develStage>beta</develStage>
<compatibility>
<ver>4.4</ver>
<ver>4.5</ver>
<ver>4.6</ver>
<ver>4.7</ver>
</compatibility>
<comments>Make sure the resources folder in the extension is writeable for the user!</comments>
<comments>Please read README.md or check this extension's Github repository for documentation and examples.</comments>
<civix>
<namespace>CRM/Civiconfig</namespace>
</civix>
......
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment