Rikki

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.

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; }  

Basics
The button classes described here can be applied to any element, although typically would be applied to an element like a, input[type="submit"] or button so that the user can interact with it.
As a minimum, a button should receive the basic ipsButton class, plus a size class and a style class (explained below).
 
Button styles
ipsButton_normal
Normal button ipsButton_primary
Primary button ipsButton_alternate
Alternate button ipsButton_important
Important button ipsButton_light
Light button ipsButton_veryLight
Very light button ipsButton_overlaid
Overlaid button ipsButton_link
Link button  
Button sizes
ipsButton_medium
Medium button ipsButton_verySmall
Very small button ipsButton_small
Small button ipsButton_large
Large button ipsButton_veryLarge
Very large button ipsButton_fullWidth
Can be combined with another size, above.
Full width button  
Disabled buttons
Buttons can be visually disabled either by adding the class ipsButton_disabled, or, on relevant input elements, adding the disabled property. For example:
<a href='#' class='ipsButton ipsButton_normal ipsButton_medium ipsButton_disabled'>Disabled button (link)</a> <input type='submit' class='ipsButton ipsButton_normal ipsButton_medium' disabled value='Disabled button (input)'> These would render like so:
Disabled button (link)  
Split buttons
Split buttons allow you to create toolbars easily by specifying a list of buttons that display joined to each other.
They are created by specifying the class ipsButton_split on a wrapper element containing two or more buttons. The wrapper element can be a <ul> tag, or any other that makes sense for your use.
All of the buttons in a split button group should be the same size, otherwise results are unpredictable. Different styles can be used on each button, though.
<ul class='ipsButton_split'> <li><a href='#' class='ipsButton ipsButton_small ipsButton_primary'>Button 1</a></li> <li><a href='#' class='ipsButton ipsButton_small ipsButton_light'>Button 2</a></li> <li><a href='#' class='ipsButton ipsButton_small ipsButton_light'>Button 3</a></li> </ul> Button 1 Button 2 Button 3  

Description
We make use of an icon font called FontAwesome. This enables us to display icons that are accessible, that don't require an additional HTTP request, that can be styled with CSS (and inherit styling automatically), and which scale without loss of quality.
 
Usage
An icon can be included within the markup by using the following code:
<i class='fa fa-iconname'></i> The list of possible icons and their classnames is available at http://fontawesome.io/icons/. Note that these classnames are not prefixed with ips as with other framework classes; they are left with their default names as they appear on the FontAwesome website.
Icons can be used anywhere that HTML can be used. For example, within text, on buttons, in menus and more.
    Icon on a button    A caret icon indicates a dropdown     Yes, I think so   No, I disagree   This is another caret  
Icon consistency
It is important that icon use remains relatively consistent throughout the suite. This applies to core developers as well as addon developers. If different icons are used for the same purpose (or worse, an icon is used for a purpose different to it's usual purpose), users will become confused by the software.
To help alleviate this, we have a list of icons that we generally refer to when choosing an icon to represent an action. Check this list to see if your action already has an associated icon, and lean towards using that instead of choosing another.
The list below organizes actions, with the title being a general concept. The icon names are FontAwesome icons, without the preceding fa-
 
Adding
  plus-circle   plus Deleting
  times-circle   trash-o Editing
  pencil Reverting
  undo Go Somewhere
  arrow-right Open External Link
  external-link Confirming Yes/No
  check   times Permissions
  lock   unlock Log In/Sign In
  key Copy
  copy Settings
  cog Flagging On/Off
  flag   flag-o Star On/Off
  star   star-o Developer/Application
  cogs Help
  question-circle Merge
  level-up Code/PHP/HTML
  code Mail/Send Mail
  envelope-o Search
  search View
  search Refresh/Reload
  refresh Execute/Run Now
  play-circle Easy Mode/Visual Editor
  magic  

By default, we use the 'comments' icon from FontAwesome to represent forums on the read/unread badges. IPS4 also includes an option to upload an image that will be used instead of the icon. But what if you want to use a different FontAwesome icon for each forum?
The good news is this is possible using some custom CSS. Each forum row in the index template includes a data attribute with the forum ID, meaning we can write a style to specifically target each individual forum and overwrite the icon it uses.
Note: Although this method isn't terribly complex, it does require editing custom CSS and working with unicode characters.
 
Determining the icon unicode value
The method we're going to use involves replacing the icon using a CSS rule, rather than changing the icon classname in the HTML. The reason we take this approach is it won't make upgrading your templates difficult later - our custom CSS persist through IPS4 versions easily.
What this means however is that we need to identify the unicode value that FontAwesome assigns to the icons we want to use.
To do so, head over to the FontAwesome icon list on this page. Locate the icon you'd like to use, and click it. On the information page, you'll see the unicode value for the icon. Make a note of this code. For example:

Do this for each icon you'll want to use.
 
Adding the CSS
We're going to add our CSS to our custom.css file so that it persists through upgrades. In the AdminCP, go to Customizations -> Themes, and click the code edit icon next to the theme you want to change. On the CSS tab, open the custom.css file:

The rule we need to use looks like this:
[data-forumid="..."] .fa-comments:before { content: "\f123"; } You'll need to adjust this code to include the forum ID for the forum you want to change. You can find the forum ID by hovering on the link to the forum, and noting the number you see in the URL: 

You'll also need to replace the f123 unicode value with the one for the icon you want to use that you noted earlier.
 
Example
Let's say we have forum ID's 1 and 2, and we want to use FontAwesome's bicycle and car icons, respectively. We note the unicode values for those icons, which are f206 and f1b9.
The CSS we'd add looks like this:
[data-forumid="1"] .fa-comments:before { content: "\f206"; } [data-forumid="2"] .fa-comments:before { content: "\f1b9"; } Once we save it, we can see the result:

Database URL Structure
Databases exist inside a page you've created with Pages. Individual categories and records in the database are accessed via the URL of the page. For example, if you had a page with the URL <yourcommunity>/mypage and this page contained your database, you might have a record that's accessed via the URL <yourcommunity>/mypage/category/record, where category is the category name and record is the record name. Your URLs would dynamically update themselves if you renamed your page or moved the database to a different page.
To facilitate this approach, databases can only exist in one page at a time. They can't be duplicated on other pages (although you can create blocks showing data from the database and use them on other pages).
 
Fields
More advanced uses of databases require custom data to achieve their goals, and fields can be set up to gather this data. Fields are created in the AdminCP, and when a user adds a new record, the fields are shown on the form. 
IPS4 supports a wide range of field types, allowing you to capture data of a specific type easily. Here's the supported types:
Address
Provides a special auto-completing address field, powered by Google Checkbox
A single on/off checkbox Checkbox set
A group of several on/off checkboxes Code
Provides a way to syntax-highlight code Date
A date field, with a date picker Editor
Provides a rich text editor for WYSIWYG editing Database relationship
An advanced field type that allows records from different databases to be associated Member
Provides an auto-complete member search box Number
A number input box (on older browsers, reverts to a simple text box but with number validation) Password
A password input field Radio
A group of radio boxes (meaning only one of the options can be selected) Select box
A drop-down menu containing the provided options (can allow multiple selections if desired) Soundcloud
A Soundcloud embed field Spotify
A Spotify embed field Telephone
A telephone number input field (on older browsers, reverts to a simple text box) Text (default)
A one-line text input field Text Area
A multiple-line text input field Upload
An IPS4 upload field URL
A URL input field (on older browsers, reverts to a simple text box with URL format validation) Yes/No
A toggle field that can accept yes or no values YouTube
A YouTube embed field Many of these field types have additional options specific to them. For example, select boxes have an option to allow multiple values to be selected, whereas the upload has options to allow multiple files, and a way to restrict file types.
Field Formatting
Fields can have automatic formatting applied to them. For non-coders, a range of badge colors is available to choose from, and you have some control over the location that the field shows in the listing or record display. For coders, however, you have full control over the HTML output for each field, including having use of IPS4's template logic. This means you have the ability to use the data stored by IPS4 for each field in some very interesting ways - for example, you might take the value of an address field and use it to output an embedded Google Maps map, or even create some fields that you don't output, but instead use to control the layout of your record templates. There are a huge number of possibilities.
 
Permissions
There's multiple levels of permissions at play with databases:
Page-level
Since pages have their own permission settings, if the user doesn't have permission to see the page, they won't be able to see the database either. Database-level
Permissions can be set at a database-level, which forms the default permissions for categories in the database too. Category-level
A category can optionally override the database-level permissions and provide its own. This is useful for hidden categories - perhaps staff only, or a category only for premium members.  
Managing Databases
Databases are managed by going to Pages -> Databases in the AdminCP. You'll also find that databases are listed in the Pages menu in the AdminCP for quicker access. From this screen, you'll see some simple information about each of your databases, as well as menu items to manage each part:

Managing Database
Records can be added either via the AdminCP (click the   icon) or via the front-end page that displays the database. This means users don't need AdminCP access to add/edit records.
 
Creating Databases
To create a database, click the Create New button on the screen above. There's a number of configuration options available to you.
Details
The basic settings for this database. At the bottom of this tab, you can choose the templates you want to use for this database. If you haven't created them yet, you always do this later.
  Language
On the Language tab, you set up the words that will be used to refer to records in this database (rather than the generic 'records' terminology). For example, if you are creating a database for guides, these language choices will mean IPS4 will refer to your database in context, such as "Search Guides", "There are 5 guides in this database" and "Create a new guide".
  Options
This tab more finely controls how your database will work, including comments, reviews, tagging, and the 'wiki-style' editing we covered earlier. Sorting options are also available here, allowing you to choose the order of records, and more importantly, the field on which they are sorted. For example, if you had a database containing records about dinosaurs, you may want to sort the records by Era (a custom field you will have created). You can return to this tag after creating your fields later to configure it.
  Forum
This tab configures the aforementioned Forums integration for the database (individual categories can override these settings too).
  Page
Since a database requires a page in which it displays, you can easily create one here as part of the database creation process. Alternatively, you can add it to one of your existing pages later.  
Adding to a Page
If you don't create a page as part of the database creation process (above), you can do so manually by using a special database tag in your page content. On the Details tab of the database form, you specified a database key. This is how this database is included in pages. If the key is my-database, you'd insert it into a page by placing this:
{database="my-database"} As mentioned above, a database can only exist on one page at a time; trying to use this tag on multiple pages won't work correctly.

For most admins, creating a theme with the Easy Editor is the best option. It allows you to customize the default theme in a point-and-click environment and see your changes in real-time, and requires no coding skills whatsoever.
 
Creating the theme
To create the theme we'll edit, navigate to Customization -> Themes in the AdminCP. Click the Add Theme button. In the popup window, ensure the Easy Mode option is selected (it's the default), and then click Next. 
On the next screen, you can configure some choices about your new theme:
Name (required)
As it will appear to users of your site Parent
You can make this theme a child of another, meaning it will automatically inherit any style/template changes from the parent theme Default theme
Makes this theme the default for guests and members who have not specifically chosen another theme Available for
Sets permissions for which groups can use this theme. Example use: a theme that only 'premium' users can access as an added benefit of paying Click Save once you have filled in the information. Your theme will be created and you'll be returned to the theme listing.
 
Launching the Easy Mode editor
From the theme listing in the AdminCP, you can click the magic wand icon on any Easy Mode theme to launch the visual editor (you will need to be logged into the front-end of your community to use the visual editor):

Note: You can launch the visual editor at any time, even long after you've created the theme. However, if you convert an Easy Mode theme to a normal theme, you can't go back and use the visual editor.
Launching the visual editor will take you to your community in editing mode (that only you can see). Your community will be shown on the left, with editing tools available in a panel on the right:

 
The visual editor has a few key functions to help you design your theme. We'll cover each in turn.
 
1. Colorize
This tool lets you instantly change all of the theme colors to different shades of another color. Click the Colorize button, and you'll see four swatches:

Clicking a swatch and choosing a new color will immediately update the live preview to show you the result.

The colorize tool is great as a first step - if you know you want a red theme (for example), you can use it to get the basics done, and then fine-tune the resulting colors later using the other tools.
If you don't like the result, you can click the Revert Colorizer button to undo your changes.
 
2. Select tool
The Select tool allows you to point-and-click at sections of pages on your community, and the visual editor will automatically show you the color editor for the closest available parts.

 
3. Custom CSS
If you are familiar with CSS, the Easy Mode editor gives you the ability to add custom CSS to your theme without needing to convert it to a full manual theme. Simply click the CSS button, and a code editor will be shown for you to use. And yes, you still get the live preview!
 
4. Style editor
The available styles you can edit are listed in the main panel. Click one to see the color swatches and to edit the colors. Some styles allow you to edit just the background, others will also allow you to edit the font color.

Background colors can also be turned into gradients by clicking the    button. To use it, you choose a direction in which the gradient should go, and then add colors to form the gradient.

 
5. Build
The Build tab is where you'll go once you're happy with your changes and want to save them. Click the Save Theme button to do so. This will save your changes and make them live to any users who have chosen this theme.
 
 

Basics
The button classes described here can be applied to any element, although typically would be applied to an element like a, input[type="submit"] or button so that the user can interact with it.
As a minimum, a button should receive the basic ipsButton class, plus a size class and a style class (explained below).
 
Button styles
ipsButton_normal
Normal button ipsButton_primary
Primary button ipsButton_alternate
Alternate button ipsButton_important
Important button ipsButton_light
Light button ipsButton_veryLight
Very light button ipsButton_overlaid
Overlaid button ipsButton_link
Link button  
Button sizes
ipsButton_medium
Medium button ipsButton_verySmall
Very small button ipsButton_small
Small button ipsButton_large
Large button ipsButton_veryLarge
Very large button ipsButton_fullWidth
Can be combined with another size, above.
Full width button  
Disabled buttons
Buttons can be visually disabled either by adding the class ipsButton_disabled, or, on relevant input elements, adding the disabled property. For example:
<a href='#' class='ipsButton ipsButton_normal ipsButton_medium ipsButton_disabled'>Disabled button (link)</a> <input type='submit' class='ipsButton ipsButton_normal ipsButton_medium' disabled value='Disabled button (input)'> These would render like so:
Disabled button (link)  
Split buttons
Split buttons allow you to create toolbars easily by specifying a list of buttons that display joined to each other.
They are created by specifying the class ipsButton_split on a wrapper element containing two or more buttons. The wrapper element can be a <ul> tag, or any other that makes sense for your use.
All of the buttons in a split button group should be the same size, otherwise results are unpredictable. Different styles can be used on each button, though.
<ul class='ipsButton_split'> <li><a href='#' class='ipsButton ipsButton_small ipsButton_primary'>Button 1</a></li> <li><a href='#' class='ipsButton ipsButton_small ipsButton_light'>Button 2</a></li> <li><a href='#' class='ipsButton ipsButton_small ipsButton_light'>Button 3</a></li> </ul> Button 1 Button 2 Button 3  

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.

Description
The messages module provides a way to style informational messages to bring something to the user's attention.
 
Usage
To create a message, simply add the ipsMessage class to a container element (e.g. div), along with one of the message styles below. The message style class will automatically add the appropriate icon to your message box.
 
Message styles
Error - ipsMessage_error
This is an error message. Success - ipsMessage_success
This message indicates something happened successfully. Warning - ipsMessage_warning
This message warns the user of something terrible (or not so terrible). Information - ipsMessage_info
This message provides general information.  
Message codes
If you need to add a code to your message, such as an error number, you can do so using the ipsMessage_code class:
<div class='ipsMessage ipsMessage_error'> <span class='ipsMessage_code'>12345</span> This is an error message. </div> 12345 This is an error message.  

Description
We make use of an icon font called FontAwesome. This enables us to display icons that are accessible, that don't require an additional HTTP request, that can be styled with CSS (and inherit styling automatically), and which scale without loss of quality.
 
Usage
An icon can be included within the markup by using the following code:
<i class='fa fa-iconname'></i> The list of possible icons and their classnames is available at http://fontawesome.io/icons/. Note that these classnames are not prefixed with ips as with other framework classes; they are left with their default names as they appear on the FontAwesome website.
Icons can be used anywhere that HTML can be used. For example, within text, on buttons, in menus and more.
    Icon on a button    A caret icon indicates a dropdown     Yes, I think so   No, I disagree   This is another caret  
Icon consistency
It is important that icon use remains relatively consistent throughout the suite. This applies to core developers as well as addon developers. If different icons are used for the same purpose (or worse, an icon is used for a purpose different to it's usual purpose), users will become confused by the software.
To help alleviate this, we have a list of icons that we generally refer to when choosing an icon to represent an action. Check this list to see if your action already has an associated icon, and lean towards using that instead of choosing another.
The list below organizes actions, with the title being a general concept. The icon names are FontAwesome icons, without the preceding fa-
 
Adding
  plus-circle   plus Deleting
  times-circle   trash-o Editing
  pencil Reverting
  undo Go Somewhere
  arrow-right Open External Link
  external-link Confirming Yes/No
  check   times Permissions
  lock   unlock Log In/Sign In
  key Copy
  copy Settings
  cog Flagging On/Off
  flag   flag-o Star On/Off
  star   star-o Developer/Application
  cogs Help
  question-circle Merge
  level-up Code/PHP/HTML
  code Mail/Send Mail
  envelope-o Search
  search View
  search Refresh/Reload
  refresh Execute/Run Now
  play-circle Easy Mode/Visual Editor
  magic  

For more advanced sites built with Pages, you may want to change the output of a custom HTML or PHP block depending on which page the user is viewing. For example, if you have a custom menu, you may want to highlight the active item.
We can implement this in Pages by checking the underlying page URL parameters. Although you access a page with a friendly URL (FURL) like http://<yourcommunity>/section/page, behind the scenes this is mapped to a raw URL, such as http://<yourcommunity>/index.php?app=cms&module=pages&controller=page&path=/section/page. Notice the path parameter allows us to identify which page we're accessing. When we access the \IPS\Request::i() object, we can compare against this parameter, like so:
{{if strpos( \IPS\Request::i()->path, 'section/page' ) !== FALSE}} <!-- We know the user is on /section/page --> {{elseif strpos( \IPS\Request::i()->path, 'othersection/otherpage' ) !== FALSE}} <!-- We know the user is on /othersection/otherpage --> {{endif}} Note that for reliability, we're using PHP's strpos function to check for the presence of the page URL in the path parameter, rather than a simple comparison.
Example
Let's assume we've created a Manual HTML block, we're adding HTML to show a menu, and we want to highlight the correct item based on the page. Here's what our block contents might look like:
<ul class='ipsList_inline cMyMenu'> <li {{if strpos( \IPS\Request::i()->path, 'help/home' ) !== FALSE}}class='active'{{endif}}> <a href='/help/home'>Home</a> </li> <li {{if strpos( \IPS\Request::i()->path, 'help/faq' ) !== FALSE}}class='active'{{endif}}> <a href='/help/faq'>FAQ</a> </li> <li {{if strpos( \IPS\Request::i()->path, 'help/tutorials' ) !== FALSE}}class='active'{{endif}}> <a href='/help/tutorials'>Tutorials</a> </li> </ul> If we had many items to show, it would get tedious to list them all like this. We could instead do it as a loop:
// Using a PHP variable to store an array of pages => page names that we'll loop over {{$myPages = array('help/home' => "Home", 'help/faq' => "FAQ", 'help/tutorials' => "Tutorials", 'help/qna/listing' => "Questions", 'help/qna/recent' => "Recent Questions", 'help/contact' => "Contact Us");}} <ul class='ipsList_inline cMyMenu'> {{foreach $myPages as $url => $title}} <li {{if strpos( \IPS\Request::i()->path, $url ) !== FALSE}}class='active'{{endif}}> <a href='{$url}'>{$title}</a> </li> {{endforeach}} </ul> Now to add new items to our custom menu, we just have to add them to the array.

Basics
The button classes described here can be applied to any element, although typically would be applied to an element like a, input[type="submit"] or button so that the user can interact with it.
As a minimum, a button should receive the basic ipsButton class, plus a size class and a style class (explained below).
 
Button styles
ipsButton_normal
Normal button ipsButton_primary
Primary button ipsButton_alternate
Alternate button ipsButton_important
Important button ipsButton_light
Light button ipsButton_veryLight
Very light button ipsButton_overlaid
Overlaid button ipsButton_link
Link button  
Button sizes
ipsButton_medium
Medium button ipsButton_verySmall
Very small button ipsButton_small
Small button ipsButton_large
Large button ipsButton_veryLarge
Very large button ipsButton_fullWidth
Can be combined with another size, above.
Full width button  
Disabled buttons
Buttons can be visually disabled either by adding the class ipsButton_disabled, or, on relevant input elements, adding the disabled property. For example:
<a href='#' class='ipsButton ipsButton_normal ipsButton_medium ipsButton_disabled'>Disabled button (link)</a> <input type='submit' class='ipsButton ipsButton_normal ipsButton_medium' disabled value='Disabled button (input)'> These would render like so:
Disabled button (link)  
Split buttons
Split buttons allow you to create toolbars easily by specifying a list of buttons that display joined to each other.
They are created by specifying the class ipsButton_split on a wrapper element containing two or more buttons. The wrapper element can be a <ul> tag, or any other that makes sense for your use.
All of the buttons in a split button group should be the same size, otherwise results are unpredictable. Different styles can be used on each button, though.
<ul class='ipsButton_split'> <li><a href='#' class='ipsButton ipsButton_small ipsButton_primary'>Button 1</a></li> <li><a href='#' class='ipsButton ipsButton_small ipsButton_light'>Button 2</a></li> <li><a href='#' class='ipsButton ipsButton_small ipsButton_light'>Button 3</a></li> </ul> Button 1 Button 2 Button 3  

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.

For more advanced sites built with Pages, you may want to change the output of a custom HTML or PHP block depending on which page the user is viewing. For example, if you have a custom menu, you may want to highlight the active item.
We can implement this in Pages by checking the underlying page URL parameters. Although you access a page with a friendly URL (FURL) like http://<yourcommunity>/section/page, behind the scenes this is mapped to a raw URL, such as http://<yourcommunity>/index.php?app=cms&module=pages&controller=page&path=/section/page. Notice the path parameter allows us to identify which page we're accessing. When we access the \IPS\Request::i() object, we can compare against this parameter, like so:
{{if strpos( \IPS\Request::i()->path, 'section/page' ) !== FALSE}} <!-- We know the user is on /section/page --> {{elseif strpos( \IPS\Request::i()->path, 'othersection/otherpage' ) !== FALSE}} <!-- We know the user is on /othersection/otherpage --> {{endif}} Note that for reliability, we're using PHP's strpos function to check for the presence of the page URL in the path parameter, rather than a simple comparison.
Example
Let's assume we've created a Manual HTML block, we're adding HTML to show a menu, and we want to highlight the correct item based on the page. Here's what our block contents might look like:
<ul class='ipsList_inline cMyMenu'> <li {{if strpos( \IPS\Request::i()->path, 'help/home' ) !== FALSE}}class='active'{{endif}}> <a href='/help/home'>Home</a> </li> <li {{if strpos( \IPS\Request::i()->path, 'help/faq' ) !== FALSE}}class='active'{{endif}}> <a href='/help/faq'>FAQ</a> </li> <li {{if strpos( \IPS\Request::i()->path, 'help/tutorials' ) !== FALSE}}class='active'{{endif}}> <a href='/help/tutorials'>Tutorials</a> </li> </ul> If we had many items to show, it would get tedious to list them all like this. We could instead do it as a loop:
// Using a PHP variable to store an array of pages => page names that we'll loop over {{$myPages = array('help/home' => "Home", 'help/faq' => "FAQ", 'help/tutorials' => "Tutorials", 'help/qna/listing' => "Questions", 'help/qna/recent' => "Recent Questions", 'help/contact' => "Contact Us");}} <ul class='ipsList_inline cMyMenu'> {{foreach $myPages as $url => $title}} <li {{if strpos( \IPS\Request::i()->path, $url ) !== FALSE}}class='active'{{endif}}> <a href='{$url}'>{$title}</a> </li> {{endforeach}} </ul> Now to add new items to our custom menu, we just have to add them to the array.

We can now tie everything together with some Javascript. It's with the Javascript that everything will feel snappy and interactive. Begin by heading over to the template editor, and editing the Javascript file we created earlier.
The Javascript controller we write will do two things:
Load the first record when the page is loaded Handle click events on the other records to load the ones the user clicks Here's the final Javascript code you need to insert into the file. We'll explain it shortly:
 
This is a standard IPS4 javascript controller; refer to the controller documentation for more information.
In our initialize method (called automatically when the controller is initialized), we set up an event handler for clicking on elements with the data-releaseID attribute (if you remember, we gave items in our record listing this attribute). We bind this handler to the showRelease method.
We then call the setup method. The logic in this method selects a record to load automatically, so that the page has content in it when the user first loads it. It tries to find a record with the data-currentRelease attribute, but if one doesn't exist, it will load the first item in the list instead.
Finally, there's the showRelease method which has the job of loading and displaying the record view, pulled dynamically via AJAX. To do this, we find the relevant URL from the record row and then fire an AJAX request. In the done handler, we update the div that holds our record content.
When a Pages URL is called via AJAX (whether it's a normal page, or a database), it will only return the page content - it won't include the complete site wrapper. This makes it a little easier to implement dynamic page loading. However, in our case, the HTML we need is actually even narrower - we want just the record content, not any of the surrounding page from Pages. For this reason, in the done handler we select just the contents of the #elCmsPageWrap element, and use that as our record content.

We can now tie everything together with some Javascript. It's with the Javascript that everything will feel snappy and interactive. Begin by heading over to the template editor, and editing the Javascript file we created earlier.
The Javascript controller we write will do two things:
Load the first record when the page is loaded Handle click events on the other records to load the ones the user clicks Here's the final Javascript code you need to insert into the file. We'll explain it shortly:
 
This is a standard IPS4 javascript controller; refer to the controller documentation for more information.
In our initialize method (called automatically when the controller is initialized), we set up an event handler for clicking on elements with the data-releaseID attribute (if you remember, we gave items in our record listing this attribute). We bind this handler to the showRelease method.
We then call the setup method. The logic in this method selects a record to load automatically, so that the page has content in it when the user first loads it. It tries to find a record with the data-currentRelease attribute, but if one doesn't exist, it will load the first item in the list instead.
Finally, there's the showRelease method which has the job of loading and displaying the record view, pulled dynamically via AJAX. To do this, we find the relevant URL from the record row and then fire an AJAX request. In the done handler, we update the div that holds our record content.
When a Pages URL is called via AJAX (whether it's a normal page, or a database), it will only return the page content - it won't include the complete site wrapper. This makes it a little easier to implement dynamic page loading. However, in our case, the HTML we need is actually even narrower - we want just the record content, not any of the surrounding page from Pages. For this reason, in the done handler we select just the contents of the #elCmsPageWrap element, and use that as our record content.

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; }  

For more advanced sites built with Pages, you may want to change the output of a custom HTML or PHP block depending on which page the user is viewing. For example, if you have a custom menu, you may want to highlight the active item.
We can implement this in Pages by checking the underlying page URL parameters. Although you access a page with a friendly URL (FURL) like http://<yourcommunity>/section/page, behind the scenes this is mapped to a raw URL, such as http://<yourcommunity>/index.php?app=cms&module=pages&controller=page&path=/section/page. Notice the path parameter allows us to identify which page we're accessing. When we access the \IPS\Request::i() object, we can compare against this parameter, like so:
{{if strpos( \IPS\Request::i()->path, 'section/page' ) !== FALSE}} <!-- We know the user is on /section/page --> {{elseif strpos( \IPS\Request::i()->path, 'othersection/otherpage' ) !== FALSE}} <!-- We know the user is on /othersection/otherpage --> {{endif}} Note that for reliability, we're using PHP's strpos function to check for the presence of the page URL in the path parameter, rather than a simple comparison.
Example
Let's assume we've created a Manual HTML block, we're adding HTML to show a menu, and we want to highlight the correct item based on the page. Here's what our block contents might look like:
<ul class='ipsList_inline cMyMenu'> <li {{if strpos( \IPS\Request::i()->path, 'help/home' ) !== FALSE}}class='active'{{endif}}> <a href='/help/home'>Home</a> </li> <li {{if strpos( \IPS\Request::i()->path, 'help/faq' ) !== FALSE}}class='active'{{endif}}> <a href='/help/faq'>FAQ</a> </li> <li {{if strpos( \IPS\Request::i()->path, 'help/tutorials' ) !== FALSE}}class='active'{{endif}}> <a href='/help/tutorials'>Tutorials</a> </li> </ul> If we had many items to show, it would get tedious to list them all like this. We could instead do it as a loop:
// Using a PHP variable to store an array of pages => page names that we'll loop over {{$myPages = array('help/home' => "Home", 'help/faq' => "FAQ", 'help/tutorials' => "Tutorials", 'help/qna/listing' => "Questions", 'help/qna/recent' => "Recent Questions", 'help/contact' => "Contact Us");}} <ul class='ipsList_inline cMyMenu'> {{foreach $myPages as $url => $title}} <li {{if strpos( \IPS\Request::i()->path, $url ) !== FALSE}}class='active'{{endif}}> <a href='{$url}'>{$title}</a> </li> {{endforeach}} </ul> Now to add new items to our custom menu, we just have to add them to the array.

By default, we use the 'comments' icon from FontAwesome to represent forums on the read/unread badges. IPS4 also includes an option to upload an image that will be used instead of the icon. But what if you want to use a different FontAwesome icon for each forum?
The good news is this is possible using some custom CSS. Each forum row in the index template includes a data attribute with the forum ID, meaning we can write a style to specifically target each individual forum and overwrite the icon it uses.
Note: Although this method isn't terribly complex, it does require editing custom CSS and working with unicode characters.
 
Determining the icon unicode value
The method we're going to use involves replacing the icon using a CSS rule, rather than changing the icon classname in the HTML. The reason we take this approach is it won't make upgrading your templates difficult later - our custom CSS persist through IPS4 versions easily.
What this means however is that we need to identify the unicode value that FontAwesome assigns to the icons we want to use.
To do so, head over to the FontAwesome icon list on this page. Locate the icon you'd like to use, and click it. On the information page, you'll see the unicode value for the icon. Make a note of this code. For example:

Do this for each icon you'll want to use.
 
Adding the CSS
We're going to add our CSS to our custom.css file so that it persists through upgrades. In the AdminCP, go to Customizations -> Themes, and click the code edit icon next to the theme you want to change. On the CSS tab, open the custom.css file:

The rule we need to use looks like this:
[data-forumid="..."] .fa-comments:before { content: "\f123"; } You'll need to adjust this code to include the forum ID for the forum you want to change. You can find the forum ID by hovering on the link to the forum, and noting the number you see in the URL: 

You'll also need to replace the f123 unicode value with the one for the icon you want to use that you noted earlier.
 
Example
Let's say we have forum ID's 1 and 2, and we want to use FontAwesome's bicycle and car icons, respectively. We note the unicode values for those icons, which are f206 and f1b9.
The CSS we'd add looks like this:
[data-forumid="1"] .fa-comments:before { content: "\f206"; } [data-forumid="2"] .fa-comments:before { content: "\f1b9"; } Once we save it, we can see the result:

Padding
ipsPad
15px padding on desktop
ipsPad_half
7px padding on desktop
ipsPad_double
30px padding on desktop
The padding classes are scaled appropriately on mobile devices.
 
Spacing
ipsSpacer_top
15px top margin
ipsSpacer_bottom
15px bottom margin
ipsSpacer_both
15px top and bottom margin
ipsSpacer_half
When combined with one of the above, halves the spacing
ipsSpacer_double
When combined with one of the above, doubles the spacing
 
Clearing
ipsClear
Clears floats preceding the element this class is applied to
ipsClearfix
The popular 'clearfix' technique, which causes a wrapper element with this class applied to fully wrap elements contained within it, even if they are floated. This class should be applied to all elements where descendents may be floated.
 
Positioning
For text positioning, see typography.
ipsPos_left
Floats the element left
ipsPos_right
Floats the element right
ipsPos_center
Sets automatic margins on the element in order to center it. Block elements will require a width to be set for this to be noticeable, otherwise they will naturally display at 100% width.
 
Horizontal rules
Horizontal rules can be styled simply by adding the class ipsHr to a standard <hr> element.
 
Notification counts
ipsNotificationCount is a class for a floating bubble which can denote a notification count of some kind. The parent element should have a non-static position for this class to work correctly. By default, the notification bubble will be offset to the top and right, but this could be overwritten with additional specific styles if desired. Usage:
<!-- The element the notification belongs to --> <!-- position: relative; is set inline here, but avoid that in practice --> <a href='#' class='ipsButton ipsButton_primary ipsButton_medium' style='position:relative'> A button with notification <span class='ipsNotificationCount'>12</span> </a> This would render:
A button with notification12  
Online/Offline status
Provides simple styling to denote whether something (a user, for example) is online or offline. ipsOnlineStatus is the base class; add ipsOnlineStatus_online or ipsOnlineStatus_offline to denote the actual status.
<strong class='ipsOnlineStatus ipsOnlineStatus_online'><i class='fa fa-circle'></i> Online</strong><br> <strong class='ipsOnlineStatus ipsOnlineStatus_offline'><i class='fa fa-circle'></i> Offline</strong>   Online
  Offline  
Cursors
Several classes are provided as shortcuts for changing the mouse cursor on elements.
ipsCursor_locked
"No permission" cursor (example)
ipsCursor_drag
Shows an element can be moved (example)
ipsCursor_pointer
Shows an element can be clicked (example)
ipsCursor_help
Shows an element provides help (example)
ipsCursor_default
Sets the cursor to the default state (example)

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.

Database URL Structure
Databases exist inside a page you've created with Pages. Individual categories and records in the database are accessed via the URL of the page. For example, if you had a page with the URL <yourcommunity>/mypage and this page contained your database, you might have a record that's accessed via the URL <yourcommunity>/mypage/category/record, where category is the category name and record is the record name. Your URLs would dynamically update themselves if you renamed your page or moved the database to a different page.
To facilitate this approach, databases can only exist in one page at a time. They can't be duplicated on other pages (although you can create blocks showing data from the database and use them on other pages).
 
Fields
More advanced uses of databases require custom data to achieve their goals, and fields can be set up to gather this data. Fields are created in the AdminCP, and when a user adds a new record, the fields are shown on the form. 
IPS4 supports a wide range of field types, allowing you to capture data of a specific type easily. Here's the supported types:
Address
Provides a special auto-completing address field, powered by Google Checkbox
A single on/off checkbox Checkbox set
A group of several on/off checkboxes Code
Provides a way to syntax-highlight code Date
A date field, with a date picker Editor
Provides a rich text editor for WYSIWYG editing Database relationship
An advanced field type that allows records from different databases to be associated Member
Provides an auto-complete member search box Number
A number input box (on older browsers, reverts to a simple text box but with number validation) Password
A password input field Radio
A group of radio boxes (meaning only one of the options can be selected) Select box
A drop-down menu containing the provided options (can allow multiple selections if desired) Soundcloud
A Soundcloud embed field Spotify
A Spotify embed field Telephone
A telephone number input field (on older browsers, reverts to a simple text box) Text (default)
A one-line text input field Text Area
A multiple-line text input field Upload
An IPS4 upload field URL
A URL input field (on older browsers, reverts to a simple text box with URL format validation) Yes/No
A toggle field that can accept yes or no values YouTube
A YouTube embed field Many of these field types have additional options specific to them. For example, select boxes have an option to allow multiple values to be selected, whereas the upload has options to allow multiple files, and a way to restrict file types.
Field Formatting
Fields can have automatic formatting applied to them. For non-coders, a range of badge colors is available to choose from, and you have some control over the location that the field shows in the listing or record display. For coders, however, you have full control over the HTML output for each field, including having use of IPS4's template logic. This means you have the ability to use the data stored by IPS4 for each field in some very interesting ways - for example, you might take the value of an address field and use it to output an embedded Google Maps map, or even create some fields that you don't output, but instead use to control the layout of your record templates. There are a huge number of possibilities.
 
Permissions
There's multiple levels of permissions at play with databases:
Page-level
Since pages have their own permission settings, if the user doesn't have permission to see the page, they won't be able to see the database either. Database-level
Permissions can be set at a database-level, which forms the default permissions for categories in the database too. Category-level
A category can optionally override the database-level permissions and provide its own. This is useful for hidden categories - perhaps staff only, or a category only for premium members.  
Managing Databases
Databases are managed by going to Pages -> Databases in the AdminCP. You'll also find that databases are listed in the Pages menu in the AdminCP for quicker access. From this screen, you'll see some simple information about each of your databases, as well as menu items to manage each part:

Managing Database
Records can be added either via the AdminCP (click the   icon) or via the front-end page that displays the database. This means users don't need AdminCP access to add/edit records.
 
Creating Databases
To create a database, click the Create New button on the screen above. There's a number of configuration options available to you.
Details
The basic settings for this database. At the bottom of this tab, you can choose the templates you want to use for this database. If you haven't created them yet, you always do this later.
  Language
On the Language tab, you set up the words that will be used to refer to records in this database (rather than the generic 'records' terminology). For example, if you are creating a database for guides, these language choices will mean IPS4 will refer to your database in context, such as "Search Guides", "There are 5 guides in this database" and "Create a new guide".
  Options
This tab more finely controls how your database will work, including comments, reviews, tagging, and the 'wiki-style' editing we covered earlier. Sorting options are also available here, allowing you to choose the order of records, and more importantly, the field on which they are sorted. For example, if you had a database containing records about dinosaurs, you may want to sort the records by Era (a custom field you will have created). You can return to this tag after creating your fields later to configure it.
  Forum
This tab configures the aforementioned Forums integration for the database (individual categories can override these settings too).
  Page
Since a database requires a page in which it displays, you can easily create one here as part of the database creation process. Alternatively, you can add it to one of your existing pages later.  
Adding to a Page
If you don't create a page as part of the database creation process (above), you can do so manually by using a special database tag in your page content. On the Details tab of the database form, you specified a database key. This is how this database is included in pages. If the key is my-database, you'd insert it into a page by placing this:
{database="my-database"} As mentioned above, a database can only exist on one page at a time; trying to use this tag on multiple pages won't work correctly.

What is a database?
Databases are one of the most powerful and flexible features available in the Pages application. With some configuration and customization, they enable you to add complex, data-driven areas to your community, using some of the basic underlying functionality that full IPS4 applications have.
Databases, as the name implies, are designed to hold data and display that to the user. This might be as simple as a table of records each containing a title and a body, from which you could make a very simple blog-like section, or it might be as complex as a completely custom interface backed by a large number of custom data fields specific to your needs - and the possibilities for this are endless.
 
Features
Searching
Databases are searchable by default (although you can turn this off if desired). Each database is treated as a distinct area of your community, so on the search form, each database is listed as a first-class area to search, much like the Forums app for example.
Core suite features
Pages provides a range of core application features to databases that make even the simplest database feature-rich and well-integrated with your community from the outset. Commenting and writing reviews for records is available (although this can be disabled per-database). Users can also follow categories and records to be notified of new content wherever they are in the community. Social features such as reputation and sharing to other social networks is also built-in and available for records. Tagging and full moderation of records is also supported by default, and integrated across the suite as you'd expect.
Wiki-style editing
In terms of adding/editing records, databases in Pages behave much like you'd expect from our other applications; that is, when a user with permission creates a record, they 'own' it. However, databases have an option for wiki-style editing, whereby any user can edit records after they are created. This approach is great for community-curated content.
Revisions
Databases also support revisions for records. This means each time a record changes, the previous version is saved as a revision that can be accessed again later - you can also revert to an earlier revision if desired.
Forum Integration
Finally, databases has special integration with our Forums app. When posting a new record to a Pages database, IPS4 can optionally cross-post the record as a forum topic, to a category of your choosing. But it goes further - you can even use the forum topic as the comments for the record, rather than the standard commenting interface that records have.
 
What does a database consist of?
There's a few key components in a database to be aware of when creating one:
The database itself
Naturally, you need to create the database itself. This is where you configure options that affect that database as a whole, such as sorting, permissions, and so on. Categories
If your databases uses categories (you can optionally choose not to), they add another level of structure and permissions. Fields
We'll cover fields in more depth shortly, but you can create custom fields for all kinds of data that you might need for your database. IPS4 supports a wide range of field types, from simple text boxes up to YouTube embeds, upload fields and intra-database relationships. Templates
Templates allow you to customize the output of the database. Default templates are supplied with IPS4, and if you aren't a coder, using these defaults allow you to get a database up and running quickly. For coders, however, customizing templates is the best way to build complex data-driven applications. Templates, CSS & JS

Description
The form module provides classes for styling forms throughout the suite, with a range of options available to change the appearance and flow.
 
Usage
A form should have the base class ipsForm. In many cases this will be directly on the <form> element, but it can actually appear on any element that contains form elements. The recommended basic DOM structure for a form is as follows:
<form class='ipsForm'> <ul> <li class='ipsFieldRow'> ... </li> <li class='ipsFieldRow'> ... </li> </ul> </form> In this structure, each field row within the form appears as a <li> element with the class ipsFieldRow
 
Form layouts
There are two layout options for forms: vertical or horizontal. In a vertical form, field labels are displayed above the field element. In horizontal forms, the label appears to the left of the field element. The layout can be controlled by adding the classes ipsForm_vertical or ipsForm_horizontal to the root form element, respectively.
Example of both types:
Vertical form Horizontal form Note: On small devices and with the responsive CSS enabled, horizontal layout forms will automatically collapse to become vertical layout so that they are easily readable.
 
Field Rows
Each field row within the form has a number of options available, depending on the type of field. The basic structure for a field row is as follows:
<li class='ipsFieldRow'> <label for='example' class='ipsFieldRow_label'> Example field </label> <div class='ipsFieldRow_content'> <input type='text' id='example' value=''> </div> </li> The row receives the base class ipsFieldRow. Within this element are the label and content elements. The label receives the class ipsFieldRow_label, while the content wrapper receives the class ipsFieldRow_content. The content element can theoretically contain anything, though naturally it should be kept simple for best usability.
There are several additional classes that can be applied to field rows.
ipsFieldRow_primary
A primary field row causes text inputs to be enlarged to convey importance ipsFieldRow_fullWidth
Causes appropriate form controls (primarily text-based/select inputs) to take up all available horizontal space ipsFieldRow_noLabel
If no label is needed, this class can be used to ensure spacing still works as expected. Do give thought to usability before deciding to remove a label.  
Required fields
To add a 'required' indicator to a field, an element with the class ipsFieldRow_required can be added inside the label element, like so:
<label for='elExample' class='ipsFieldRow_label'> Field title <span class='ipsFieldRow_required'>Required</span> </label> On horizontal-layout forms, the text inside the 'required' indicator element is automatically replaced with an asterisk in order to conserve space.
 
Field descriptions
Field descriptions can be added immediately following the form control, inside of the field content element, by using the class ipsFieldRow_desc. For example:
<div class='ipsFieldRow_content'> <input type='text' size='30'><br> <span class='ipsFieldRow_desc'>This is a field description</span> </div>  
Checkboxes/Radios
The markup and classes used for checkboxes or radio buttons are by necessity a little different to that described above, because typically the element will sit to the left of the label and appear inline with it.
This is an example of the markup used for checkboxes or radios (note that although the class refers to 'checkbox', it can be used for both types of control):
<li class='ipsFieldRow ipsFieldRow_checkbox'> <span class='ipsCustomInput'> <input type='checkbox' id='elExampleCheckbox'> <span></span> </span> <div class='ipsFieldRow_content'> <label for='elExampleCheckbox'>Remember me</label> </div> </li> There are a few differences here. Firstly, the class ipsFieldRow_checkbox has been added to the field row to denote that this row should be handled differently. Secondly, the checkbox control now sits as a direct descendant of the row element, while the label moves inside the content element. Finally, the checkbox itself is wrapped in an element with the classname ipsCustomInput, which allows us to style checkboxes and radios using CSS.
  Remember me  
Horizontally-grouped checkboxes
Another common way to display checkbox/radio controls is as a horizontal list of choices. This can be done with the following markup:
<li class='ipsFieldRow'> <span class='ipsFieldRow_label'>Choose an option</span> <ul class='ipsFieldRow_content ipsList_reset'> <li class='ipsFieldRow_inlineCheckbox'> <span class='ipsCustomInput'> <input type='radio' id='checkbox1'> <span></span> </span> <label for='checkbox1'>Option 1</label> </li> <li class='ipsFieldRow_inlineCheckbox'> <span class='ipsCustomInput'> <input type='radio' id='checkbox2'> <span></span> </span> <label for='checkbox2'>Option 2</label> </li> <li class='ipsFieldRow_inlineCheckbox'> <span class='ipsCustomInput'> <input type='radio' id='checkbox3'> <span></span> </span> <label for='checkbox3'>Option 3</label> </li> </ul> </li> Here we're building the field row content element as a list (we use ipsList_reset to remove margins and padding), with each list item receiving the class ipsFieldRow_inlineCheckbox to align them horizontally.
The above example produces the following result:
Choose an option   Option 1   Option 2   Option 3  
Vertically-grouped checkboxes
You can also group checkboxes and radio controls in a vertical list. The markup looks like this:
<li class='ipsFieldRow'> <span class='ipsFieldRow_label'>Choose an option</span> <ul class='ipsFieldRow_content ipsField_fieldList'> <li> <span class='ipsCustomInput'> <input type='checkbox' id='option1'> <span></span> </span> <div class='ipsField_fieldList_content'> <label for='option1'>Option 1</label><br> <span class='ipsFieldRow_desc'>Option 1 description</span> </div> </li> <li> <span class='ipsCustomInput'> <input type='checkbox' id='option2'> <span></span> </span> <div class='ipsField_fieldList_content'> <label for='option1'>Option 2</label><br> <span class='ipsFieldRow_desc'>Option 2 description</span> </div> </li> </ul> </li> Which renders as:
Choose an option   Option 1
Option 1 description   Option 2
Option 2 description  
Field loading state
Text-based form inputs (text inputs, date fields, textareas, etc.) can be shown in a loading state by adding the class ipsField_loading (usually with Javascript). This causes the field to show a loading throbber in the field.
Loading example Note: this effect is achieved using background images. If you define styles for form fields that specify a background image, the loading effect may not render correctly.
 
Grouping field rows
Adding section headers
You can add a section header to a form by adding a header element of your choice with the class ipsFieldRow_section, like this:
<li> <h2 class='ipsFieldRow_section'>A section header</h2> </li>  
Fieldsets
Fields can be grouped together in related sets by using fieldsets with the class ipsForm_group. The markup for this kind of structure looks like this:
<div class='ipsForm ipsForm_horizontal'> <fieldset class='ipsForm_group'> <legend class='ipsForm_groupTitle'>First group</legend> <ul class='ipsForm_groupContent'> <li class='ipsFieldRow'> <!-- Field row content --> </li> <li class='ipsFieldRow'> <!-- Field row content --> </li> </ul> </fieldset> <fieldset class='ipsForm_group'> <legend class='ipsForm_groupTitle'>Second group</legend> <ul class='ipsForm_groupContent'> <li class='ipsFieldRow'> <!-- Field row content --> </li> <li class='ipsFieldRow'> <!-- Field row content --> </li> </ul> </fieldset> </div> This produces (with field row content added):
First group Field title Field title Second group Field title Field title The class ipsForm_group is added to a container element - this will typically be a fieldset. Within that element will be a title element, with the class ipsForm_groupTitle. This too can be any element, but a legend element will usually make most sense. Finally, there's an element with the class ipsForm_groupContent which wraps all of the field rows in the group.
 
Complete form example
Here is a complete example of a form, which can be toggled between vertical and horizontal layouts for demonstration purposes. The markup for this example follows after.
Name Required E-mail Address Required
We keep this confidential Please send me   Updates   Offers   I agree to the terms and conditions Submit  
<ul class='ipsForm ipsForm_horizontal' id='form_example'> <li class='ipsFieldRow ipsFieldRow_primary ipsFieldRow_fullWidth'> <label class='ipsFieldRow_label'>Name <span class='ipsFieldRow_required'>Required</span></label> <div class='ipsFieldRow_content'> <input type='text' size='30' placeholder='First name'> </div> </li> <li class='ipsFieldRow'> <label class='ipsFieldRow_label'>E-mail Address <span class='ipsFieldRow_required'>Required</span></label> <div class='ipsFieldRow_content'> <input type='text' size='30' placeholder='example@me.com'><br> <span class='ipsFieldRow_desc'>We keep this confidential</span> </div> </li> <li class='ipsFieldRow'> <span class='ipsFieldRow_label'>Please send me</span> <ul class='ipsFieldRow_content ipsList_reset'> <li class='ipsFieldRow_inlineCheckbox'> <span class='ipsCustomInput'> <input type='checkbox'> <span></span> </span> <label>Updates</label> </li> <li class='ipsFieldRow_inlineCheckbox'> <span class='ipsCustomInput'> <input type='checkbox'> <span></span> </span> <label>Offers</label> </li> </ul> </li> <li class='ipsFieldRow ipsFieldRow_checkbox'> <span class='ipsCustomInput'> <input type='checkbox'> <span></span> </span> <div class='ipsFieldRow_content'> <label class='ipsFieldRow_label'><strong>I agree to the terms and conditions</strong></label> </div> </li> <li class='ipsFieldRow'> <div class='ipsFieldRow_content'> <button type='submit' class='ipsButton ipsButton_medium ipsButton_primary'>Submit</button> </div> </li> </ul>  

By default, IPS4 has a maximum body width of 1340 pixels, and is fluid at sizes smaller than this. However, we ship the software with a customizable theme setting allowing this to be easily overridden, should you want to change the behavior.
 
Using the Easy Mode theme editor
If your theme was made using the Easy Mode editor, you can adjust the body width on the Settings tab when designing your theme. First, click the magic wand icon to launch the Easy Mode editor:

And then the Settings tab. There's two settings you need to adjust; turn on Enable Fluid Width, and then change the percentage value in the Fluid Width Size setting. To have it take up all available space, set this to 100%.
 
Using the standard theme editor
If your theme was created using the standard theme editor in the AdminCP, you adjust the theme settings also in the AdminCP. Click the edit icon next to the theme you want to adjust:

And on the Custom tab on the edit screen, you will see the Enable Fluid Width and Fluid Width Size settings.

We can now tie everything together with some Javascript. It's with the Javascript that everything will feel snappy and interactive. Begin by heading over to the template editor, and editing the Javascript file we created earlier.
The Javascript controller we write will do two things:
Load the first record when the page is loaded Handle click events on the other records to load the ones the user clicks Here's the final Javascript code you need to insert into the file. We'll explain it shortly:
 
This is a standard IPS4 javascript controller; refer to the controller documentation for more information.
In our initialize method (called automatically when the controller is initialized), we set up an event handler for clicking on elements with the data-releaseID attribute (if you remember, we gave items in our record listing this attribute). We bind this handler to the showRelease method.
We then call the setup method. The logic in this method selects a record to load automatically, so that the page has content in it when the user first loads it. It tries to find a record with the data-currentRelease attribute, but if one doesn't exist, it will load the first item in the list instead.
Finally, there's the showRelease method which has the job of loading and displaying the record view, pulled dynamically via AJAX. To do this, we find the relevant URL from the record row and then fire an AJAX request. In the done handler, we update the div that holds our record content.
When a Pages URL is called via AJAX (whether it's a normal page, or a database), it will only return the page content - it won't include the complete site wrapper. This makes it a little easier to implement dynamic page loading. However, in our case, the HTML we need is actually even narrower - we want just the record content, not any of the surrounding page from Pages. For this reason, in the done handler we select just the contents of the #elCmsPageWrap element, and use that as our record content.

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.

For more advanced sites built with Pages, you may want to change the output of a custom HTML or PHP block depending on which page the user is viewing. For example, if you have a custom menu, you may want to highlight the active item.
We can implement this in Pages by checking the underlying page URL parameters. Although you access a page with a friendly URL (FURL) like http://<yourcommunity>/section/page, behind the scenes this is mapped to a raw URL, such as http://<yourcommunity>/index.php?app=cms&module=pages&controller=page&path=/section/page. Notice the path parameter allows us to identify which page we're accessing. When we access the \IPS\Request::i() object, we can compare against this parameter, like so:
{{if strpos( \IPS\Request::i()->path, 'section/page' ) !== FALSE}} <!-- We know the user is on /section/page --> {{elseif strpos( \IPS\Request::i()->path, 'othersection/otherpage' ) !== FALSE}} <!-- We know the user is on /othersection/otherpage --> {{endif}} Note that for reliability, we're using PHP's strpos function to check for the presence of the page URL in the path parameter, rather than a simple comparison.
Example
Let's assume we've created a Manual HTML block, we're adding HTML to show a menu, and we want to highlight the correct item based on the page. Here's what our block contents might look like:
<ul class='ipsList_inline cMyMenu'> <li {{if strpos( \IPS\Request::i()->path, 'help/home' ) !== FALSE}}class='active'{{endif}}> <a href='/help/home'>Home</a> </li> <li {{if strpos( \IPS\Request::i()->path, 'help/faq' ) !== FALSE}}class='active'{{endif}}> <a href='/help/faq'>FAQ</a> </li> <li {{if strpos( \IPS\Request::i()->path, 'help/tutorials' ) !== FALSE}}class='active'{{endif}}> <a href='/help/tutorials'>Tutorials</a> </li> </ul> If we had many items to show, it would get tedious to list them all like this. We could instead do it as a loop:
// Using a PHP variable to store an array of pages => page names that we'll loop over {{$myPages = array('help/home' => "Home", 'help/faq' => "FAQ", 'help/tutorials' => "Tutorials", 'help/qna/listing' => "Questions", 'help/qna/recent' => "Recent Questions", 'help/contact' => "Contact Us");}} <ul class='ipsList_inline cMyMenu'> {{foreach $myPages as $url => $title}} <li {{if strpos( \IPS\Request::i()->path, $url ) !== FALSE}}class='active'{{endif}}> <a href='{$url}'>{$title}</a> </li> {{endforeach}} </ul> Now to add new items to our custom menu, we just have to add them to the array.

By default, we use the 'comments' icon from FontAwesome to represent forums on the read/unread badges. IPS4 also includes an option to upload an image that will be used instead of the icon. But what if you want to use a different FontAwesome icon for each forum?
The good news is this is possible using some custom CSS. Each forum row in the index template includes a data attribute with the forum ID, meaning we can write a style to specifically target each individual forum and overwrite the icon it uses.
Note: Although this method isn't terribly complex, it does require editing custom CSS and working with unicode characters.
 
Determining the icon unicode value
The method we're going to use involves replacing the icon using a CSS rule, rather than changing the icon classname in the HTML. The reason we take this approach is it won't make upgrading your templates difficult later - our custom CSS persist through IPS4 versions easily.
What this means however is that we need to identify the unicode value that FontAwesome assigns to the icons we want to use.
To do so, head over to the FontAwesome icon list on this page. Locate the icon you'd like to use, and click it. On the information page, you'll see the unicode value for the icon. Make a note of this code. For example:

Do this for each icon you'll want to use.
 
Adding the CSS
We're going to add our CSS to our custom.css file so that it persists through upgrades. In the AdminCP, go to Customizations -> Themes, and click the code edit icon next to the theme you want to change. On the CSS tab, open the custom.css file:

The rule we need to use looks like this:
[data-forumid="..."] .fa-comments:before { content: "\f123"; } You'll need to adjust this code to include the forum ID for the forum you want to change. You can find the forum ID by hovering on the link to the forum, and noting the number you see in the URL: 

You'll also need to replace the f123 unicode value with the one for the icon you want to use that you noted earlier.
 
Example
Let's say we have forum ID's 1 and 2, and we want to use FontAwesome's bicycle and car icons, respectively. We note the unicode values for those icons, which are f206 and f1b9.
The CSS we'd add looks like this:
[data-forumid="1"] .fa-comments:before { content: "\f206"; } [data-forumid="2"] .fa-comments:before { content: "\f1b9"; } Once we save it, we can see the result:

By default, we use the 'comments' icon from FontAwesome to represent forums on the read/unread badges. IPS4 also includes an option to upload an image that will be used instead of the icon. But what if you want to use a different FontAwesome icon for each forum?
The good news is this is possible using some custom CSS. Each forum row in the index template includes a data attribute with the forum ID, meaning we can write a style to specifically target each individual forum and overwrite the icon it uses.
Note: Although this method isn't terribly complex, it does require editing custom CSS and working with unicode characters.
 
Determining the icon unicode value
The method we're going to use involves replacing the icon using a CSS rule, rather than changing the icon classname in the HTML. The reason we take this approach is it won't make upgrading your templates difficult later - our custom CSS persist through IPS4 versions easily.
What this means however is that we need to identify the unicode value that FontAwesome assigns to the icons we want to use.
To do so, head over to the FontAwesome icon list on this page. Locate the icon you'd like to use, and click it. On the information page, you'll see the unicode value for the icon. Make a note of this code. For example:

Do this for each icon you'll want to use.
 
Adding the CSS
We're going to add our CSS to our custom.css file so that it persists through upgrades. In the AdminCP, go to Customizations -> Themes, and click the code edit icon next to the theme you want to change. On the CSS tab, open the custom.css file:

The rule we need to use looks like this:
[data-forumid="..."] .fa-comments:before { content: "\f123"; } You'll need to adjust this code to include the forum ID for the forum you want to change. You can find the forum ID by hovering on the link to the forum, and noting the number you see in the URL: 

You'll also need to replace the f123 unicode value with the one for the icon you want to use that you noted earlier.
 
Example
Let's say we have forum ID's 1 and 2, and we want to use FontAwesome's bicycle and car icons, respectively. We note the unicode values for those icons, which are f206 and f1b9.
The CSS we'd add looks like this:
[data-forumid="1"] .fa-comments:before { content: "\f206"; } [data-forumid="2"] .fa-comments:before { content: "\f1b9"; } Once we save it, we can see the result:

By default, we use the 'comments' icon from FontAwesome to represent forums on the read/unread badges. IPS4 also includes an option to upload an image that will be used instead of the icon. But what if you want to use a different FontAwesome icon for each forum?
The good news is this is possible using some custom CSS. Each forum row in the index template includes a data attribute with the forum ID, meaning we can write a style to specifically target each individual forum and overwrite the icon it uses.
Note: Although this method isn't terribly complex, it does require editing custom CSS and working with unicode characters.
 
Determining the icon unicode value
The method we're going to use involves replacing the icon using a CSS rule, rather than changing the icon classname in the HTML. The reason we take this approach is it won't make upgrading your templates difficult later - our custom CSS persist through IPS4 versions easily.
What this means however is that we need to identify the unicode value that FontAwesome assigns to the icons we want to use.
To do so, head over to the FontAwesome icon list on this page. Locate the icon you'd like to use, and click it. On the information page, you'll see the unicode value for the icon. Make a note of this code. For example:

Do this for each icon you'll want to use.
 
Adding the CSS
We're going to add our CSS to our custom.css file so that it persists through upgrades. In the AdminCP, go to Customizations -> Themes, and click the code edit icon next to the theme you want to change. On the CSS tab, open the custom.css file:

The rule we need to use looks like this:
[data-forumid="..."] .fa-comments:before { content: "\f123"; } You'll need to adjust this code to include the forum ID for the forum you want to change. You can find the forum ID by hovering on the link to the forum, and noting the number you see in the URL: 

You'll also need to replace the f123 unicode value with the one for the icon you want to use that you noted earlier.
 
Example
Let's say we have forum ID's 1 and 2, and we want to use FontAwesome's bicycle and car icons, respectively. We note the unicode values for those icons, which are f206 and f1b9.
The CSS we'd add looks like this:
[data-forumid="1"] .fa-comments:before { content: "\f206"; } [data-forumid="2"] .fa-comments:before { content: "\f1b9"; } Once we save it, we can see the result:

By default, we use the 'comments' icon from FontAwesome to represent forums on the read/unread badges. IPS4 also includes an option to upload an image that will be used instead of the icon. But what if you want to use a different FontAwesome icon for each forum?
The good news is this is possible using some custom CSS. Each forum row in the index template includes a data attribute with the forum ID, meaning we can write a style to specifically target each individual forum and overwrite the icon it uses.
Note: Although this method isn't terribly complex, it does require editing custom CSS and working with unicode characters.
 
Determining the icon unicode value
The method we're going to use involves replacing the icon using a CSS rule, rather than changing the icon classname in the HTML. The reason we take this approach is it won't make upgrading your templates difficult later - our custom CSS persist through IPS4 versions easily.
What this means however is that we need to identify the unicode value that FontAwesome assigns to the icons we want to use.
To do so, head over to the FontAwesome icon list on this page. Locate the icon you'd like to use, and click it. On the information page, you'll see the unicode value for the icon. Make a note of this code. For example:

Do this for each icon you'll want to use.
 
Adding the CSS
We're going to add our CSS to our custom.css file so that it persists through upgrades. In the AdminCP, go to Customizations -> Themes, and click the code edit icon next to the theme you want to change. On the CSS tab, open the custom.css file:

The rule we need to use looks like this:
[data-forumid="..."] .fa-comments:before { content: "\f123"; } You'll need to adjust this code to include the forum ID for the forum you want to change. You can find the forum ID by hovering on the link to the forum, and noting the number you see in the URL: 

You'll also need to replace the f123 unicode value with the one for the icon you want to use that you noted earlier.
 
Example
Let's say we have forum ID's 1 and 2, and we want to use FontAwesome's bicycle and car icons, respectively. We note the unicode values for those icons, which are f206 and f1b9.
The CSS we'd add looks like this:
[data-forumid="1"] .fa-comments:before { content: "\f206"; } [data-forumid="2"] .fa-comments:before { content: "\f1b9"; } Once we save it, we can see the result:

By default, we use the 'comments' icon from FontAwesome to represent forums on the read/unread badges. IPS4 also includes an option to upload an image that will be used instead of the icon. But what if you want to use a different FontAwesome icon for each forum?
The good news is this is possible using some custom CSS. Each forum row in the index template includes a data attribute with the forum ID, meaning we can write a style to specifically target each individual forum and overwrite the icon it uses.
Note: Although this method isn't terribly complex, it does require editing custom CSS and working with unicode characters.
 
Determining the icon unicode value
The method we're going to use involves replacing the icon using a CSS rule, rather than changing the icon classname in the HTML. The reason we take this approach is it won't make upgrading your templates difficult later - our custom CSS persist through IPS4 versions easily.
What this means however is that we need to identify the unicode value that FontAwesome assigns to the icons we want to use.
To do so, head over to the FontAwesome icon list on this page. Locate the icon you'd like to use, and click it. On the information page, you'll see the unicode value for the icon. Make a note of this code. For example:

Do this for each icon you'll want to use.
 
Adding the CSS
We're going to add our CSS to our custom.css file so that it persists through upgrades. In the AdminCP, go to Customizations -> Themes, and click the code edit icon next to the theme you want to change. On the CSS tab, open the custom.css file:

The rule we need to use looks like this:
[data-forumid="..."] .fa-comments:before { content: "\f123"; } You'll need to adjust this code to include the forum ID for the forum you want to change. You can find the forum ID by hovering on the link to the forum, and noting the number you see in the URL: 

You'll also need to replace the f123 unicode value with the one for the icon you want to use that you noted earlier.
 
Example
Let's say we have forum ID's 1 and 2, and we want to use FontAwesome's bicycle and car icons, respectively. We note the unicode values for those icons, which are f206 and f1b9.
The CSS we'd add looks like this:
[data-forumid="1"] .fa-comments:before { content: "\f206"; } [data-forumid="2"] .fa-comments:before { content: "\f1b9"; } Once we save it, we can see the result:

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; }  

Description
We make use of an icon font called FontAwesome. This enables us to display icons that are accessible, that don't require an additional HTTP request, that can be styled with CSS (and inherit styling automatically), and which scale without loss of quality.
 
Usage
An icon can be included within the markup by using the following code:
<i class='fa fa-iconname'></i> The list of possible icons and their classnames is available at http://fontawesome.io/icons/. Note that these classnames are not prefixed with ips as with other framework classes; they are left with their default names as they appear on the FontAwesome website.
Icons can be used anywhere that HTML can be used. For example, within text, on buttons, in menus and more.
    Icon on a button    A caret icon indicates a dropdown     Yes, I think so   No, I disagree   This is another caret  
Icon consistency
It is important that icon use remains relatively consistent throughout the suite. This applies to core developers as well as addon developers. If different icons are used for the same purpose (or worse, an icon is used for a purpose different to it's usual purpose), users will become confused by the software.
To help alleviate this, we have a list of icons that we generally refer to when choosing an icon to represent an action. Check this list to see if your action already has an associated icon, and lean towards using that instead of choosing another.
The list below organizes actions, with the title being a general concept. The icon names are FontAwesome icons, without the preceding fa-
 
Adding
  plus-circle   plus Deleting
  times-circle   trash-o Editing
  pencil Reverting
  undo Go Somewhere
  arrow-right Open External Link
  external-link Confirming Yes/No
  check   times Permissions
  lock   unlock Log In/Sign In
  key Copy
  copy Settings
  cog Flagging On/Off
  flag   flag-o Star On/Off
  star   star-o Developer/Application
  cogs Help
  question-circle Merge
  level-up Code/PHP/HTML
  code Mail/Send Mail
  envelope-o Search
  search View
  search Refresh/Reload
  refresh Execute/Run Now
  play-circle Easy Mode/Visual Editor
  magic  

We can now tie everything together with some Javascript. It's with the Javascript that everything will feel snappy and interactive. Begin by heading over to the template editor, and editing the Javascript file we created earlier.
The Javascript controller we write will do two things:
Load the first record when the page is loaded Handle click events on the other records to load the ones the user clicks Here's the final Javascript code you need to insert into the file. We'll explain it shortly:
 
This is a standard IPS4 javascript controller; refer to the controller documentation for more information.
In our initialize method (called automatically when the controller is initialized), we set up an event handler for clicking on elements with the data-releaseID attribute (if you remember, we gave items in our record listing this attribute). We bind this handler to the showRelease method.
We then call the setup method. The logic in this method selects a record to load automatically, so that the page has content in it when the user first loads it. It tries to find a record with the data-currentRelease attribute, but if one doesn't exist, it will load the first item in the list instead.
Finally, there's the showRelease method which has the job of loading and displaying the record view, pulled dynamically via AJAX. To do this, we find the relevant URL from the record row and then fire an AJAX request. In the done handler, we update the div that holds our record content.
When a Pages URL is called via AJAX (whether it's a normal page, or a database), it will only return the page content - it won't include the complete site wrapper. This makes it a little easier to implement dynamic page loading. However, in our case, the HTML we need is actually even narrower - we want just the record content, not any of the surrounding page from Pages. For this reason, in the done handler we select just the contents of the #elCmsPageWrap element, and use that as our record content.

We can now tie everything together with some Javascript. It's with the Javascript that everything will feel snappy and interactive. Begin by heading over to the template editor, and editing the Javascript file we created earlier.
The Javascript controller we write will do two things:
Load the first record when the page is loaded Handle click events on the other records to load the ones the user clicks Here's the final Javascript code you need to insert into the file. We'll explain it shortly:
 
This is a standard IPS4 javascript controller; refer to the controller documentation for more information.
In our initialize method (called automatically when the controller is initialized), we set up an event handler for clicking on elements with the data-releaseID attribute (if you remember, we gave items in our record listing this attribute). We bind this handler to the showRelease method.
We then call the setup method. The logic in this method selects a record to load automatically, so that the page has content in it when the user first loads it. It tries to find a record with the data-currentRelease attribute, but if one doesn't exist, it will load the first item in the list instead.
Finally, there's the showRelease method which has the job of loading and displaying the record view, pulled dynamically via AJAX. To do this, we find the relevant URL from the record row and then fire an AJAX request. In the done handler, we update the div that holds our record content.
When a Pages URL is called via AJAX (whether it's a normal page, or a database), it will only return the page content - it won't include the complete site wrapper. This makes it a little easier to implement dynamic page loading. However, in our case, the HTML we need is actually even narrower - we want just the record content, not any of the surrounding page from Pages. For this reason, in the done handler we select just the contents of the #elCmsPageWrap element, and use that as our record content.

For most admins, creating a theme with the Easy Editor is the best option. It allows you to customize the default theme in a point-and-click environment and see your changes in real-time, and requires no coding skills whatsoever.
 
Creating the theme
To create the theme we'll edit, navigate to Customization -> Themes in the AdminCP. Click the Add Theme button. In the popup window, ensure the Easy Mode option is selected (it's the default), and then click Next. 
On the next screen, you can configure some choices about your new theme:
Name (required)
As it will appear to users of your site Parent
You can make this theme a child of another, meaning it will automatically inherit any style/template changes from the parent theme Default theme
Makes this theme the default for guests and members who have not specifically chosen another theme Available for
Sets permissions for which groups can use this theme. Example use: a theme that only 'premium' users can access as an added benefit of paying Click Save once you have filled in the information. Your theme will be created and you'll be returned to the theme listing.
 
Launching the Easy Mode editor
From the theme listing in the AdminCP, you can click the magic wand icon on any Easy Mode theme to launch the visual editor (you will need to be logged into the front-end of your community to use the visual editor):

Note: You can launch the visual editor at any time, even long after you've created the theme. However, if you convert an Easy Mode theme to a normal theme, you can't go back and use the visual editor.
Launching the visual editor will take you to your community in editing mode (that only you can see). Your community will be shown on the left, with editing tools available in a panel on the right:

 
The visual editor has a few key functions to help you design your theme. We'll cover each in turn.
 
1. Colorize
This tool lets you instantly change all of the theme colors to different shades of another color. Click the Colorize button, and you'll see four swatches:

Clicking a swatch and choosing a new color will immediately update the live preview to show you the result.

The colorize tool is great as a first step - if you know you want a red theme (for example), you can use it to get the basics done, and then fine-tune the resulting colors later using the other tools.
If you don't like the result, you can click the Revert Colorizer button to undo your changes.
 
2. Select tool
The Select tool allows you to point-and-click at sections of pages on your community, and the visual editor will automatically show you the color editor for the closest available parts.

 
3. Custom CSS
If you are familiar with CSS, the Easy Mode editor gives you the ability to add custom CSS to your theme without needing to convert it to a full manual theme. Simply click the CSS button, and a code editor will be shown for you to use. And yes, you still get the live preview!
 
4. Style editor
The available styles you can edit are listed in the main panel. Click one to see the color swatches and to edit the colors. Some styles allow you to edit just the background, others will also allow you to edit the font color.

Background colors can also be turned into gradients by clicking the    button. To use it, you choose a direction in which the gradient should go, and then add colors to form the gradient.

 
5. Build
The Build tab is where you'll go once you're happy with your changes and want to save them. Click the Save Theme button to do so. This will save your changes and make them live to any users who have chosen this theme.
 
 

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.

For most admins, creating a theme with the Easy Editor is the best option. It allows you to customize the default theme in a point-and-click environment and see your changes in real-time, and requires no coding skills whatsoever.
 
Creating the theme
To create the theme we'll edit, navigate to Customization -> Themes in the AdminCP. Click the Add Theme button. In the popup window, ensure the Easy Mode option is selected (it's the default), and then click Next. 
On the next screen, you can configure some choices about your new theme:
Name (required)
As it will appear to users of your site Parent
You can make this theme a child of another, meaning it will automatically inherit any style/template changes from the parent theme Default theme
Makes this theme the default for guests and members who have not specifically chosen another theme Available for
Sets permissions for which groups can use this theme. Example use: a theme that only 'premium' users can access as an added benefit of paying Click Save once you have filled in the information. Your theme will be created and you'll be returned to the theme listing.
 
Launching the Easy Mode editor
From the theme listing in the AdminCP, you can click the magic wand icon on any Easy Mode theme to launch the visual editor (you will need to be logged into the front-end of your community to use the visual editor):

Note: You can launch the visual editor at any time, even long after you've created the theme. However, if you convert an Easy Mode theme to a normal theme, you can't go back and use the visual editor.
Launching the visual editor will take you to your community in editing mode (that only you can see). Your community will be shown on the left, with editing tools available in a panel on the right:

 
The visual editor has a few key functions to help you design your theme. We'll cover each in turn.
 
1. Colorize
This tool lets you instantly change all of the theme colors to different shades of another color. Click the Colorize button, and you'll see four swatches:

Clicking a swatch and choosing a new color will immediately update the live preview to show you the result.

The colorize tool is great as a first step - if you know you want a red theme (for example), you can use it to get the basics done, and then fine-tune the resulting colors later using the other tools.
If you don't like the result, you can click the Revert Colorizer button to undo your changes.
 
2. Select tool
The Select tool allows you to point-and-click at sections of pages on your community, and the visual editor will automatically show you the color editor for the closest available parts.

 
3. Custom CSS
If you are familiar with CSS, the Easy Mode editor gives you the ability to add custom CSS to your theme without needing to convert it to a full manual theme. Simply click the CSS button, and a code editor will be shown for you to use. And yes, you still get the live preview!
 
4. Style editor
The available styles you can edit are listed in the main panel. Click one to see the color swatches and to edit the colors. Some styles allow you to edit just the background, others will also allow you to edit the font color.

Background colors can also be turned into gradients by clicking the    button. To use it, you choose a direction in which the gradient should go, and then add colors to form the gradient.

 
5. Build
The Build tab is where you'll go once you're happy with your changes and want to save them. Click the Save Theme button to do so. This will save your changes and make them live to any users who have chosen this theme.
 
 

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; }  

Description
The messages module provides a way to style informational messages to bring something to the user's attention.
 
Usage
To create a message, simply add the ipsMessage class to a container element (e.g. div), along with one of the message styles below. The message style class will automatically add the appropriate icon to your message box.
 
Message styles
Error - ipsMessage_error
This is an error message. Success - ipsMessage_success
This message indicates something happened successfully. Warning - ipsMessage_warning
This message warns the user of something terrible (or not so terrible). Information - ipsMessage_info
This message provides general information.  
Message codes
If you need to add a code to your message, such as an error number, you can do so using the ipsMessage_code class:
<div class='ipsMessage ipsMessage_error'> <span class='ipsMessage_code'>12345</span> This is an error message. </div> 12345 This is an error message.  

What is a theme?
A theme is a package that changes how the IPS Community Suite looks. By default, the software has a blue theme (it's the one you see here on our own community), but with themes you can completely change that, including colors, fonts, images and much more. With a little skill, your imagination is the limit!
Above all, themes are a great way to keep consistent branding between your main website and your community.
 
Where do you get themes?
Themes can come from a few different sources, including:
Our Marketplace, for free or paid Created yourself using the Easy Mode editor Created yourself using the full theme editor (for advanced users) Some designers run their own sites that offer ready-made themes for purchase/download You can hire a designer to create a theme especially for your community   
Multiple themes
Although many communities have one theme that matches their brand, it's also possible to install multiple themes and let users choose between them. You can select a default as your 'main' theme, and users can choose their own preference from the theme selector at the bottom of the page. You can even restrict themes to certain member groups, allowing you to have 'premium' themes for paid members (for example). We'll cover how to do all this and more in a later step.

Basics
The button classes described here can be applied to any element, although typically would be applied to an element like a, input[type="submit"] or button so that the user can interact with it.
As a minimum, a button should receive the basic ipsButton class, plus a size class and a style class (explained below).
 
Button styles
ipsButton_normal
Normal button ipsButton_primary
Primary button ipsButton_alternate
Alternate button ipsButton_important
Important button ipsButton_light
Light button ipsButton_veryLight
Very light button ipsButton_overlaid
Overlaid button ipsButton_link
Link button  
Button sizes
ipsButton_medium
Medium button ipsButton_verySmall
Very small button ipsButton_small
Small button ipsButton_large
Large button ipsButton_veryLarge
Very large button ipsButton_fullWidth
Can be combined with another size, above.
Full width button  
Disabled buttons
Buttons can be visually disabled either by adding the class ipsButton_disabled, or, on relevant input elements, adding the disabled property. For example:
<a href='#' class='ipsButton ipsButton_normal ipsButton_medium ipsButton_disabled'>Disabled button (link)</a> <input type='submit' class='ipsButton ipsButton_normal ipsButton_medium' disabled value='Disabled button (input)'> These would render like so:
Disabled button (link)  
Split buttons
Split buttons allow you to create toolbars easily by specifying a list of buttons that display joined to each other.
They are created by specifying the class ipsButton_split on a wrapper element containing two or more buttons. The wrapper element can be a <ul> tag, or any other that makes sense for your use.
All of the buttons in a split button group should be the same size, otherwise results are unpredictable. Different styles can be used on each button, though.
<ul class='ipsButton_split'> <li><a href='#' class='ipsButton ipsButton_small ipsButton_primary'>Button 1</a></li> <li><a href='#' class='ipsButton ipsButton_small ipsButton_light'>Button 2</a></li> <li><a href='#' class='ipsButton ipsButton_small ipsButton_light'>Button 3</a></li> </ul> Button 1 Button 2 Button 3  

Description
We make use of an icon font called FontAwesome. This enables us to display icons that are accessible, that don't require an additional HTTP request, that can be styled with CSS (and inherit styling automatically), and which scale without loss of quality.
 
Usage
An icon can be included within the markup by using the following code:
<i class='fa fa-iconname'></i> The list of possible icons and their classnames is available at http://fontawesome.io/icons/. Note that these classnames are not prefixed with ips as with other framework classes; they are left with their default names as they appear on the FontAwesome website.
Icons can be used anywhere that HTML can be used. For example, within text, on buttons, in menus and more.
    Icon on a button    A caret icon indicates a dropdown     Yes, I think so   No, I disagree   This is another caret  
Icon consistency
It is important that icon use remains relatively consistent throughout the suite. This applies to core developers as well as addon developers. If different icons are used for the same purpose (or worse, an icon is used for a purpose different to it's usual purpose), users will become confused by the software.
To help alleviate this, we have a list of icons that we generally refer to when choosing an icon to represent an action. Check this list to see if your action already has an associated icon, and lean towards using that instead of choosing another.
The list below organizes actions, with the title being a general concept. The icon names are FontAwesome icons, without the preceding fa-
 
Adding
  plus-circle   plus Deleting
  times-circle   trash-o Editing
  pencil Reverting
  undo Go Somewhere
  arrow-right Open External Link
  external-link Confirming Yes/No
  check   times Permissions
  lock   unlock Log In/Sign In
  key Copy
  copy Settings
  cog Flagging On/Off
  flag   flag-o Star On/Off
  star   star-o Developer/Application
  cogs Help
  question-circle Merge
  level-up Code/PHP/HTML
  code Mail/Send Mail
  envelope-o Search
  search View
  search Refresh/Reload
  refresh Execute/Run Now
  play-circle Easy Mode/Visual Editor
  magic  

Padding
ipsPad
15px padding on desktop
ipsPad_half
7px padding on desktop
ipsPad_double
30px padding on desktop
The padding classes are scaled appropriately on mobile devices.
 
Spacing
ipsSpacer_top
15px top margin
ipsSpacer_bottom
15px bottom margin
ipsSpacer_both
15px top and bottom margin
ipsSpacer_half
When combined with one of the above, halves the spacing
ipsSpacer_double
When combined with one of the above, doubles the spacing
 
Clearing
ipsClear
Clears floats preceding the element this class is applied to
ipsClearfix
The popular 'clearfix' technique, which causes a wrapper element with this class applied to fully wrap elements contained within it, even if they are floated. This class should be applied to all elements where descendents may be floated.
 
Positioning
For text positioning, see typography.
ipsPos_left
Floats the element left
ipsPos_right
Floats the element right
ipsPos_center
Sets automatic margins on the element in order to center it. Block elements will require a width to be set for this to be noticeable, otherwise they will naturally display at 100% width.
 
Horizontal rules
Horizontal rules can be styled simply by adding the class ipsHr to a standard <hr> element.
 
Notification counts
ipsNotificationCount is a class for a floating bubble which can denote a notification count of some kind. The parent element should have a non-static position for this class to work correctly. By default, the notification bubble will be offset to the top and right, but this could be overwritten with additional specific styles if desired. Usage:
<!-- The element the notification belongs to --> <!-- position: relative; is set inline here, but avoid that in practice --> <a href='#' class='ipsButton ipsButton_primary ipsButton_medium' style='position:relative'> A button with notification <span class='ipsNotificationCount'>12</span> </a> This would render:
A button with notification12  
Online/Offline status
Provides simple styling to denote whether something (a user, for example) is online or offline. ipsOnlineStatus is the base class; add ipsOnlineStatus_online or ipsOnlineStatus_offline to denote the actual status.
<strong class='ipsOnlineStatus ipsOnlineStatus_online'><i class='fa fa-circle'></i> Online</strong><br> <strong class='ipsOnlineStatus ipsOnlineStatus_offline'><i class='fa fa-circle'></i> Offline</strong>   Online
  Offline  
Cursors
Several classes are provided as shortcuts for changing the mouse cursor on elements.
ipsCursor_locked
"No permission" cursor (example)
ipsCursor_drag
Shows an element can be moved (example)
ipsCursor_pointer
Shows an element can be clicked (example)
ipsCursor_help
Shows an element provides help (example)
ipsCursor_default
Sets the cursor to the default state (example)