Advanced Theming

  1. What does a theme comprise?

    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.
  2. Using the template editor

    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.
  3. Using designer's mode

    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.    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 do, 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.
  4. Managing theme settings

    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}}  
  5. Managing resources

    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"} ); }  
  6. Best practices for your themes

    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.
  7. Handling right-to-left languages

    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.
  8. Upgrading themes

    When a new version of the software is released, there will inevitably be changes to the default templates in which would need to be replicated in your own custom themes. On an upgrade, only unedited templates would be upgraded automatically, and therefore this would be for yourself to upgrade any templates which cannot be upgraded. There are a couple of tools available for you in order to achieve this. Each of which is explained below. Theme differences The theme differences tool is an external tool which can be found in the following location on our site https://invisionpower.com/index.php?app=core&module=system&controller=plugins&do=diff This tool will allow you to see the differences between any 2 versions of the 4.x software, from 4.0.0 right up to the current version.   Once you have selected the versions to compare, you will then be shown all changes between templates on the 2 versions in which you selected in a similar format to the below. Red showing what has been removed, and the green showing what was added   Comparing within the admin CP Whilst within a template in your custom theme, you can compare that to the default, unedited version of the same template directly from the admin CP.  First of all, you would take a look to see which items within your custom theme have been modified. You can do this using the selection menu at the top of the template list, to select only modified templates. This will enable you to quickly find all templates that you may need to look at after an upgrade.   Once you have found and opened a template that you are working on, you will see a tools button in the top right of the screen. Clicking on this will show an option for you show the default. Tip If you simply need to change the template to be that of the default template, you can use the Revert button, also shown in the image below, to achieve this.   Once you have selected this, you will see the default template is placed alongside, with any changes to the default indicated, as shown below. Note that you can edit directly on the right hand side to make any changes needed.