Settings: Forms¶

The settings system has a lot of information about each setting -- name, data-type, default, help-text, etc. This is enough to auto-generate an admin UI for the settings.

Mixin¶

For extensions, you can enable the standard mixin (setting-admin@1).

civix mixin --enable=setting-admin@1

Doing this will:

Create a permission administer {myext}.
Create a route civicrm/admin/setting/{myext}.
Create a link in "Administer > System Settings" to "{My Extension} Settings"
Assign all settings from group=>myext to appear on the page.

This provides decent defaults. If you want to fine-tune, then you can override by doing the steps manually:

If you manually create permission administer {myext}, then your label/description takes precedence.
If you manually register route civicrm/admin/setting/{myext}, then your definition takes precedence.
If you manually configure the settings_page on a specific setting, then that setting will move to the other page. (To make a hidden setting, specify settings_page => [].)
If you manually add civicrm/admin/setting/{myext} to the menu, then your link takes precedence.
Additionally, there is experimental support for overrides in info.xml. (Respected by v1.0.0 but not guaranteed future.)
```
<civix><setting-page-title>My Custom Title</setting-page-title></civix>
```

Form Controller¶

The engine behind this page is a PHP-based form-controller, CRM_Admin_Form_Generic:

In the extension mixin (above), it implicitly loads CRM_Admin_Form_Generic.

In civicrm-core, many of the standard settings screens are explicitly based on CRM_Admin_Form_Generic.

<?xml version="1.0"?>
<menu>
  ...
  <item>
    <path>civicrm/admin/setting/preferences/campaign</path>
    <title>CiviCampaign Component Settings</title>
    <page_callback>CRM_Admin_Form_Generic</page_callback>
  </item>
  ...
</menu>

The purpose of this controller is to read the metadata and display a form UI.

In general, you should see Settings: Definitions for details about how to tune each setting.

There's one subtopic in the definition that is particularly important to the form-controller -- that is positioning.

Positioning¶

How does the form-controller decide when and where to display a setting? With the property settings_pages. Let's consider a few examples.

Explicit settings_page: Within a property definition, you can precisely set a location:
```
  'settings_pages' => ['campaign' => ['weight' => 10]],
```
This example will be displayed on the page civicrm/admin/setting/preferences/campaign. (Note how campaign matches.)

Its position within this page will be based on the weight (10).
Implicit settings_page: In an extension that uses settings-admin@1, there is an implicit rule that every setting in the extension (group=>myext) will be placed on its settings-page. The weight will be assigned automatically (with the first-setting having the lowest weight).

For core settings (civicrm-core.git:settings/*), there is no implicit mechanism. You must be explicit.
Empty settings_page: If you want to explicitly exclude a setting from any/all pages, then you can set:
```
  'settings_pages' => [],
```