diff --git a/docs/extensions/index.md b/docs/extensions/index.md index 4b21c17d1056a15cbf7b4b9e76089e038f5b7aca..da383045d37985ab7170a5a9a6a1715c0bced69d 100644 --- a/docs/extensions/index.md +++ b/docs/extensions/index.md @@ -7,91 +7,48 @@ Todo: ## Introduction -**CiviCRM Extensions** are packaged pieces of functionality that extend -CiviCRM's out-of-the-box functionality, independent of CMS plaform. +**CiviCRM Extensions** are packaged pieces of functionality that extend CiviCRM's out-of-the-box functionality, independent of CMS plaform. This section covers how to write extensions. ## Extension Names -All extension names follow the same convention as Java package names – they -look like reversed domain names. (e.g. `com.example.myextension`). For -module-extensions, the last word in the module name will be the module's -*short-name*. The short-name *must* be unique. It is possible to pick a -different short-name, but that requires extra work. +All extension names follow the same convention as Java package names – they look like reversed domain names. (e.g. `com.example.myextension`). For module-extensions, the last word in the module name will be the module's *short-name*. The short-name *must* be unique. It is possible to pick a different short-name, but that requires extra work. ## Pre-Requisites -- Have basic knowledge of PHP, Unix, and object-oriented programming -- Install ***civix v14.01*** or newer. For instructions, see - [Civix Documentation](/extensions/civix.md/). - This page assumes that "civix" is installed and registered in - the PATH. -- Configure an extensions directory. For instructions, see - [Extensions](/extensions/index.md). - This page assumes the directory is `/var/www/extensions`, but - you should adapt as appropriate. - Your extensions directory must be under the CMS root directory so - that civix can find and bootstrap the CMS. Otherwise, it will fail - with an error like "Sorry, could not locate bootstrap.inc" on most - operations. -- The user account you use to develop the module must have permission - to read all CMS files, including configuration files, and write to - the extensions directory. - For example, Debian's drupal7 package saves database configuration - to `/etc/drupal/7/sites/default/dbconfig.php`, which is only readable - by the www-data user. You will need to make this file readable by - your development user account for civix to work. +- Have basic knowledge of PHP, Unix, and object-oriented programming. +- Install ***civix v14.01*** or newer. For instructions, see [Civix Documentation](/extensions/civix.md/). This page assumes that "civix" is installed and registered in the PATH. +- Configure an extensions directory. For instructions, see [Extensions](/extensions/index.md). This page assumes the directory is `/var/www/extensions`, but you should adapt as appropriate. Your extensions directory must be under the CMS root directory so that civix can find and bootstrap the CMS. Otherwise, it will fail with an error like "Sorry, could not locate bootstrap.inc" on most operations. +- The user account you use to develop the module must have permission to read all CMS files, including configuration files, and write to the extensions directory. For example, Debian's drupal7 package saves database configuration to `/etc/drupal/7/sites/default/dbconfig.php`, which is only readable by the www-data user. You will need to make this file readable by your development user account for civix to work. ### 0. Decide -Writing an extension is a great way to implement a new feature – but it may be -unnecessary if someone else has already implemented that feature. If you're not -sure, you can do a couple things: +Writing an extension is a great way to implement a new feature – but it may be unnecessary if someone else has already implemented that feature. If you're not sure, you can do a couple things: - Search the [Extensions Directory](http://civicrm.org/extensions) for an existing extension. - Post about your planned extension in the [Extensions Channel](https://chat.civicrm.org/civicrm/channels/extensions). -Extensions provide a native, portable way to extend CiviCRM, but there are -other ways to extend CiviCRM – such as implementing Drupal modules or Joomla -plugins. If you're considering another way, look at the -[Add-on Formats](/extensions/packaging.md) +Extensions provide a native, portable way to extend CiviCRM, but there are other ways to extend CiviCRM – such as implementing Drupal modules or Joomla plugins. If you're considering another way, look at the [Add-on Formats](/extensions/packaging.md) to help decide. ### 1. Install civix -Some tasks in the process of writing an extension require boilerplate code. To -reduce the amount of work required to find, understand, and adapt the -boilerplate code, one should install the CiviCRM extension builder, civix. -Civix is a command-line tool which generates code for some common development -tasks. +Some tasks in the process of writing an extension require boilerplate code. To reduce the amount of work required to find, understand, and adapt the boilerplate code, one should install the CiviCRM extension builder, civix. Civix is a command-line tool which generates code for some common development tasks. >> See [https://github.com/totten/civix/](https://github.com/totten/civix/) ->> For more information on the boilerplate civix generates for you, in - particular the extension manifest file (info.xml), see the [Extension - Reference](/extensions/index.md). +>> For more information on the boilerplate civix generates for you, in particular the extension manifest file (info.xml), see the [Extension Reference](/extensions/index.md). ### 2. Develop -To get started with development, one should usually follow the steps in -"[Create a Module -Extension.](/extensions/civix.md#generate-module)" -A module extension is the most flexible type of extension – it can define any -mix of new reports, custom search screens, payment processors, and web pages; -it can listen for hooks, override page-templates, and more. The coding -conventions closely resemble those of CiviCRM Core and of CiviCRM-Drupal -modules. Module extensions are fully supported in CiviCRM 4.2+. +To get started with development, one should usually follow the steps in "[Create a Module Extension.](/extensions/civix.md#generate-module)". A module extension is the most flexible type of extension – it can define any mix of new reports, custom search screens, payment processors, and web pages; it can listen for hooks, override page-templates, and more. The coding +conventions closely resemble those of CiviCRM Core and of CiviCRM-Drupal modules. Module extensions are fully supported in CiviCRM 4.2+. ### 3. Publish -The CiviCRM ecosystem is built on the belief that non-profit organizations can -serve themselves best by collaborating in development of their data-management -applications. As staff, volunteers, and consultants for non-profit organizations, -we can share our new enhancements and extensions -- and build a richer whole for -the entire ecosystem. - -Extension authors may make their extensions available to the larger CiviCRM -community by publishing them in the [Extensions Directory](https://civicrm.org/extensions). +The CiviCRM ecosystem is built on the belief that non-profit organizations can serve themselves best by collaborating in development of their data-management applications. As staff, volunteers, and consultants for non-profit organizations, we can share our new enhancements and extensions -- and build a richer whole for the entire ecosystem. + +Extension authors may make their extensions available to the larger CiviCRM community by publishing them in the [Extensions Directory](https://civicrm.org/extensions). + >> See: [Publish](/extensions/publish.md) -Extensions which undergo a [formal review](/extensions/lifecycle.md#formal-review) may be -distributed in-app. Approved extensions can be [installed -directly](https://docs.civicrm.org/user/en/master/introduction/extensions/#installing-extensions) -into CiviCRM via the user interface, lowering the barrier to entry for many users. +Extensions which undergo a [formal review](/extensions/lifecycle.md#formal-review) may be distributed in-app. Approved extensions can be [installed directly](https://docs.civicrm.org/user/en/master/introduction/extensions/#installing-extensions) into CiviCRM via the user interface, lowering the barrier to entry for many users. + >> See: [Automated Distribution](/extensions/publish.md#automated-distribution) +