Tutorial System Settings

Many of your projects will require MODX System Settings. System Settings are handled as Seed-Data -- this means that we can define any MODX object as a file and therefore version control it. Any MODX object can be defined as an array and Repoman will import it as a MODX object.

Add the Seed File(s)

To add System Settings to your Repoman project, add a file named modSystemSetting.php to your project's model/seeds/ directory (create this directory if it doesn't already exist).

Here is an example of some System Settings defined by the Gmarker Extra:

<?php
/*-----------------------------------------------------------------
 * Lexicon keys for System Settings follows this format:
 * Name: setting_ + $key
 * Description: setting_ + $key + _desc
 -----------------------------------------------------------------*/
return array(

    array(
        'key'  		=>     'gmarker.formatting_string',
        'value'		=>     '',
        'xtype'		=>     'textfield',
        'namespace' =>     'gmarker',
        'area' 		=>     'gmarker:default'
    ),
    array(
        'key'  		=>     'gmarker.templates',
        'value'		=>     '',
        'xtype'		=>     'textfield',
        'namespace' =>     'gmarker',
        'area' 		=>     'gmarker:default'
    ),
);
/*EOF*/

From the Seed-Data docs, the format for the seed data file names is this:

[ordering_prefix.]classname.[php|json]

We can add one or many objects to a single seed file. For example, you could create two separate files:

• model/seeds/formatting_string.modSystemSetting.php
• model/seeds/templates.modSystemSetting.php

The ordering_prefix can be used to help you identify each file, and you can use it to determine which file will get loaded first (files are parsed alphabetically).

xTypes

The xType determines what kind of form field will be visible when a user edits this setting in the manager. The most common are listed below:

• combo-boolean : stored values are 1 and 0; the GUI will display "Yes" and "No"
• textfield : standard text field
• textarea : standard textearea
• text-password : standard password field (input is masked)
• numberfield : used for entering numbers
• modx-combo-language : allows user to select a language
• modx-combo-template : allows user to select a template
• modx-combo-content-type : allows user to select a content type
• modx-combo-charset : allows user to select a character set
• modx-combo-rte : like the textarea, but with formatting controls
• modx-combo-context : allows user to select a context

There are others: Bob Ray has documented a full list of available xTypes.

Lexicon Translations

You should furnish translations of the names and descriptions of your System Settings. Create a file default.inc.php inside of lexicon/en/ (or substitute the appropriate language locale abbreviation). The naming convention for your lexicon keys is

• Name: setting_{system_setting_key}
• Description: setting_{system_setting_key}_desc

REMEMBER: each System Setting requires 2 lexicon entries!

Here is an example of the lexicon entries corresponding to the gmarker.formatting_string System Setting:

$_lang['setting_gmarker.formatting_string'] = 'Formatting String';
$_lang['setting_gmarker.formatting_string_desc'] = 'Assemble all the Template Variables so that when they are parsed they will contain a valid address that you could conceivably type into a Google Maps search field.';

Custom Seed Locations

If necessary, you can define multiple directories to contain your seed data. This can be useful, for example, if you need to use one set of data for development and a different data set for production. Your composer.json should define the appropriate path(s) for production:

"extra": {
   "seeds_path": ["model/seeds/prod"]
}

You can manually load the seed data in other directories by supplying a path to the --seeds_path argument.

System Settings Added by Repoman

When Repoman installs or updates a package, it automatically adds several of its own System Settings.

• {namespace}.core_path
• {namespace}.assets_path
• {namespace}.assets_url
• {namespace}.version

You do not need to add these System Settings to your project! These settings are required for Repoman to function: it manages them and their values automatically based on where your repo is located and the contents of your composer.json file.