Megaphone Commons

# CiviCRM cheatsheet

### Custom Entities & Extensions

   * A new Entity (think: Contact, Event) can be added to CiviCRM via an extension

       * Use the `civix` [commands](https://docs.civicrm.org/dev/en/latest/extensions/civix/) to create the extension.

   * To create core fields on the new extension, edit the XML file of the extension. Reference this [guide](https://docs.civicrm.org/dev/en/latest/framework/database/schema-definition/) for the options.

    * To add custom fields on the new extension, follow this [guide](https://docs.civicrm.org/dev/en/latest/step-by-step/create-entity/#121-making-our-entity-available-for-custom-data). It is also helpful to read about [managed entities](https://docs.civicrm.org/dev/en/latest/api/v4/managed/) before tackling custom fields.

       * If you've already created custom fields/groups *not* on the custom entity, but on another entity that you would like to use in the extension, then you can export the CustomField from the APIv4 explorer and paste the results in a filed named `OptionValue_cg_extends_objects.mgd.php` within the *managed* folder of the extension (see detailed steps below).

   * You can include configured Search Kit searches and Form Builder forms in your extension.

       * _Search Kit_

         * Create, configure, and save your search and any desired displays

         * Go to **Support > Developer > API Explorer v4**

         * Set the Entity to *Saved Search* and the Action to *export* (You will need the id of the saved search, so if unknown, do a *get* first)

         * Fill in the id of the saved search and click **Execute**

         * On the upper right corner of the results box, change *View as JSON* to *View as PHP*

         * Copy the results

         * Paste the results in a new file named `SavedSearch_name-of-saved-search.mgd.php` within the *managed* folder within the particular extension's folder. Note that you might need to create the *managed* folder as `civix` does not generate it automatically, but if you created custom fields as noted above, then you will have already added it. Also make sure that you add `<?php` to the top of the file!

       * _Form Builder_

         * Create, configure, and save your forms

         * In the root folder of your extension, create an *ang* folder if it does not yet exist

         * Move the files (both the html and json) related to your form(s) from their default location into the ang folder of your extension

             * The default location, such as for WordPress sites is `/wp-content/uploads/civicrm/ang`

* See an [example of a custom entity](https://github.com/briennekordis/presentationEntity)

### Adding JavaScript to CiviCRM

  1. Create an extension

  2. Figure out the exact page on which you want to add JS.

        * add a `buildForm` hook within the myextensionname.php

        * set a breakpoint on a simple statement (`$var = 1`) within the hook, turn on the debugger, and then load the page. The breakpoint will be hit and then you can get the name of the page in question by looking at the value of the `formName` variable with your debugging environment.

  3. Within the main extension file, write an `if` statement. The condition should limit on what page the JS is run. Adding a second condition to specify the form's id allows for future protection in case the formName is duplicated.

`$formName === 'Page Name'` OR `$formName === 'Page Name' && $form->id === 1`

  4. Within the `if` block, add `Civi::resources()->addScriptFile('foo', 'bar.js');`

      * the first argument ('foo') is the name of the extension

      * the second argument ('bar.js') is the name of the file relative to the path of the extension

  5. In a new JS file within the extension, add the JS / JQuery

      * For JQuery, add the code within the `$()` of the following code block:

```

CRM.$(function ($) {

  $();

});

```

  6. For additional reference, see the [Resources Reference docs](https://docs.civicrm.org/dev/en/latest/framework/resources/)