Skip to content
Snippets Groups Projects
Commit da9e32cc authored by Erich's avatar Erich
Browse files

finish transfer

parent 8e6b7cec
No related branches found
No related tags found
No related merge requests found
Hide whitespace changes
Inline Side-by-side
docs/extensions/civix.md
+ 77
− 49
View file @ da9e32cc
...@@ -443,7 +443,7 @@ SQL logic and form layouts. Use this command to get started: ...@@ -443,7 +443,7 @@ SQL logic and form layouts. Use this command to get started:
civix help generate:search civix help generate:search
``` ```
Then you could generate your basic search code with: Then you could generate your basic search code for a MySearch class with:
```bash ```bash
civix generate:search MySearch civix generate:search MySearch
...@@ -464,9 +464,9 @@ If one of the existing searches is close to ...@@ -464,9 +464,9 @@ If one of the existing searches is close to
meeting your needs you may copy it instead and then customise the meeting your needs you may copy it instead and then customise the
PHP, SQL and templates. PHP, SQL and templates.
To make a new search based on an existing search determine the class-name of To make a new search based on an existing search first determine the name of
the original search class within the `civicrm/CRM/Contact/Form/Search/Custom` the original search class within the `civicrm/CRM/Contact/Form/Search/Custom`
within the CiviCRM source tree. Then run the "generate:search" command from directory of CiviCRM source tree. Then run the "generate:search" command from
within your module directory. within your module directory.
For example, the zipcode search is in the class For example, the zipcode search is in the class
...@@ -482,29 +482,38 @@ on whether the original search screen defines its own Smarty template. ...@@ -482,29 +482,38 @@ on whether the original search screen defines its own Smarty template.
### Add an API function ### Add an API function
The [CiviCRM API](../api/general) The [CiviCRM API](../api/general)
provides a way to expose functions for use by other developers – API provides a way to expose functions for use by other developers. API
functions can be useful for implementing AJAX interfaces (using the functions allow implementing AJAX interfaces (using the
cj().crmAPI() helper), and they can also be called via REST, PHP, cj().crmAPI() helper), and they can also be called via REST, PHP,
Smarty, Drush CLI, and more. Each API requires a two-part name: an Smarty, Drush CLI, and more. Each API requires a two-part name: an
entity name (such as "Contact", "Event", or "MyEntity") and an action entity name (such as "Contact", "Event", or "MyEntity") and an action
name (such as "Create" or "MyAction"). name (such as "Create" or "MyAction").
Get started by accessing the `civix` help:
```bash ```bash
civix generate:api civix help generate:api
``` ```
>> ![danger](../img/danger.png) >> ![information](../img/info.png)
Action names must be lowercase. The javascript helpers CRM.api() and Action names must be lowercase. The javascript helpers `CRM.api()` and
CRM.api3() force actions to be lowercase. This issues does not present `CRM.api3()` force actions to be lowercase. This issues does not present
itself in the API Explorer or when the api action is called via PHP, itself in the API Explorer or when the api action is called via PHP,
REST, or SMARTY REST, or SMARTY.
You can make your API code with a command in this pattern:
```bash
civix generate:api NewEntity NewAction
```
This creates one file: This creates one file:
- `api/v3/NewEntity/NewAction.php` provides the API function. Note - `api/v3/NewEntity/NewAction.php` provides the API function.
that the parameters and return values must be processed in a that the parameters and return values must be processed in a
particular way (as demonstrated by the auto-generated file). particular way (as demonstrated by the auto-generated file).
<!-- fixme - clarify is this 4.3 and later? -->
For use with CiviCRM 4.3, you can also add the "–schedule" option (e.g. For use with CiviCRM 4.3, you can also add the "–schedule" option (e.g.
"–schedule Hourly"). This will create another file: "–schedule Hourly"). This will create another file:
...@@ -513,15 +522,17 @@ For use with CiviCRM 4.3, you can also add the "–schedule" option (e.g. ...@@ -513,15 +522,17 @@ For use with CiviCRM 4.3, you can also add the "–schedule" option (e.g.
### Add a new entity ### Add a new entity
You may have a need to create a new entity that doesn't exist in >> ![danger](../img/danger.png)
CiviCRM. For this, you can use the command civix generate:entity - which This functionality is considered "experimental and incomplete".
as of this writing is considered "experimental and incomplete". This
documentation will guide you through filling in the blanks. You may have a need to create a new entity that does not exist in
CiviCRM. For this, you can use the command `civix generate:entity`
- Pick a name for your entity. In some places, CiviCRM expects a - Pick a name for your entity. In some places, CiviCRM expects a
FirstLetterCapitalizedName, in others, an underscore\_name. Be *FirstLetterCapitalizedName*, in others, an *underscore\_name*. Be
absolutely consistent in your naming, because CiviCRM expects to be absolutely consistent in your naming, because CiviCRM needs to
able to translate between those two naming conventions. translate between those two naming conventions.
- Run `civix generate:entity <name of entity>` (entity name should be - Run `civix generate:entity <name of entity>` (entity name should be
FirstLetterCapitalized here). This creates a skeletal file for your FirstLetterCapitalized here). This creates a skeletal file for your
XML schema, your BAO, and your API. It does NOT create a skeletal XML schema, your BAO, and your API. It does NOT create a skeletal
...@@ -529,10 +540,10 @@ documentation will guide you through filling in the blanks. ...@@ -529,10 +540,10 @@ documentation will guide you through filling in the blanks.
- Edit the XML schema in the "xml" folder to match the fields you - Edit the XML schema in the "xml" folder to match the fields you
want. Minimal documentation is available want. Minimal documentation is available
[here](https://wiki.civicrm.org/confluence/display/CRMDOC/Database+Reference), [here](https://wiki.civicrm.org/confluence/display/CRMDOC/Database+Reference),
but you're better off looking at the [existing XML but you are better off looking at the [existing XML
schemata](https://github.com/civicrm/civicrm-core/tree/master/xml/schema). schemata](https://github.com/civicrm/civicrm-core/tree/master/xml/schema).
- Create a DAO file. For now, civix does not handle this. You can - Create a DAO file. For now, civix does not handle this. You can
create this by hand; alternatively, use [this create this by hand. Alternatively, use [this
technique](http://civicrm.stackexchange.com/a/3536/12). Copy your technique](http://civicrm.stackexchange.com/a/3536/12). Copy your
XML schema into a development copy of CiviCRM. Edit Schema.xml to XML schema into a development copy of CiviCRM. Edit Schema.xml to
include your XML file, then from the xml folder, run include your XML file, then from the xml folder, run
...@@ -540,46 +551,49 @@ documentation will guide you through filling in the blanks. ...@@ -540,46 +551,49 @@ documentation will guide you through filling in the blanks.
`<civiroot>/bin/setup.sh -g` instead). This will generate a DAO file `<civiroot>/bin/setup.sh -g` instead). This will generate a DAO file
for you in the CiviCRM core code; copy it into the for you in the CiviCRM core code; copy it into the
CRM/<Entityname\>/DAO folder of your extension. CRM/<Entityname\>/DAO folder of your extension.
- At this time, civix also does not generate the SQL to create and - Currently, `civix` does not generate the SQL to create and
drop your table(s). You can create these by hand; alternatively, if drop your table(s). You can create these by hand, or, if
you used the `<civiroot>/bin/setup.sh -g` technique to create your you used the `<civiroot>/bin/setup.sh -g` technique to create your
DAO, SQL will have been generated for you in DAO, SQL will have been generated for you in
`<civiroot>/sql/civicrm.mysql`. Once you have the SQL statements for `<civiroot>/sql/civicrm.mysql`. Once you have the SQL statements for
creating and dropping your SQL tables, you can name them creating and dropping your SQL tables, create
`auto_install.sql` and `auto_uninstall.sql` `auto_install.sql` and `auto_uninstall.sql`
respectively and drop them in your "sql" folder. They will be run respectively in your 'sql/' folder. CiviCRM will run them
automatically on install if you generated an upgrader. Note that automatically on install if you generated an upgrader. Note that
using `auto_install.sql` and `auto_uninstall.sql` using `auto_install.sql` and `auto_uninstall.sql`
is not best practice if you have multiple statements in each file, is not best practice if you have multiple statements in each file,
since you can't error check each statement separately. since you cannot error check each statement separately.
- Run `civix generate:upgrader` from within your extension. [More <!-- fixme update and clarify -->
details are - Run `civix generate:upgrader` from within your extension.
here](https://wiki.civicrm.org/confluence/display/CRMDOC/Create+a+Module+Extension#CreateaModuleExtension-Addadatabaseupgrader/Installer/uninstaller).
- Define your entity using - Define your entity using
[hook\_civicrm\_entityTypes](https://wiki.civicrm.org/confluence/display/CRMDOC/hook_civicrm_entityTypes). [hook\_civicrm\_entityTypes](https://wiki.civicrm.org/confluence/display/CRMDOC/hook_civicrm_entityTypes).
### Add a unit-test class ### Add a unit-test class
Unit-testing is an invaluable to way to maintain quality-control over Unit-testing is essential to maintain quality-control over
your extension. When developing a test case for a CiviCRM extension, it your extension. When developing a test case for a CiviCRM extension, it
is useful to run the test case within an active, clean CiviCRM is useful to run the test case within an active, clean CiviCRM
environment. The CiviCRM/Civix testing tools will automate this – as environment. The combined CiviCRM `civix` testing tools will automate this as
long as you follow a few basic conventions. The following steps will long as you follow a few basic conventions.
create and run a test in your extension.
The following steps will create and run a test in your extension.
>> ![information](../img/info.png)
Before preparing unit-tests with extensions, you must first
[configure you personal testing sandbox](/confluence/display/CRM/Setting+up+your+personal+testing+sandbox+HOWTO) and enable your extension on the sandbox.
Before preparing unit-tests with extensions, you must first: Explore the full options with:
- Configure the test system for core CiviCRM. See [Setting up your ```bash
personal testing sandbox civix help generate:test
HOWTO](/confluence/display/CRM/Setting+up+your+personal+testing+sandbox+HOWTO). ```
- Ensure that the extension is enabled on the linked CiviCRM site
First, create a skeletal test-class. The class name should be placed in To create a skeletal test-class choose a class name in
your extension's namespace (*CRM\_Myextension*) and should end with the your extension's namespace (*CRM\_Myextension*) that ends with the
word *Test*. word *Test*:
```bash ```bash
civix generate:test civix generate:test CRM_Myextension_MyTest
``` ```
This creates a new directory and a new PHP file: This creates a new directory and a new PHP file:
...@@ -592,17 +606,31 @@ This creates a new directory and a new PHP file: ...@@ -592,17 +606,31 @@ This creates a new directory and a new PHP file:
To make sure you can run the test civix needs to know where the CiviCRM To make sure you can run the test civix needs to know where the CiviCRM
base install is: base install is:
To run this test-class, change to your extension folder and call "civix The skeletal test class does not do anything useful. For more details on
test":
```bash
civix test
```
The skeletal test class doesn't do anything useful. For more details on
how to write a test class: how to write a test class:
- Read [PHP Unit Manual: Writing Tests for - Read [PHP Unit Manual: Writing Tests for
PHPUnit.](https://phpunit.de/manual/current/en/writing-tests-for-phpunit.html) PHPUnit.](https://phpunit.de/manual/current/en/writing-tests-for-phpunit.html)
- Review the example code in - Review the example code in
[org.civicrm.exampletests](https://github.com/totten/org.civicrm.exampletests) [org.civicrm.exampletests](https://github.com/totten/org.civicrm.exampletests)
>> ![danger](../img/danger.png)
The following instructions are deprecated. Updated instructions coming soon.
```bash
# Check if civix can connect to the civi api
civix civicrm:ping
# Look at your current config
civix config:get
# Tell civix where to read the civicrm.settings.php
# EG. For Drupal
civix config:set civicrm_api3_conf_path /your/path/to/sites/default
```
To run this test-class, change to your extension folder and call "civix
test":
```bash
civix test CRM_Myextension_MyTest
```
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