System Setting Lexicon Strings in Transport Packages

Handling lexicon strings for System Settings in a transport package.

In the last article, we saw how to compare entire directories in PhpStorm. In this one, we'll look at how to handle lexicon strings for System Settings in transport packages.

MODX logo

When you create a transport package for a MODX extra, you may end up creating some new System Settings. This is especially true of CMPs and widgets, because you can't assign property sets to them. If your widget is a snippet-type widget, it will have default properties, but if a user changes them, the user's changes will be overwritten when they upgrade the extra. The two usual ways around this, properties in the snippet tag and a separate property set, are not available because there's no tag and no way to attach a property set to a widget.

The most practical alternative, then, is to create System Settings for the CMP or widget. Being a good citizen, you'll want to internationalize your extra, which means creating lexicon strings for it.

How MODX Handles Setting Lexicon Strings

We'll use System Settings as an example here, but the concepts apply to all settings, including User Settings, Context Settings, and Usergroup Settings.

The way MODX handles lexicon strings for System Settings in transport packages is very strange. It's unlike its handling of other lexicon strings.

When you create a new System Setting in the Manager, the form includes a name input field and a description input field. Seeing this, you'd expect to find both those fields in the database in the modx_system_settings table, but neither one is there.

Instead, when you save the new System Setting, MODX creates two lexicon entries for those fields. Say you've entered my_setting as the key, Setting1 as the name and Description of setting one for the description. MODX will save the key field as is, then it will create these two records in the modx_lexicon_entries table:

name                           value
setting_my_setting             Setting1
setting_my_setting_desc        Description of setting one

The first line above is the lexicon string for the name field. The second is for the description field. Other fields in those records will contain the namespace, topic, and language, as well as the createdon and editedon dates.

When MODX displays your new System Setting in the System Settings grid, it gets all the lexicon entries from the namespace and topic in the current manager language (if there are none in that language, it looks for a lexicon file in the namespace path). In the Name field for your new System Setting, it displays the value from the first entry above in the Name input field, and the value from the second one in the Description input field.

If you update either value and save the setting, MODX updates one or both lexicon entries.

What About My Transport Package?

There are many ways to go wrong in creating the lexicon strings for settings in a transport package. The secret is to remember that MODX treats the entries there just like it treats the input fields in the Manager.

For the example above, a transport.settings.php file would contain something like this:

'key' => 'my_setting',
'value' => 'whatever',
'xtype' => 'whatever',
'namespace' => 'MyNamespace',
'area' => 'whatever',
'name' => 'Setting1',
'description' => 'Description for setting one',

Notice that the longer lexicon keys, prefixed with setting_. do not appear here. They do appear, though, in the lexicon file, which should have these entries in the default topic file:

$_lang['setting_my_setting'] = 'Setting1';
$_lang['setting_my_setting_desc'] = 'Description of setting one';

What if I'm Using MyComponent?

MyComponent makes this relatively easy. You can put the settings in your config file, but for me, that often leads to problems because I forget what is supposed to go there.

The easy (and more reliable) way is to just create the System Settings in the Manager. Put the name of each setting (in the manager language) in the name input field, put the description (in the manager language) for each setting in the Description input field, then save the setting. Be sure to put each setting in the project's namespace (create the namespace first, if necessary). When you've finished creating the settings, launch MyComponent. Run Export Objects, then Lexicon Helper. MyComponent will create the correct transport file for the settings and add the correct lexicon strings to the lexicon file for you.

Steps for MyComponent

  1. Before Creating any System Settings run Import Objects to make sure everything is current
  2. Do *not* use '~~' anywhere
  3. Create your System Settings in the MODX manager as described in the paragraph above
  4. Run Export Objects
  5. Run Lexicon Helper

Coming Up

In the next article, we'll look at how to remove an entry from your browser's Most Recently Used (MRU) list.

Looking for high-quality, MODX-friendly hosting? As of May 2016, Bob's Guides is hosted at A2 hosting. (More information in the box below.)

Comments (0)

Please login to comment.