Displaying your Pages

Smarty Templates

All HTML rendered within Form Tools - the theme pages, modules, emails, everything - is done with Smarty. For our usage, Smarty templates are just HTML files with a .tpl extension, that contain special Smarty logic which process variables passed to the template.

Smarty templates are called from your PHP using the ft_display_module_page helper function. This function abstracts away all the fussy details, providing your templates with a wide range of information about the environment, user, sessions and so forth. To understand how the Smarty templates are rendered, I'd recommend reading these sections:

• Anatomy of a Module: index.php
• Helper Functions: ft_display_module_page()

Themes and CSS

Each theme can render the UI in any number of ways. But theme developers only ever edit the templates, CSS and Javascript within their own theme folder. It would be unrealistic to expect them to edit the presentation layer for all modules, too. So to account for this, module pages are rendered within a module wrapper defined by the theme designer. This is actually very simple. All your templates should include the modules_header.tpl and modules_footer.tpl files, like so:

{include file='modules_header.tpl'}

Your HTML here.

{include file='modules_footer.tpl'}

It's the theme designers job to develop that wrapper so that your HTML appears in the appropriate spot.

Now, since every theme presents the information in different ways, you need to keep this in mind when writing your HTML. NEVER rely on CSS defined in your theme folder: that's custom to that particular theme and probably won't exist for others.

The CSS rules you can rely on being available are stored in your /global css/main.css file. These rules are imported for all themes so you can rely on them being there.

You can, of course, defined your own stylesheets to contain whatever CSS you wish. If you do, we strongly recommend keeping things simple and generic to increase the likelihood of being visually compatible with whatever theme is selected by the administrator.

Language Compatibility

As mentioned in the discussion of the module language files, Form Tools modules are designed support multiple languages. The way this works is actually quite simple: all language strings that appear in the user interface and code are stored in a separate language file. This is a PHP file, located in the module's /lang folder. Every time a page is rendered, it automatically loads the appropriate language file for use in your code.

But extracting the strings into your language file is only half the battle. Here's a few other things to keep in mind. This list is FAR from complete and will be expanded upon in later versions of the doc.

Spacing

This is very obvious, but it's easy to forget: just because a word is short in English, doesn't mean it's going to be short in other languages. Try to keep this in mind when developing your templates. Rather than using fixed widths for table columns, you might want to consider adding a "nowrap" class and padding to the string so the text doesn't get jammed up together. That way, the templates stay fairly flexible and can accomodate strings of different lengths.

Language Strings Placeholders

Often you may need to embed something dynamic within a string. e.g. "You have X settings to complete". In different languages, "X" may appear in different places so you can't simply separate the string into two ("You have" and "settings to complete") then construct your string by concatenating the values.

Instead, embed Smarty variables into your strings. Here's how it works. First, in your language file, add your string like so:

$L["phrase_num_settings_to_complete"] = "You have {\$num_settings} settings to complete.";

Note that the $ in $num_settings is escaped with a preceding \ dash. This prevents it being interpreted as PHP.

Next, in your PHP you can use the Form Tools core function ft_eval_smarty_string  to replace the Smarty variable $num_settings with the value you need to insert.

$placeholders = array("num_settings" => 5);
$string = ft_eval_smarty_string($L["phrase_num_settings_to_complete"], $placeholders)
echo $string; // "You have 5 settings to complete."