Rikki

Each template bit can have variables passed into it by the backed PHP code, and these variables can be used by the template bit to control the display. Consult either the template editor or designer's mode guides (depending on your preference) to find out how to determine which variables are available to a template. As well as these local variables, you can access the various objects created by the IPS4 PHP framework. Variables are escaped It's important to note that by default, all variable values are HTML-escaped when you output them in templates. This is for security, and ensures you don't inadvertently output some malicious HTML that is then processed by the browser and displayed. If a variable $value contained: <strong>Example</strong> Then outputting it in a template like so: Here's the variable value: {$value} Would actually send: Here's the variable value: &lt;strong&gt;Example&lt;/strong&gt; This is safe for the browser to display. Bypassing this protection Of course, in some situations, you want the raw HTML to be output, and not escaped. To do so, you can use the raw modifier on the variable: Here's the variable value: {$value|raw} Warning Using this modifier on untrusted content is a security risk. You should not output raw user-supplied HTML unless it has been properly sanitized and you are certain it is safe. Content that comes from IPS4's rich text editor is safe to output with this modifier.

Standard PHP loop types are supported as HTML logic tags. Foreach {{foreach [expression]}} ... {{endforeach}} Expression is anything PHP would support in a loop. The variables the loop defines are available within the body of the loop: <ul> {{foreach $arrayOfItems as $id => $item}} <li>{$id}: {$item}</li> {{endforeach}} </ul> For {{for [expression]}} ... {{endfor}} For example: <ul> {{for $i = 0; $i < count( $arrayOfItems ); $i++}} <li>{$i}</li> {{endfor}} </ul> Breaking and continuing If you need to break or continue a loop, you can use the relevant PHP statement to do so. For example, using break: {{foreach $arrayOfItems as $id => $item}} {{if $id > 15}} {{break;}} {{endif}} {{endforeach}}

As mentioned in the first step, any valid PHP expression can be used in HTML logic tags. You'll often just be checking if an expression is true or false: {{if $value}} ... {{endif}} ...but there are many other possibilities. You can also use normal PHP functions in your expressions. For example, you may need to determine if an array has any items, so PHP's count function is appropriate: {{if count( $items ) > 0}} ... {{endif}} Consult the full PHP documentation for the functions and language syntax. Getting values from IPS4 You'll often need to compare values in the software in your expressions. For example, is a particular setting enabled, or does the current user have a member ID. While you can use the standard PHP approach to get these values, IPS4 contains a number of shortcut 'constants' you can use to simplify your logic. They are used like so: {{if settings.reputation_enabled}} ... {{endif}} Behind the scenes, this shortcut gets expanded to the PHP equivalent, meaning it gives you access to all of the available methods and properties of the object it translates to. The available shortcuts are: request Translates to \IPS\Request::i(). Access to the request variables. e.g. {{if request.some_param}} member Translates to \IPS\Member::loggedIn(). The member object for the current user. e.g. {{if member.language()->isrtl}} settings Translates to \IPS\Settings::i(). Obtains system setting values (by setting key). e.g. {{if settings.auto_polling_enabled}} output Translates to \IPS\Output::i(). The output object, containing the methods/properties the suite uses to output content. e.g. {{if count( output.contextualSearchOptions )}} theme Translates to \IPS\Theme::i()->settings. Access to the theme settings available for the currently-used theme. e.g. {{if theme.sidebar_position == 'right'}} cookie Translates to \IPS\\Request::i()->cookie. Access to the cookie object. e.g. {{if isset( cookie.hasJS )}} Consult the PHP framework documentation for the full range of properties and methods available for each class.

The most basic logic check is a simple if/else. This allows you to put HTML if a condition matches, or something else if it doesn't. The syntax is simply: {{if [expression]}} HTML to output if expression is true {{else}} HTML to output if expression was not true {{endif}} There's also an elseif tag which allows you to specify other conditions to check if earlier conditions didn't match. {{if [expression]}} HTML to output if expression is true {{elseif [expression]}} HTML to output if expression is true {{else}} HTML to output if other expressions were not true {{endif}}

What problem does HTML logic solve? In the IPS Community Suite, our templates are the 'view', i.e. how the data is rendered as HTML to the screen. However, basic HTML has no logic capabilities; what is in the HTML file is what is sent to the browser. In a complex application like ours, we need some way to make decisions about what is output. These decisions could potentially be made in the PHP backend, but that isn't appropriate in most cases; the backend should be focused on processing the data, while the view (our templates) control how the data is displayed. HTML logic allows us to make these decisions inside our templates. It mixes standard HTML with some special tags and flow-control statements, most of which are very similar to PHP. What other features do templates have? The result is that in one template, we can have logic that says output some HTML if a certain condition is met, or different HTML otherwise. We can also do loops on data, reducing repetition. We also have some special tags that call output plugins to transform values in some way (for example, to render dates from a timestamp). Basic syntax There's three basic types of syntax you'll see. We will explore these in more detail in later steps. Logic tags Double-curly parenthesis. Controls flow in a template. In these tags, the expressions can be any valid PHP expression. Some examples: /* Basic structure */ {{if $condition}} ... {{else}} ... {{endif}} /* Examples of other expressions */ {{if !$condition}} {{if ( $color == 'green' && $size == 'big' ) || $condition}} {{if count( $value ) > 2}} Variables Single-curly parenthesis. Outputs values passed into the template (or values from elsewhere, e.g. a loop). {$value} Output plugins Pass the provided value through the specified output plugin. {pluginName="value"}

The IPS Community Suite ships with a collection of our iconic emoticons, and from version 4.1 onwards, they are retina-compatible (meaning high-resolution versions are used on displays that support them). It's also possible to add new emoticons, either individually or as new sets, to customize your community. Emoticons are used either by clicking the emoticon button in the editor and clicking the emoticon you'd like to use, or by typing the short code, which is then converted to the emoticon on the fly. Managing existing emoticons To manage your site's emoticons, navigate to Customization -> Editor -> Emoticons in the AdminCP. The screen you'll see will show you the currently-installed emoticons: Underneath each emoticon is the code that users can type to use the emoticon; you can change this by editing the value and pressing enter (old posts will continue to show the emoticon correctly). To the right of the textbox is an HD indicator to let you know whether the emoticon has a high-res version. Users don't need to worry about this - they will automatically see the high-res version when compatible with their screen. An emoticon can be deleted by clicking the X in the corner. However, deleting an emoticon will remove the image from the server, meaning old posts that used it will show a broken image to the user. You can reorder emoticons simply by dragging and dropping them. You can also move them between sets in the same way. Finally, you can rename the emoticon set by clicking the icon in the title bar. By default, there's only one set (named Default), but if you have several, the name helps to identify them when the user browses the emoticon list in the editor. Adding new emoticons To add new emoticons to your site, click the Add Emoticons button in the header. You'll see the following: Simply drag and drop your emoticon images to the upload field to attach them. You can also choose whether to create a new group or add them to an existing group. Once you click Save and the emoticons have finished uploading, you'll be returned to the overview screen. Emoticon codes will have been added for each emoticon based on the filename, but you can edit these now if you wish. Retina emoticons To add HD versions of your emoticons, a special naming format is used. Simply add @2x to the end of the filename, making sure the rest of filename matches that of the 'low res' version. For example, if you're uploading an emoticon named smile.png, the high-res version should be named smile@2x.png. The software will automatically combine these two images into one emoticon for you.

A few global editor settings are available for you (as the administrator) to configure for your community. To edit them, navigate to Customization -> Editor -> Settings in the AdminCP. General settings Paste Behavior By default, in IPS 4.1 onwards, when a user pastes formatted content (that is, content copied from elsewhere that contains HTML formatting such as bold, italics etc.), a bar appears in the editor asking them if they would like to retain this formatting, or remove it and keep the plain text: Some administrators prefer that no formatted content is posted, and the Paste Behavior setting allows you to control this. Return Key Behavior By default, when the user presses the return key, a new paragraph is started (and there's there's a space between the new line, and the line above), in common with many modern web apps. However, some administrators prefer that when the return key is pressed, a simple line break occurs and the same paragraph continues (this is how IPB3 handled the return key, too). The Return Key Behavior setting allows you to control this. Advanced settings When a post is submitted, the post parser strips out certain HTML tags, attributes and values that are potentially undesirable for security or visual reasons. However, in some cases, you may want to alter this behavior and allow certain values through. The Advanced tab allows you to add exceptions for: CSS classnames By default, other than certain 'known' CSS classnames that IPS4 needs for things such as quotes, classnames in elements will be stripped out. If you need to retain certain classnames for editor plugins or buttons, you can add them here. Javascript controllers IPS4's Javascript framework allows for controllers to be defined on elements using the data-controller attribute. These are stripped out when posted. If you have a block that requires some Javascript controller, you can add an exception to allow it here. Allowed iframe bases By default, iframes are usually stripped from posts. However, if you have a need to allow them, you can add URLs here. If the URL of an iframe matches one listed, it will be allowed through the parser. Warning It goes almost without saying that you should be careful about what you add exceptions for on the Advanced tab. Allowing undesirable values through the post parser could lead to visual abnormalities, or worse, security issues.

If an existing CKEditor plugin isn't available that meets your needs, another alternative that may be suitable is to create a custom button. What can custom buttons do? Custom buttons allow you to create blocks of HTML that are inserted by clicking a button on the editor toolbar. The blocks you create can accept content that users can enter. Custom buttons don't have the capabilities of a full CKEditor plugin - they can't be dynamic or use Javascript, for example. But for formatting text the user enters, a custom button may be the best choice. Note: although custom buttons tend to be simple, we recommend you have knowledge of HTML, or seek assistance from our peer-to-peer forums. Creating a custom button To create a custom button, navigate to Customization -> Editor -> Toolbars. Click the Add Button button in the header, and then the Custom tab. The form you see has the following fields: Button title The title seen by users when they hover over the button in the editor Icon A small image file that will act at the button icon on the editor. For retina support, upload an icon twice as big as you'd like it to display; it will be resized down by the browser and therefore show high-res. Type Three types of content are supported, and they roughly mimic the three types of element display in HTML: Inline - used when the inserted HTML exists somewhere in a line of text. Does not create a new line for the content. Single line block - designed for single lines (e.g. headers), and puts the block on a new line Block - used for multiple lines, and puts the block on a new line Use option A custom button can optionally accept a value from the user (aside from what they can type as normal inside the block itself). This option will appear as a popup dialog when the user clicks the button in the editor, and the value they enter is passed into the block when it is rendered. With this field enabled, you'll see an additional setting: Option label The text shown to the user requesting a value for the option. HTML The actual HTML the button will render in the editor when used. Generally, any HTML is supported but it must be valid. Within this HTML, a couple of special tags can be used: {option} If the option is used, this tag is replaced with the value the user entered, as-is. {content} If your button will allow the user to type within the generated HTML, insert this tag where the user should be able to type. Click the Save button to create the button. Your icon will be shown on the Buttons Not On Editor toolbar, and from here you can drag it to your live toolbars and configure it as normal. Using custom styles We don't recommend using inline styles in your HTML, because it will be almost impossible for you to update later (posts are built at save-time, not display-time, so if you update a custom button, old posts won't reflect those changes). Instead, we suggest using classnames, and adding styles for those classnames in your custom.css theme file. This way, you can update the styles later, and old posts will also reflect the changes. An example Within this documentation we have tip boxes like this: Tip This is a tip This is a custom editor button we've created that is available to staff. Here's the configuration we used to create this button: Button title Tip Icon Type Block Use option No HTML <div class='docsBox docsBox_tip'> <div class='docsBox_header'>Tip</div> <div class='docsBox_body'> <div class='ipsType_richText ipsType_break ipsContained'> {content} </div> </div> </div> We then add these styles to our custom.css CSS file: .docsBox_header { padding: 5px 10px; color: #fff; font-weight: 500; font-size: 15px; } .docsBox_body { padding: 10px; font-size: 13px; line-height: 1.4; } .docsBox_tip .docsBox_header { background: #2E7D32; } .docsBox_tip .docsBox_body { background: #E8F5E9; } .docsBox_tip .docsBox_body .ipsType_richText { color: #1B5E20; }

Since the editor in IPS4 uses CKEditor, the full range of plugins is available for you to install. If there's an editor feature you wish you had, check out their plugin repository and see if a ready-made plugin is available. Note: Currently we only support plugins that add a button to the CKEditor toolbar. Please don't install plugins that add other kinds of functionality or they may cause problems for your community. Installing a CKEditor plugin To start, navigate to Customization -> Editor -> Toolbars in the AdminCP. Click the Add Button button, and from the next screen select the CKEditor Plugin tab. Note: The plugin you install needs to be compatible with the CKEditor version used in your current version of the IPS Community Suite. We display your current version on this form so that you can cross-check the compatibility with the CKEditor website. Next, choose the plugin zip file you downloaded, and then submit the form. If everything installed successfully, you will see the new button shown on the Buttons Not On Editor toolbar at the bottom of the management screen. You can now drag it to your active toolbars and manage it as normal. If plugin installation fails Occasionally, installing a CKEditor plugin won't work. This might be because: It doesn't add a button We currently only support editor plugins that add a button to the toolbar; other kinds of plugin aren't supported. It doesn't support the installed version of CKEditor Ensure the plugin you want to use supports the version of CKEditor used in the IPS Community Suite version you have installed Your CKEditor directory doesn't have write permissions The directory /applications/core/interface/ckeditor/ckeditor/plugins needs to be writable (CHMOD 777) in order to install plugins

Toolbars on the IPS4 editor are completely customizable - you can rearrange buttons or remove them entirely, and set permissions for which group can use which buttons. To manage the editor toolbars, navigate to Customization -> Editor -> Toolbars in the AdminCP. On the screen you'll see a dummy editor showing your current button configuration for desktop view. Responsive support IPS4 has a responsive theme, which means the same theme works on desktops, tablets and phones, and adjusts what it displays based on the available space. Naturally, on a desktop monitor you might want to show a full range on editing options, while on a phone you might just show the essential formatting choices. We facilitate this by offering three editor configurations that you can independently change, ensuring the appropriate buttons are shown depending on device. The tabs shown allow you to configure these sizes. Large = Desktop Medium = Tablet/Small Desktop Small = Phone Reordering editor buttons On the main screen, you see a dummy editor that shows you your current button configuration. At the bottom of the page is another toolbar that shows you the available buttons that you are not currently using. Drag and drop buttons between these two locations to add or remove them from your toolbars. Changes you make are available instantly to users. Changing button permissions To restrict areas in which a button is available or to whom it is available to, click the button you want to edit on the toolbar. You'll see a simple form: By default, buttons are available to "Everyone" and "Everywhere", but by toggling the checkboxes and selecting either groups or areas, you can change this here. Note: some buttons, such as bold, italics and underline, have old-style BBCode equivalents. Removing the buttons from the toolbar does not prevent these BBCodes from being used in content. Adding toolbars & separators You can also add new toolbars if you find the single toolbar doesn't offer enough space, and new separators if you want to keep buttons grouped by type. Simply click the buttons above the toolbar editor to add them. Separators can be dragged and dropped just like buttons once you have added them. Reverting changes to your editor If you want to revert back to the configuration that we provide when you install the software, click the Restore Default Configuration button at the top of the page. This resets all positioning and permissions on all editor sizes, not just the one you are currently viewing.

The IPS Community Suite uses a "What you see is what you get" (WYSIWYG) editor that allows for rich content in posts. Posts are composed visually - there's no longer any need to use old-fashioned approaches like BBCode. The editor we use is an extended version of CKEditor, the leading WYSIWYG web editor. As such, you have access to the wide range of plugins and themes available for CKEditor, and you can install them easily to use them in your community. We'll cover how to do that in later steps. In IP.Board 3, you could create custom BBCode/Media tags. In IPS4, this is now done by creating custom buttons in the editor, which is completely configurable.

The IPS Community Suite has built-in support for languages that use right-to-left text (including Arabic, Persian and others), and if you are creating a theme to share with others, you should ensure it is compatible with right-to-left display. Doing so is easy. RTL-specific CSS When RTL display is used, certain CSS properties need to be reversed; for example, if you position something left in LTR languages, when shown in RTL it would need to be positioned right instead. The global template in IPS4 always has the dir attribute specifying the text direction (the value is either ltr or rtl), and it is this attribute we can use to add direction-specific styles. Let's imagine you have some CSS in your theme like this: .yourClass { font-weight: bold; position: absolute; left: 15px; top: 15px; padding-left: 30px; } Some of these styles need to be separated out for RTL or the theme won't look right. So, by using the dir attribute on the html tag, what we instead need to write is: /* These styles are the same regardless of text-direction */ .yourClass { font-weight: bold; position: absolute; top: 15px; } /* LTR styles */ html[dir="ltr"] .yourClass { left: 15px; padding-left: 30px; } /* RTL styles */ html[dir="rtl"] .yourClass { right: 15px; padding-right: 30px; } That's it! RTL languages will now correctly position the element on the right-hand side of the screen, while LTR languages will show it on the left as expected. Whenever you use styles impacted by text direction, you should split them out in this way. RTL-specific icons The IPS Community Suite makes extensive use of FontAwesome icons. Some of the icons need to be flipped for RTL languages (such as arrows) and if you use the standard classnames (e.g. fa-caret-left), we automatically flip these so that they are correct for RTL languages. If you manually specify icons in your CSS classes using the unicode code, you will need to adjust them for RTL so that their opposite icon is used. For example, if you do this in your CSS: /* This uses the unicode for FA's 'angle-right' icon */ .nextLink:after { font-family: 'FontAwesome'; content: '\f105'; } You will need to change it to be: .nextLink:after { font-family: 'FontAwesome'; } html[dir="ltr"] .nextLink:after { content: '\f105'; } html[dir="rtl"] .nextLink:after { content: '\f104'; } Consider your Javascript This usually will not require any action. However, if you have any custom JavaScript which adds user interaction, consider if any changes need to be made. For example, if you have a menu which opens from the left, it may need to open from the right. If you are only using the UI widgets already in the IPS Community Suite, these already make all such considerations so no action will be necessary.

A theme can have resources associated with it; these are usually images, but can be any kind of resource you need. Some examples: Images Web fonts Video Resources for a theme are managed by navigating to Customization -> Themes in the AdminCP, and selecting Manage Resources from the dropdown menu for the relevant theme. You'll see a listing of all current resources in the theme. Note: This only applies if you do not have Designer's Mode enabled. If you have it enabled, you can manage your resources using normal folders and you don't need to upload them through the AdminCP. However, note that the method of referencing a resource file at the end of this step still applies even if you use Designer's Mode. Adding resources To add a new resource file, click the Add Resource button. The form displayed is relatively self-explanatory, aside from: Existing location Choose the appropriate location for your resource. If it's for the public side of the site, choose front, if it's for both the public and admin sides, choose global. Folder Files are grouped by type, much like you would structure files in a folder on a desktop. We recommend creating a new folder for your resources to keep them separate from the default resources we ship with the software. Using resources Because of the way uploaded files are stored by IPS4 (in that they could exist on a file system, or Amazon S3, or even in a database as a virtual file, and that's before introducing CDNs), there is no guaranteed URL for you to use to refer to your resource. Instead, you use a special template tag, which IPS4 replaces with the generated URL when the page is rendered. The format is: {resource="<folder>/<filename>" app="<app>" location="<location>"} <folder> is the folder name you created when uploading the image (or the existing folder name if you chose an existing folder). <filename> is the original filename of the file you uploaded, with extension. <app> is the associated application (almost always will be core), and <location> is one of front, admin or global. You can also find the tag you need for your resource by locating it in the table of existing resources (see the start of this step). The template tag can be used in both templates and CSS files, and is simply replaced with a URL. That means you would use it like so: HTML: <img src='{resource="myfolder/myfile.png" app="core" location="front"}' alt='My file'> CSS: body { background: url( {resource="myfolder/myfile.png" app="core" location="front"} ); }

Theme settings are a way to set up variables that your theme can use, and which offer an interface to be customized via the AdminCP. For example, the default IPS4 theme stores most of its color choices as theme settings, and it's this which facilitates the easy mode editor. Theme settings are particularly useful when you plan to distribute your theme for others to use, but you may also find uses even if a theme is for your own use. For example, you might occasionally have a banner at the top of your site about some upcoming event. Instead of constantly editing your templates to add/change/remove this message, you could set up a couple of theme settings - one to show/hide it, and another containing the text. IPS4 supports a wide range of field types for theme settings, opening up some innovative possibilities for your custom themes. Managing theme settings Note: Theme settings can only be managed using Designer's Mode. Ensure that mode is enabled before continuing. Theme settings are managed by navigating to Customizations -> Themes in the AdminCP, clicking the dropdown menu beside the theme you want to edit, and selecting Custom Settings. The screen you see shows the current theme settings for this theme. You can drag and reorder the settings by grabbing the drag handle to the left of each row, or edit/delete the setting using the buttons to the right. Theme settings can be grouped, and the groups are shown as tabs at the top of the table. Creating theme settings To create a theme setting, click Add Setting at the top of this screen. You'll see a popup window: Title language key Theme settings need to be language-abstracted, since they can be shown in other languages if a language pack is used. Therefore, instead of entering an English name for this setting, you enter a language key, and then create that language phrase. Since you're in Designer's Mode, a language file named lang.php will be created in the theme directory, so you should create your language phrase in that file, and enter the key in this field. For application The associated application for this setting; this will be Core in almost all situations. Key The key is how your theme setting will be referenced in templates & CSS files, so it's a good idea to pick something simple but clear. Tab type This controls the grouping of the setting. If you want to add the setting to an existing group, select it from the next setting; otherwise, choose New Tab and enter a name in the text field that appears. Type This determines the field type the setting will use, and therefore how admins will choose a value when they edit the setting. Default value The field type you choose will determine what fields are shown, so fill them in as necessary. The Default Value field is shown for all field types, and determines what value this setting will have if the admin doesn't change it. Note: for the Color field type, the value you enter should be a hexadecimal value, and prefixed with a # symbol. For example, #ff0000. Save the form to add the setting, and exit Designer's Mode when you have finished creating theme settings. Editing theme setting values Theme setting values are edited by administrators on the normal edit screen for the theme. Navigate to Customization -> Themes, and click the Edit icon to the right of the theme you want to edit. Theme settings are available in tabs on the edit screen, and can be adjusted based on the field type: Using theme settings Now that you have created a theme setting (or several), they can be used in your HTML & CSS files. There's a couple of ways of using them. {theme} tag If you just want to output the value a setting (for example, in a CSS file to set a style value as the value of the theme setting), IPS4 includes a special theme tag you can use: {theme="your_theme_key"} A real-world example: body { background-color: {theme="page_background"}; } HTML logic If you need to check the value of a theme setting in an HTML logic tag (for example, to determine whether a block of HTML should be shown or not), a short-hand variable is available to you: theme.your_theme_key A real-world example: {{if theme.forum_layout === 'grid'}} ... {{else}} ... {{endif}}

While the theme system allows almost limitless customization possibilities, there are a few best practices that we recommend you follow. They will make things easier for both you and site admins who choose to use your theme. Don't edit default CSS files Whenever a default theme file is edited, it makes upgrading a site a little more difficult because the customizations have to be handled. This is an easy problem to solve for CSS because by its nature it cascades - that means you can create your own CSS files that overwrite styles defined in our default CSS files, without impacting the ability for the suite to update the default CSS file later upon upgrade. By way of encouragement, we ship an empty CSS file called custom.css which you can use as a starting point for your changes. For simpler themes, keeping your changes in this one file might be sufficient. However, you can create more custom CSS files in the custom group if you wish, and they'll be automatically included (no need to use @import statements). The IPS Community Suite always includes your custom CSS files last in the loading order, so you can use the same selectors you see in the default CSS files and your new styles should overwrite the default. Keep template changes to a minimum Similar to the above, editing templates can lead to difficulty with upgrades, because customized templates may be missing new HTML necessary for a new feature, or worse, break the templates by calling a variable that has since been removed. However, unlike CSS files, templates can't cascade, and sometimes editing a template is the only choice. Therefore, we recommend you try to keep these edits to a minimum. There's a few strategies for doing so: Use CSS where possible It may be tempting to adjust the HTML in templates to help achieve some particular visual style. We recommend exploring using CSS to do this instead wherever possible because it will make maintaining your theme much easier in the long run. Use template includes and custom templates where appropriate If you're adding a larger block of HTML to a template (more than a couple of lines), consider putting that code in a custom template bit instead, and then calling that template from the default template. That way, the customization to the default template is a simple include tag that can easily be reverted and added back later without much effort. To call a custom template, you can do: {template="myCustomTemplate" group="<group>" app="<app>"} where <group> and <app> are the keys for the location you chose when you created your custom template bit. Consider creating a hook instead Application hooks have the ability to adjust templates by 'hooking' into the code inside them. In some situations, using a hook to adjust the template may be more appropriate that editing the template contents directly. Remember mobile support The IPS Community Suite has been designed from the ground up to be responsive; that is, the same theme works on devices regardless of screen size, whether it's a desktop monitor or a phone. When you make changes to your theme, remember to consider mobile support and ensure you include responsive styles too. You can use a tool like Google Chrome's web inspector to mimic different screen sizes, or use a tool like BrowserStack to test your theme on real devices Remember right-to-left support The IPS Community Suite is designed to work fully with both left-to-right (LTR) and right-to-left (RTL) languages. If you are creating a theme that you plan to share with others (rather than one just for your own use), keep RTL support in mind. The next step of this guide covers some steps you can follow to support it.

While the standard template editor is useful for light template editing, for larger, more complex changes, editing with a real IDE is desirable. The IPS Community Suite facilitates this through something called Designer's Mode. What is Designer's Mode? Designer's Mode allows you to use a real IDE by exporting all of the templates and CSS files to disk as files, and then reimporting them to the suite when you have finished editing them. With Designer's Mode enabled, the software will load its theme from this folder, meaning you can edit the files and see the changes as you make them. Warning Designer's Mode should not be used on a live community because it will have resource usage implications. We always recommend developing themes with Designer's Mode on a test/development installation. Enabling Designer's Mode The first step is to create a folder called themes in your root community directory (that is, the same place your conf_global.php exists). CHMOD this folder to 777 to enable the suite to write the files. Next, navigate to Customization -> Themes in the AdminCP. In the toolbar at the top of the page, click the Designer's Mode button. Toggle the setting on after reading the information box, and then save the form. IPS4 will begin writing the theme files to disk. Once complete, you will see a directory structure similar to this in the /themes folder on your server: All themes currently installed are exported when Designer's Mode is enabled; the parent folders in this structure are named based on the theme ID. You can cross-reference the theme ID you wish to edit on the theme listing page in the AdminCP while Designer's Mode is enabled: Each theme folder contains four key parts: /css The CSS for the theme, grouped first by app, then by location (front/admin/global). /html The *.phtml HTML templates this theme uses, grouped first by app, then by location (front/admin/global) then by section. lang.php A language file into which you can insert any custom language strings your theme requires. They should be in this format: 'my_language_key' => "The English phrase" /resources Resources for the theme (primarily images), grouped first by app, then by location (front/admin/global) then by type. Resources aren't allowed to be larger than 1.5 MB . Editing templates When you edit the *.phtml template files exporting by Designer's Mode, you will notice a special tag on the first line of each file that looks like this: <ips:template parameters="$title,$html,$location=array()" /> This tag is how the software knows which variables belong to this template. It is very important that you do not modify this line in template files, or your theme may break. Completing Designer's Mode When you are happy with your changes, you can disable Designer's Mode to import them back into the suite (note that you can enable Designer's Mode again later to continue). To do this, go back to the theme listing screen at Customization -> Themes, and click the red Designer's Mode Enabled button. When you toggle the setting off, you will see additional settings asking you to confirm that you want to synchronize the changes. Warning Be sure the Synchronize option is enabled when you save this form, otherwise your changes will be lost. You can select individual themes to sync, or all of them. You can also choose whether to keep the files on disk or automatically delete them once the sync is done.

The standard way of editing a theme is by using the template editing tools available in the AdminCP. They provide easy access to templates & CSS and don't require any special setup. To begin editing a theme, navigate to Customization -> Themes in the AdminCP, and then click the code icon to the right of the theme you wish to edit. Note: If the theme you wish to edit was originally created with the easy editor, the code icon will instead appear in the dropdown menu for the theme. This is what you'll see: 1. File listing The sidebar lists the available templates/CSS files in this theme. In the template list, templates are grouped first by application, and then front/global, and finally by section. front - Used on the public side global - Used on both the public and admin side Four different icons may be shown to the right of each item in the list to denote its status: M - This file was modified in a previous version of the IPS Community Suite and may be out of date M - This file was modified in the current version of the IPS Community Suite I - This file is being inherited from a parent theme. Changes in the parent theme's file will be reflected here too C - This file is unique to this theme (i.e. it has been added manually) You can switch between templates and CSS files with the tabs at the top of the sidebar. Both types of file can be open at once in the editor. 2. Editor The main editor window is a tabbed, syntax-highlighted editor allowing you to edit both templates and CSS files at the same time. Open a tab by clicking a file in the sidebar; close a tab by clicking the X in the tab. If a file has unsaved changes, a bulletpoint will be shown in place of the X. 3. Search Easily locate a particular template or CSS file by searching for it. This field searches both the name and template contents. 4. Revert If the currently-selected file has saved changes (i.e. it is different from the default theme that we ship with the software), the Revert button will be available. Clicking it will revert the file back to its default status - any customizations will be removed from it. This is often useful after an upgrade where a file may be out of date. In those situations, reverting a file and then manually reapplying the necessary customizations is the best course of action. 5. Variables Most templates have variables passed into them by the backend code; these variables are often used to output data, or control the display in other ways. Clicking the Variables button shows you the variables being passed for the selected template, so that you are aware of what data is available to the template. Note: Don't add, change or remove variables from this dialog unless you are developing an addon and aware of what you are doing. Changing the variables here will cause errors because it will no longer match what the backend is passing to the template engine. 6. Editor preferences The editor preferences dropdown contains a handful of options controlling how the editor appears. You can set these up to suit your own taste. 7. New file The New button allows you to add custom HTML templates and CSS files to this theme. This is often a good idea to keep your changes isolated from the default templates/css files, which enables easier upgrading for sites using the theme. We cover this more in the Best Practices step of this guide.

A theme in the IPS Community Suite allows for almost limitless visual customization of the software. They are primarily used to match the branding of your community to your main website, but communities will also commonly offer a selection of themes for users to choose from. A theme is made up of the following: Templates Templates render the HTML for the views. They are a mixture of normal HTML, HTML logic, PHP variables and some special plugin tags. CSS Standard CSS files that style the page Resources Normally images, although other resource types can also be used Theme Settings Special pre-defined settings you can create for your theme, allowing users of the theme (i.e. site owners) to customize it easily The IPS Community Suite allows themes to customize all of these items, and provides tools for doing so. Note: Generally speaking, customizing themes using these advanced options assumes knowledge of HTML, CSS and occasionally Javascript. Making changes without fully understanding the impact could cause issues for your community. Consider using our other theme tools instead. Editing themes There's two primary ways of editing a theme, and we'll cover both in-depth. Template editor The AdminCP provides interfaces for editing each type of theme resource Designer's mode A special mode that exports a theme to files on disk, allowing for editing by traditional IDEs.

When you are happy with your language pack, you can export it and share it with other people (such as via our Marketplace) or simply keep it as a backup. To do so, navigate to Customization -> Languages in the AdminCP, and click the dropdown menu next to the language you want to export. Click on the Download item, and your browser will prompt you to download a file: The file you download will have the extension .xml, and is the only file you need to distribute to share your language pack.

Some phrases have values passed into them by the language system, so you will need to be able to identify these and ensure your translations still include the replacement value. There's a few types of replacement you'll see: %s Simple string replacements {internal.app=core&module=system&controller=register} URL replacements {# [1:reply][?:replies]} Plural replacements We'll cover plural replacements in-depth in the next step. String replacements Simple string replacements use a format determined by PHP's sprintf function. In this format, the special token %s is replaced with the value passed into the phrase: My name is %s becomes this when displayed: My name is Rikki Multiple values are sometimes passed into a phrase, and they are replaced in order. For example, if the values "Rikki" and "blue" were passed into a phrase, in that order, the language phrase: My name is %s and my favorite color is %s becomes this when displayed: My name is Rikki and my favorite color is blue However, since the order of the values passed in is determined by the PHP code in the suite and can't be changed by language authors, special syntax is required if you want to switch the order of any of the replacements (this is often necessary in other languages where sentence structure differs from English). To swap the replacements, the %s token should be changed to %2$s - essentially inserting 2$ in the middle of the normal token, where 2 is the position of the parameter you want to use for this replacement. To take the example above, we could now do: My favorite color is %2$s and my name is %1$s which becomes: My favorite color is blue and my name is Rikki For more information, see the PHP.net sprintf documentation (bear in mind it is a technical document designed for developers). URL replacements Occasionally, links need to be built inside language phrases. Our language system supports this with special tags like this: {internal.app=core&module=system&controller=register} In this example, the internal. means the software knows it is a link to an internal page (i.e. a page within our software), with a URL string to the particular page. There can also be pre-defined external links, like so: {external.ad-custom-location} In this case, ad-custom-location is a pre-defined external URL in our software. When making your translations, be sure to include the links found in the original language phrase, since they often provide valuable extra information to users.

Why plurals are treated differently Many of the phrases used in the IPS Community Suite are plurals. Some examples are: 21 replies 3 comments You have 10 new notifications In English, a plural typically has an 's' for multiple, and no 's' for singular. In other languages, the rules may be more complex and require a specific format depending on the exact number. To facilitate these nuances, the IPS Community Suite uses a special syntax for phrases that refer to a plural items. The language system passes the value being used into the phrase, and the special syntax can use this value to determine which words to show. Syntax The syntax for plural phrases looks like this: {# [1:reply][?:replies]} There's a lot that this syntax allows, but this is the basic usage. It's made up of definitions that are applied depending on the number passed into the phrase for replacement. Let's step through each part of this. {...} The plural replacement always needs to be enclosed in curly braces so that the suite core can recognize it. Note that the plural replacement can appear inside another phrase if the rest of the phrase isn't plural-dependent. For example: "You have {# [1:new notification][?:new notifications]}" # The next character is typically the pound/hash symbol. When it appears at the start of the replacement, this symbol is replaced with the actual number passed into the plural. Alternatively, if you use !# then the number is not included. {# [1:reply][?:replies]} {!# [1:reply][?:replies]} becomes: 10 replies replies [x:reply] The next block is the replacement option, of which there can be several. These are enclosed in square braces, and you can have as many as needed for your language. The block begins x:, where x is a number, indicating that this replacement is used when the number passed into the phrase is exactly x. If your language requires a different plural form for certain numbers, you can repeat the block for each. There's three special symbols you can use for 'x' here: *1: Matches all numbers that end in 1, e.g. 1, 11, 21, 251 %1: Matches all numbers that start with 1, e.g. 1, 10, 12, 163 ?: Matches all other values that aren't matched by another block After the colon : is the string value used if this block matches. Note that the values in these blocks can use the special character #, which like above is replaced with the actual value passed into the phrase. This is particularly useful where the phrase does not need to show the number except in certain circumstances. For example: "Every {!#[1:year][?:# years]}" In English, saying "Every 1 year" would be odd, but for other values you would say "Every 3 years". So in this case, we use !# at the start of the replacement so that the number isn't automatically added, and then use # in the second block so that our string contains the number only if that block is used.

The alternative to using the visual editor is the standard editor. This allows you to edit every phrase in the suite in one place, one after the other. To use the standard editor, navigate to Customization -> Languages in the AdminCP. Click the icon next to the language you want to translate. What you'll now see is a table listing every phrase used by the software. To use this interface, you simply work your way through each phrase, typing your translation. There's a few key parts of the interface we'll cover in more detail. 1. Filters The filters above the grid allow you to narrow down the phrases you see. Out of date Useful to find changed phrases that require updating after you have updated the IPS Community Suite Untranslated Shows phrases you haven't yet translated Translated Shows phrases you've already translated 2. Live Search You can live search for phrases to translate using the search box. By default, the key and the English phrase are both searched for matches, although you can be more specific by clicking the cog icon next to the search box. Tip A handy way to find the key used by language phrases is to enable the 'word key' view. To do so, navigate to Customization -> Languages in the AdminCP, click the Translation Tools button, and enable the View word keys option. When you save the form, instead of seeing English phrases, you'll see the keys used to identify that phrase. 3. Ordering Click one of the table headers to change the sorting of phrases in the table. Click a header again to switch between ascending/descending order. 4. English Phrase This column shows the original English phrase that we use in the software. Use this as the basis for your translated phrase. 5. Your Translation The textarea is where you type your translation for each phrase. Your translation will be automatically saved when you move to the next phrase, or you can click the green Save button manually under each text input.

Setting up the visual language editor The easiest way to get start with translating your language pack is to use the visual language editor. To enable visual editing, first ensure you are using the desired language. You can select a language to use in the footer of the front-end of your community. Next, navigate to Customization -> Languages, and click the Translation Tools button in the header. In the popup window, turn on the Quick Translating option, and save the form. Using the visual language editor With this option enabled, you can now edit phrases that you see in the interface, both in the AdminCP and on the front-end of your community. Phrases that can be translated are highlighted when you hover over them with your mouse cursor. To edit a phrase, click and hold for a couple of seconds. The phrase will change into a textbox that allows you to edit the characters. Type your new phrase, then click out of the box to save your new translation. Tip Using the visual language editor, you can even translate content sections of your site that you have created, such as forum names & descriptions, member group names, ranks and much more. That's all there is to it! You can make your way through your community translating phrases in this way. There will likely be many phrases you don't see in normal use in the interface and that therefore won't be translated with the visual language editor. For those, use the standard translating interface, which we'll cover in the next step. Turning off the visual editor The visual editor will remain active for your whole session. To turn it off, you can either restart your browser, or navigate back to Customization -> Languages in the AdminCP, click Translation Tools and turning off the Quick Translating option.

If you need to create a custom language pack for your community, the IPS Community Suite includes tools to make the process easier. Note: The IPS Community Suite has many hundreds of phrases that need translating to make a complete language pack, so the time investment may be significant. If a ready-made language pack is available for your language, you may wish to use that as a starting point rather than starting from scratch. There's two tools available: Standard translating Each phrase is presented, and you type in the translated version Visual language editor Browse the community as normal, and click on phrases you see to translate them in position We'll cover both in-depth in later steps. To create your language pack, navigate to Customization -> Languages, and click the Create New button. In the popup window that appears, enter a name for your pack, and select the appropriate options in the other fields. Click Save to create the language pack. The language is now available for users to use, although all phrases are currently still English until they are translated. You may wish to disable the language until you have finished translating. To do so, click the Enabled badge next to the language in the listing in order to disable it:

The IPS Community Suite is installed with an English language pack which is also set as the default. However, you can set another language as the default language if you wish. Note: The IPS Community Suite attempts to determine the correct language for a user based on information their browser provides. If this can be determined, and you have an appropriate language pack installed, then providing the user hasn't specifically chosen another language, that language will be shown to them regardless of your community default. To set the default language, navigate to Customization -> Languages in the AdminCP, and click the Edit icon next to the language you want to set: In the popup window that appear, check the Default Language option, and save the form.