Custom module templates and lang files

Learn how to override module template files and work with language files in CMSMS 

Scroll down for more details

Most modules for CMS Made simple have an admin panel where administrators can manage the module's data,  and adjust module settings.  The forms and reports provided in the module's admin panel use smarty templates that are shipped as files within the module's directory.   It is not difficult to override these templates.

Module templates can be found in (starting from your CMSMS root path) /modules/MODULE_NAME/templates (cmsms <= 2.3).  Though these files should never be modified, as they will be overwritten the next time you upgrade the module,  it is possible to copy these files to /assets/module_custom/MODULE_NAME/templates. If this is the first time working with overriding templates you will need to create this directory structure.

As an example, lets add some simple static text to the GBlog add/edit article template to aide bloggers who have admin access.   By looking at the files in /modules/CGBlog/templates we see that editarticle.tpl is the file that contains the admin form for adding an editing an article.   So first we must ensure that the directory structure exists, and copy the template.

mkdir -p assets/module_custom/CGBlog/templates
cp modules/CGBlog/templates/editarticle.tpl assets/module_custom/CGBlog/templates

Now we can edit this file, and add our bit of help text.   Using our favorite editor (I like emacs) we can just add some text to the top of this file.  Something like:

<div class="information">{$mod->Lang('my_admin_helptext')}</div>

Now.  there is quite a bit to understand in his single line of HTML text.

  • Firstly, we create a div and assign it the "information" class.  Since this is a template used in the CMSMS admin panel, the admin theme is responsible for styling.   The CMSMS admin theme knows to style a div with this class nicely.
  • Next we call the Lang method of the current module, which in this case will be CGBlog and provide it with the key my_admin_helptext.
    All CMSMS modules have a Lang() method to enable translation.  The 'my_admin_helptext' is a key to be used in conjunction with the current language, and the module name (in this case CGBlog) to find the correct text to place there.

If you now visit the CGBlog module's admin panel and click on 'Add article' you will see that indeed a new div is placed there, that looks something like:  


Now.  Notice that CMSMS is complaining about a 'missing lang string'.  This is true, because we have not defined any text for the 'my_admin_helptext' key in ANY language.  That is the next step.

CMS Made Simple allows extending and overriding lang strings for any module by placing files in the /assets/module_custom/MODULE_NAME/lang directory.    Here you can override the text that was provided by the module for any key or keys that you wish, but you may also add your own keys for use in your overridden templates.   We can also provide translations for any language key in any language that CMSMS understands.   Let us create some text for the 'my_admin_helptext' key in both English and Dutch.

First, let us create the file /assets/module_custom/CGBlog/lang/en_US.php and add this text:

$lang['my_admin_helptext'] = 'Reminder: Use the preview feature to review your article before saving it';

This is a PHP file,  that is defining an associative array named $lang.  The key for the one element (so far) in this associative array is the same key we use in the call to $mod->Lang(). Now, if we click on the 'Add article' link in the CGBlog admin panel, we will see our text.   All is good.  But some of our editors use dutch, so lets ensure we have that text in dutch too.  Create the file /assets/module_custom/CGBlog/lang/nl_NL.php and add this text:

$lang['my_admin_helptext'] = 'Herinnering: gebruik de preview-functie om uw artikel te beoordelen voordat u het opslaat';

Please don't comment on the quality of the translation.  I don't speak or read Dutch, so I used google translate :)

With respect to translations,  CMSMS will always read an English file first, and then look for language files in the current language (if it is different).  This ensures that at a minimum the English text will be displayed if a key has not been translated to the current user language.

So,  there we have it.  We have demonstrated that we can override file based templates provided by CMSMS modules and either fix things or add content.  We have also demonstrated how we can add new language strings, and translate them to various languages.   

This will help with the application building process.  It will work with all file based templates from modules, whether they be used on the front-end or back-end.   And work for language strings on the front end or back-end of the application.  None of your changes in /assets/module_custom will be touched when you upgrade modules.

Note:  There is a slight difference for CMSMS version 2.3 and beyond.  In Version 2.3 core modules can be located below /lib/modules and third party modules can be located in /assets/modules.   So you need to look in these locations to find the templates to override.   CMSMS Version 2.3 is still in beta at the time of writing this article.