Lexicon Strings for Permission Descriptions

Almost two years ago, I wrote a post on using Lexicon Strings for text displayed in the Manager. I recently ran into a problem while trying to use a Lexicon string for the description of a custom permission. I thought I’d share the solution in case someone else runs into the same problem.

MODX Lexicon Strings

First, a little background on Lexicon Strings in MODX. In order to internationalize MODX, all messages and prompts in MODX, and in all properly written Extras, are stored as “Lexicon Strings”.

When the Login form is shown, for example, a page with the language set to “en” will display the word “Password” as a prompt. If the language is set to “fr”, it will say: “Mot de passe” instead. Neither is contained in the Tpl Chunk used for the Login page.

Where that prompt is meant to appear, there is a language tag in the HTML code: <fixedpre>[[%login.password]]</fixedpre>. When MODX sees this language tag, it checks the currently loaded Lexicon, or more correctly, the Lexicon cache. Hopefully the Lexicon cache matches the language of the current user. MODX looks for the “login.password” key, and if it finds the key, the tag in the form is replaced by the value associated with that key.

In case you’re curious, the origin of the French version of that string is this file: core/components/login/lexicon/fr/default.inc.php, and it looks like this:

$_lang['login.password'] = 'Mot de passe';

That file contains all the Lexicon Strings used by the Login form for prompts and error messages. The login class code loads that language file with a call to modx->lexicon->load('login:default').

The Problem

The method above is fine if you have a place for a language tag, and some code to create that tag. But what if you’ve created a custom permission to add to an Access Policy Template? The description of the permission will be shown when you edit the Policy Template and again when you edit a Policy based on that Template. You can’t use a language tag, because you don’t know what language will be used, and no code of yours will be running that could inject the correct description.

When you create the access Policy and Policy Template, there’s an input field called “Lexicon”. This is where you tell MODX to look for the Lexicon Strings. The usual entry in that field is “permissions”, but there’s a catch. Because we’re in the Manager, MODX looks for the Lexicon String in the core namespace (and doesn’t find it).

I had this issue recently with the NewsPublisher Extra. NewsPublisher has a custom access policy, which is a duplicate of the Administrator Policy with an added permission with the key np_allow_modx_tags.

I put the language string in a Lexicon file called permissions.inc.php in the core/components/newspublisher/lexicon/en directory (and created parallel files for 'fr', 'it', 'de', 'ru' versions).

Here’s the en file content

$_lang['np_allow_modx_tags_desc'] = 'Allow editing Resources with MODX tags using NewsPublisher.';

I put permissions in the “Permissions” input field for the Policy Template and Policy, and np_allow_modx_tags_desc in the “Description field” for the permission, but MODX just showed that key instead of the description.

I figured I needed to tell MODX to look in the newspublisher namespace, so I changed the permission entry from permissions to newspublisher:permissions.

MODX found and displayed my permission description correctly, but with a horrible side effect. MODX didn’t find the descriptions for all the other permissions in the policy! It displayed just the Lexicon key for each of them.

The Solution

The trick was to create entries for my custom permission in the MODX Lexicon table in the database (but, again, with a catch).

In the old days, if you wanted to modify a Lexicon String, you had to find the correct Lexicon file and make your changes there. The changes were all overwritten every time you upgraded, and you had to redo it. In MODX Revolution, however, the strings are still in the files, but if you change the strings properly, the new version is stored in the MODX database, where it will survive any upgrades.

When MODX loads a set of Lexicon strings into the Lexicon cache, it first gets all the strings from the file(s). Then it looks in the database for Lexicon String overrides. If you look in the <fixedpre>modx_lexicon_entries</fixedpre> table in the MODX database, you can see all the existing overrides. If you haven’t changed any strings yet, you may not see any.

When you go to System (gear icon) -> Lexicons in the MODX Manager, you will see all of the original and modified strings. If you look at the grid there, you’ll see three columns. The first two are “Name” and “Value”. The “Name” field is the Lexicon key used in language tags or in code that gets a Lexicon string. The “Value” field is what will be shown on the screen. The right-hand column, “ast Modified On”, tells when the string was last modified.

Entries that are either modified or added in Lexicon Management are shown in green. The green entries are stored in the database and will override ones that exist in Lexicon files. Unlike the ones in the Lexicon files, they will also survive upgrades to MODX or any Extras.

Creating New Lexicon Strings

Go to System (gear icon) —> Lexicons. Click on the “Create Entry” button, then set the correct Lexicon key (Name) Namespace, Topic, Language, and value (the string you want displayed). In our case the Topic will be permissions and the language will be the two-letter code for the language. Here’s the catch: the “namespace” has to be core because that’s where MODX will be looking for the Lexicon String for a permission description.

Just set the values of the five fields, and click on the “ave” button.

Changing Lexicon Strings

You can change the values of your custom entry (or any other entries) very easily. Just double-click on the Value you want to change and edit it. After editing the string, be sure to click somewhere else on the page, or it won’t be updated. Reload the page, and navigate to the namespace and topic of your entry. The line with your string should now be displayed in green, which shows that it overrides an existing Lexicon file entry and is stored in the database. Remember that your changes will survive upgrades of MODX or any Extras.

You may have to clear the MODX cache, and sometimes your browser cache to see the change in the Manager.

Coming Up

The technique above is time-consuming, and can get tedious if you have many languages. If the permission description is part of an Extra that you will release, writing out the instructions for doing it will be painful, and your users are not going to enjoy doing all this work just to display a language-sensitive permission description. In my next article, we’ll see how to perform all the steps in the code of a resolver for your Extra, so no one has to do the process by hand.

---

Bob Ray is the author of the MODX: The Official Guide and dozens of MODX Extras including QuickEmail, NewsPublisher, SiteCheck, GoRevo, Personalize, EZfaq, MyComponent and many more. His website is Bob’s Guides. It not only includes a plethora of MODX tutorials but there are some really great bread recipes there, as well.