Skip to content
Snippets Groups Projects
Commit 298b621f authored by colemanw's avatar colemanw
Browse files

Misc updates to extension/api docs about the recent xml -> entityType.php migration

parent 125feefc
No related branches found
No related tags found
No related merge requests found
Hide whitespace changes
Inline Side-by-side
Showing
with 40 additions and 67 deletions
docs/afform/form-builder.md
+ 5
− 46
View file @ 298b621f
Form Builder provides a flexible form interface allowing editing a variety of CiviCRM entities as well as a developer interface.
## Extending Form Builder
## Exposing an entity to Form Builder
### Via event listener
The Form Builder GUI can be extended via the [`civi.afform_admin.metadata`](afform-events.md) event.
This event is used for adding entities, elements, input types, etc.
### Via an entityType declaration file
### Via an Afform entityType declaration file
It is also possible to expose entities in Form Builder by adding a declaration. To do this:
......@@ -35,47 +35,6 @@ return [
[Core afform entities](https://github.com/civicrm/civicrm-core/tree/master/ext/afform/admin/afformEntities) have examples of other parameters that can be added such as `repeat_max`, `unique_fields`, `boilerplate`, `icon`, `alterFields`, and `data` defaults. Be sure to test them out to see what works best with a custom entity.
!!! tip "Making fields available for use in Form Builder"
If an expected element for an Entity is missing from Form Builder, it's likely that the `<html><type>` needs to be added to the xml file for that Entity so that Form Builder can render it.
## Via XML declaration
The beauty of FormBuilder is that any changes that are presently made in your XML file will be integrated directly into FormBuilder after a regeneration of the boilerplate. This is also the forward direction of CiviCRM.
1. Modify you XMl entity declaration at ```yourextension/xml/schema/CRM/yourclassname/EntityName.xml```
2. Within the ```<field>``` declaration you will want to add a ```<html>``` declaration, which essentially tells FormBuilder how to display this field (works also for FormBuilder filters). One example is the AcitivtyContact entity [here](https://github.com/civicrm/civicrm-core/blob/master/xml/schema/Activity/ActivityContact.xml) or other examples [here])(https://github.com/civicrm/civicrm-core/blob/master/xml/schema/)
3. After the modification you need to rerun ```civix generate:entity-boilerplate```, which will update your DAO automatically
4. Flush your system cache
5. Now all the new fields that you have added will just work in FormBuilder and Searchkit
<details><summary>Examples of HTML fields</summary>
```xml
<html>
<type>EntityRef</type>
<label>Created By</label>
</html>
```
```xml
<html>
<type>Number</type>
</html>
```
```xml
<html>
<type>CheckBox</type>
</html>
```
```xml
<html>
<type>Text</type>
</html>
```
</details>
## Hot tips
+ If you receive an error when attempting to regenerate your boilerplate then you will need to perform a ```civix upgrade``` and then retry ```civix generate:entity-boilerplate```
+ Always clear your cache after your have modified the boilerplate as your changes will not appear
If an expected element for an Entity is missing from Form Builder, it's likely that `input_type` needs to be added to the field.
Find the `getFields` function in the corresponding `.entityType.php` file for that Entity and add an appropriate input type.
(for older entities using legacy xml schema files, the corresponding tag would be `<html><type>` and the code generator script would need to be run after updating).
docs/api/index.md
+ 6
− 5
View file @ 298b621f
......@@ -9,6 +9,7 @@ Extensions can provide additional API entities or functionality. For help creati
!!! tip "Why Use the API"
The API is superior to executing raw SQL or calling internal CiviCRM functions, because it offers consistency and stability.
It is designed to function predictably with every new release so as to preserve backwards compatibility when changes to the schema and BAO functions inevitably occur.
Using the API also ensures all hooks and events are dispatched, allowing CiviCRM business logic and 3rd party integrations to function properly.
The best place to begin working with the API is your own *test* install of CiviCRM, using the API Explorer.
......@@ -22,7 +23,8 @@ available actions and their parameters, and will write API code for you. To acce
2. Within the CivCRM menu, go to **Support > Developer** and either **API Explorer v4** (URL `/civicrm/api4`) or the legacy **API Explorer v3** (URL `/civicrm/api3`).
!!! warning
The API Explorer executes real API calls. It can modify data! So if you execute a `Contact` `delete` call, it will really delete the contact. As such, any experimenting is best done within a test site.
The API Explorer executes real API calls. It can modify data! So if you execute a `Contact` `delete` call, it will really delete the contact.
As such, any experimenting is best done within a test site.
To get started, select an entity, for example `Contact` and an action to perform, for example `Get`.
Use the GUI to select additional parameters to configure your API call; as you do, the API Explorer will generate code
......@@ -33,9 +35,8 @@ which you can copy & paste into your PHP, Javascript, REST or CLI application.
CiviCRM's API has major versions which are independent of the CiviCRM version. The API version increments more slowly in order to maintain stability within the extension ecosystem.
Typically, two versions of the API are maintained concurrently to allow gradual transitions. New releases of CiviCRM may add features to the API but will not break backward-compatibility within an API version.
- **APIv4** is the current stable version, with new features being actively developed.
- **APIv3** is now minimally maintained with no new features and regression bug-fixes only.
- [**APIv4**](v4/usage.md) is the current stable version, with new features being actively developed.
- [**APIv3**](v3/usage.md) is minimally maintained with no new features and regression bug-fixes only.
Your code can use a combination of v3 and v4 API calls, but v4 is recommended for all new projects.
Although there are no plans at the time of this writing to remove APIv3, [upgrading existing code](v4/differences-with-v3.md) to use APIv4 is a good way to future-proof extensions.
......@@ -46,4 +47,4 @@ All important changes made to the API are recorded in [APIv3 changes](v3/changes
## Entity Relationship Diagrams
To make better use of the API, it can be helpful to have a visual understanding of the relationship between entities available in the API. Entity Relationship Diagrams illustrating many of these are available [here](ERDs/index.md) as supplementary documentation to the API Explorer.
\ No newline at end of file
To make better use of the API, it can be helpful to have a visual understanding of the relationship between entities available in the API. [Entity Relationship Diagrams](ERDs/index.md) illustrating many of these are available as supplementary documentation to the API Explorer.
\ No newline at end of file
docs/api/v4/actions.md
+ 5
− 0
View file @ 298b621f
......@@ -70,3 +70,8 @@ along with some _metadata_ actions to retrieve information about the structure o
Fetch the list of fields supported by the entity, including [custom fields](custom-data.md).
Optionally load the [option-lists](pseudoconstants.md) for fields.
## Other Entity-Specific Actions
Some entities provide extra actions. For example, `Afform::submit` or `SearchDisplay::run`.
To discover all available actions for an entity, use the `getActions` API action.
\ No newline at end of file
docs/extensions/civix.md
+ 1
− 1
View file @ 298b621f
......@@ -24,7 +24,7 @@ civix help civicrm:ping
## Generate a skeletal extension {:#generate-module}
To generate a skeletal extension module, we will use `civix generate:module` and pass in the name for our extension. See [here](index.md#extension-names) for details of naming conventions.
To generate a skeletal extension module, we will use `civix generate:module` and pass in the name for our extension. See [Extension Names documentation](index.md#extension-names) for details of naming conventions.
Start with:
......
docs/extensions/index.md
+ 5
− 4
View file @ 298b621f
......@@ -17,11 +17,12 @@ This section covers how to write extensions.
## Extension Names
Pick a unique single word for your extension's name. Note that this name is used throughout the extension's code, e.g. function names, so it should only include characters that can be safely used in that way.
Pick a unique `snake_case` name for your extension. Note that this name is used throughout the extension's code, e.g. function names, so it should only include alphanumeric characters and underscores.
This name should be unique in the [CiviCRM Universe](../tools/universe.md), so check [civicrm.org/extensions](https://civicrm.org/extensions) to ensure the name isn't already in-use.
!!! info "Legacy naming"
Historically, extension names used to follow a convention like Java packages – they looked like reversed domain names. (e.g. `com.example.myextension`), but this is no longer the recommendation.
``` info
Historically, extension names used to follow the same convention as Java package names – they look like reversed domain names. (e.g. `com.example.myextension`), but this is no longer the recommendation.
```
## Pre-Requisites
......
docs/searchkit/queries.md
+ 2
− 0
View file @ 298b621f
......@@ -5,6 +5,8 @@
Any APIv4 entity can be made available to Search Kit. Even nontraditional entities that do not
correspond to a SQL table will work as long as they have a `get` action.
## Searchability
Whether an entity appears in Search Kit depends on the `@searchable` annotation at the top of the API entity class
(if not present the entity defaults to "secondary"):
......
docs/standards/entity.md
+ 3
− 1
View file @ 298b621f
......@@ -5,4 +5,6 @@ The following standards apply to entities in CiviCRM:
1. Declare entities via an `.entityType.php` file.
2. Give each entity a `title`, `title_plural`, `icon` and `description`.
3. Give each field a `title` and `input_type`.
4. Whenever possible rely on the `CiviMix\AutomaticUpgrader` to install & uninstall tables without writing any sql.
\ No newline at end of file
4. Whenever possible rely on the `CiviMix\AutomaticUpgrader` to install & uninstall tables without writing any sql.
Further documentation is found in the [CiviCRM Entities](../framework/entities/index.md) chapter.
\ No newline at end of file
docs/standards/php.md
+ 6
− 8
View file @ 298b621f
......@@ -21,20 +21,18 @@ class CRM_Coding_Example implements CRM_Coding_ExampleInterface {
* @return bool
* Whether the operation succeeded.
*/
public function expandFile($file, $power) {
$keyValuePairs = array(
public function expandFile(string $file, int $power): bool {
// Comments start with a capital letter and end with punctuation.
$keyValuePairs = [
'first' => 1,
'second' => 2,
);
];
if ($power < 4) {
echo "You got it, boss.\n";
}
elseif ($power < 10) {
echo "Whoa, that's gonna be a big file!\n";
echo ts('You got it, boss.');
}
else {
echo "Whoa, that's gonna be a really big file!\n";
echo ts("Whoa, that's gonna be a big file!");
}
for ($i = 0; $i < $power; $i++) {
......
docs/step-by-step/create-entity.md
+ 6
− 1
View file @ 298b621f
......@@ -234,10 +234,15 @@ Now it is time to update the template in `templates/CRM/Myentity/Form/MyEntity.t
## 8. Integration with Search Kit
When we generated the entity it also generated an APIv4 class. This automatically made the entity available in Search Kit.
What it did not do is include links to add, edit or delete the entity. (See [Search Kit - Links](../../searchkit/tasks/#links) for an explanation).
!!! tip "SearchKit Placement"
By default, SearchKit places most entities in the secondary list (behind the "Other..." expander). To promote your entity to the primary list,
or to hide it altogether from SearchKit, [adjust the `@searchable` annotation](../searchkit/queries.md#searchability) in the APIv4 class.
What it did not do is include links to add, edit or delete the entity.
To do this we need to add the links metadata to the entity. Open `schema/MyEntity.entityType.php` and add a `getPaths` callback
if it's not already there, and populate it with the paths at which your forms can be found.
See [Search Kit - Links](../../searchkit/tasks/#links) for more details.
## 9. Add a search
......
docs/tools/index.md
+ 1
− 1
View file @ 298b621f
......@@ -14,7 +14,7 @@ When you install [buildkit](buildkit.md) you'll get all these tools.
* `cv` - command is a utility for interacting with a CiviCRM installation
* *documentation: run `cv list`*
* *[repository](https://github.com/civicrm/cv)*
* `civix` - Generate skeletal code for CiviCRM extensions
* `civix` - CiviCRM extension code generator
* *[documentation](../extensions/civix.md)*
* *[repository](https://github.com/totten/civix)*
* `civistrings` - Scan code for translatable strings (*.pot)
......
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