Rikki

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.

Record display - record template (See diff) This is the main template for the display portion of our database. Here's the final code: There isn't too much going on here that hasn't already been explained. We're using the customFieldDisplayByKey method of the record to output our formatted fields, although we're using the display type this time: {$record->customFieldDisplayByKey('security_release', 'display')|raw} We also check the raw field value of the Additional Information field to determine whether there's any content to display for it. As before, you'll need to replace the ID number with the correct one from your own database: {{if $record->fieldValues()['field_164']}} ... {{endif}} We also strip out features we know aren't needed in this case: following, reputation, pager controls for moving between records (the latter isn't needed because all of our records are shown in the listing on the same page!).

How the Release Notes section is structured Before we start editing the templates, it would be helpful to understand how the finished section is going work. By default in Pages database, you see a record listing (which uses the Listing templates), you click through to a record which loads a new page to show it (which uses the Display templates). In our Release Notes database however, there's no page reload - the record is loaded dynamically via AJAX. This is achieved by mixing both the Listing and Display templates. The wrapper of the page and the version list on the left is built using the Listing templates. However, when a record is clicked and loaded dynamically, that portion of the page is using the Display template: Now that the structure is clear, it's finally time to start editing templates! Tip Each template discussed below and in the next step includes a link to a diff report so that you can easily compare the changes we've made to the default template. Listing header - categoryHeader template (See diff) The first template we'll work on is the category header. This shows the header of the category (which in our case is actually the header of the whole section, since the user doesn't leave this page while using the database). The categoryHeader template handles the title, the follow button, the Add Record button and more. Here's the final code for this template bit, which I'll explain below. This template is pretty similar to the default. The key things that have changed: Positioning/styling of the title, description and follow button I have removed the list item that contained the 'mark as read' link, since we don't use this functionality I have wrapped the tool list bar in {{if $category->can('add')}} since only those with permission to add records need to see these elements. Listing table - categoryTable template (See diff) The categoryTable template is the 'meat' of the listing view; it generates the table into which record rows are displayed. This template is modified quite heavily from the default, in part due to a lot of unused code being removed. Note: templates often contain a lot of code that is used when a certain option is enabled for the database. This code is wrapped in a logic check so it's only displayed if that option is enabled. It is my preference to remove these unused portions of code when I'm certain I don't need the feature they display; it makes the template more succinct and easier to read. Here's the final code for this template bit: Here's the key changes: There's some simple style changes to get the output to look how we want Note that on the wrapper element, we initialize a Javascript controller, pages.front.releaseNotes.main. This controller will be created in the Javascript file we set up earlier. A lot of code we don't need for our use is removed; the moderation tools and sorting/filter options. An empty div is added in the fluid column, with a data-role attribute. This is the div that will hold a record when it is loaded into the page. Listing row - recordRow template (See diff) This template generates each row of the listing table. It's the first template where we're doing something special, so I'll cover those parts below. Here's the final code: As with the previous template, a lot of unused code has been removed. The first few lines are setup that also exist in the default. Following those, we go into the main loop which iterates over each of our rows and generates the HTML for each. The first part I want to highlight is the <a> element. Notice we've applied a custom classname which we'll use for styling. We've also added a data-releaseID attribute, the value of which is the ID of the record. This is important because we'll use it to load the correct record later when the user clicks this record in the listing. Accessing raw field values On the same line, you'll see this: {{if $row->fieldValues()['field_163']}}data-currentRelease{{endif}} What's happening here is we are calling $row->fieldValues() (which returns an array of all the field values for the row), and using it to determine if field_163 is true. If it is, we mark this as our current release with a data attribute. You would be correct to assume then that field 163 is the current release field we set up. Unfortunately we have to refer to it by ID rather than key when using the fieldValues() method, which does complicate this check slightly. Note: In your own database, the current release field will have a different ID. Replace field_163 with whatever the field ID is in your setup. Accessing formatted field output A few times within this template, you'll see a call like this: {$row->customFieldDisplayByKey('security-release', 'listing')|raw} This is returning the output of one of our custom fields (the security_release toggle in this case). It returns the generated HTML from our formatting options that we set up for the field. This is what makes custom formatters so useful - we can keep the output for the field neatly managed on the field edit screen, and simply insert it into our templates with the simple tag above. Notice we pass the listing value for the second parameter. This is indicating we want the listing format (if you recall, you can create formatting for both the listing and display templates).

About database templates In Pages, there are four kinds of basic database template: Listing The templates that show the list of records. If you use categories, this is the template used when you click into a category. if you don't use categories but do use a record listing, this is the template that forms the index/homepage of the database. Form A template that allows you to customize the add/edit form for records in your database. Display Templates used when displaying a record, including the comments & reviews portions. Category Index If you use categories, these categories generate the category listing. This forms the index/homepage of the database, but also renders any sub-categories once you click through. In addition, there's some other templates that are used when you use a database in its 'article' mode. You can create new versions of the above templates and assign them to your database. Each database can use a different set of templates, so it's possible to have very unique areas of your site, each different from the others. Templates are also extremely powerful. You have access to a large amount of data in them, and all of the usual IPS Community Suite template syntax is available including HTML logic, template tags and raw PHP (see the Template Syntax guide for more information). With some creativity, and knowledge of HTML and template syntax, you can create databases that don't at all feel like the usual 'list of records' approach. Creating our database templates Since we don't use categories in our Release Notes database, we don't need to create a set of those templates. Similarly, we aren't going to be concerned with the record form template; the default will be fine for our use. That leaves us with the Listing and Display templates, and we'll create new sets so we can customize them without impacting any other databases. To create them, head over to Pages -> Templates. In the left-hand panel of the template editor, you can click to expand the existing database templates and get a feel for how they are structured. Click the New button in the editor, and then select New Database Template. For the name, we'll enter ReleaseNotes so that we can easily identify it later. Ensure that Record Listing is selected as the template type. Conveniently, this popup window allow allows us to assign the templates to a database right now, so choose the Release Notes database for this field. Note: if you don't assign the template to the database here, you can always do so later by editing the database itself and selecting this template set under the Options tab. Click Save to create the template set. Repeat this process to create a Record Display type. Note that the name should still be ReleaseNotes - by using the same name, all of the template bits for both template types will exist in one group, which (in my opinion) makes it a little easier to use. You can create a separate group for each type if you prefer, however. Exploring the templates If you now expand the Database Templates category in the editor, you'll see the two new sets we've created. If you expand those, you'll see a dozen or so template bits that make up the set. We won't be editing all of these in later steps; some won't be used in what we're doing, and others are fine as default. When later steps refer to editing a database template bit, this is where you'll go to do so. Customizing our listing template Using custom CSS & JS

It's often useful to transform raw values in some way, and this is achieved in IPS4 with template plugins. Template plugins take a value, and optionally some arguments, and output some transformed value. The syntax for template tags is: {pluginkey="<value>" argument="..."} The value can be a normal string, or it could be a variable coming from elsewhere. Template plugins can always be used in templates, but some can also be used in CSS files. Those that can are identified below. Available plugins {advertisement="$location"} The HTML for the specified ad location Parameters $location - A valid advertisement location {datetime="$timestamp" dateonly="[boolean]" norelative="[boolean]" lowercase="[boolean]" short="[boolean]"} Shows a time formatted according to the user's locale Parameters $timestamp - A timestamp to transform into a date dateonly - Show only the date (with no time) norelative - By default, relative times will be used (e.g. 8 hours ago). To always show an absolute date/time, set this to true. lowercase - By default, date strings will be capitalized where necessary (e.g. Yesterday, 8:32pm). Setting this to true ensures it is lowercase, for use in a sentence. short - Uses a very short date format (ideal for mobile devices) {expression="$expression" raw="[boolean]"} Allows the result of arbitrary PHP expressions to be inserted into templates. The result of the expression is output. Can be used in CSS files. Parameters $expression - A valid PHP expression that produces output of some kind raw - By default, the result of the expression is HTML-escaped. Setting this parameter to true outputs the raw result. Be careful! This can be a security risk. {file="$file" extension="[string]"} Outputs the URL to a file stored by IPS4's file handling classes. Can be used in CSS files. Parameters $file - Either an instance of the \IPS\File class, or a string representing the stored URL to the file extension - The file storage extension used to originally store the file, e.g. calendar_Events. If none is specified, core_Attachment is assumed. {filesize="$sizeInBytes" decimal="[boolean]"} Formats the specified filesize and outputs an appropriate human-readable form. Parameters $sizeInBytes - An integer representing a file size, in bytes, to be formatted decimal - Whether the filesize should be treated as a KB (i.e. 1kb = 1024 bytes) or 1 = 1000. All values are always rounded to one decimal place. {insert="$filename"} Includes a PHP script file Parameters $filename - The filename of the PHP file to include. The output of the file is buffered and output. {lang="$languageKey" sprintf="[string]" htmlsprintf="[string]" pluralize="[string]" wordbreak="[boolean]" ucfirst="[boolean]"} Inserts a phrase from the language system in the user's chosen language. Paramaters $languageKey - The key of the language phrase to insert sprintf - Comma-separated list of values to replace in the language string. These values are HTML-escaped. htmlsprintf - Comma-separated list of values to replace in the language string. These values are not escaped. Be careful! pluralize - Comma-separated list of values to pass into any pluralize statements in the language string. wordbreak - If true, adds <wbr> tags to the returned string to help prevent strings that break the page width. ucfirst - Determines whether the first character of the string should be made uppercase. {member="$propertyToDisplay" id="[integer]" group="[boolean]" raw="[boolean]"} Outputs the property or result of a method called on the member object. Parameters $propertyToDisplay - One of the properties or methods available on the member object. For example: link() or name. id - Member ID to load and display. If not specified, the current member is used. group - If true, this tag works on the member's group instead (and so the $propertyToDisplay should be one of the group properties or methods instead) raw - By default, the returned output is HTML escaped. Setting this to true means the output won't be escaped. Be careful! {number="$number"} Formats a number according to the user's locale (e.g. with commas or periods) Parameters $number - Number to format {prefix="$CSSPropertyName" value="[string]"} Shortcut tag which automatically prefixes the provided CSS property with vendor prefixes. Can be used in CSS files. Parameters $CSSPropertyName - The property name to prefix. The supported properties are: transition, transform, animation, animation-name, animation-duration, animation-fill-mode, animation-timing-function, user-select, box-sizing, background-size. value - the value of the CSS property. {request="$requestParameter" raw="[boolean]"} Inserts the value of a request parameter. Paramaters $requestParameter - The parameter from the request object to be inserted. raw - By default, the returned value is HTML-escaped. If this parameter is true, the output won't be HTML-escaped. Be careful! {resource="$path" app="[string]" location="[string]" noprotocol="[boolean]"} Returns the absolute URL to the specified resource. Can be used in CSS files. Parameters $path - Relative path to the required resource (path is relative to the current theme's /resource directory) app - The app to which the resource belongs. location - The location (front/admin/global) noprotocol - Whether to make the resulting URL protocol-less (i.e. do not include http:// or https:// at the beginning, which can be useful for resources which are not allowed to be loaded over http on an https connection) {setting="$settingKey" escape="[boolean]"} Inserts the value of a system setting. Can be used in CSS files. Parameters $settingKey - Key of the system setting to insert. escape - By default, the raw value is output. If you need the value to be HTML-escaped, pass true for this parameter. {url="$url" csrf="[bool]" base="[string]" seoTemplate="[string]" seoTitle="[string]" seoTitles="[array]" protocol="[\IPS\Http\Url::PROTOCOL_AUTOMATIC|\IPS\Http\Url::PROTOCOL_HTTPS|\IPS\Http\Url::PROTOCOL_HTTP|\IPS\Http\Url::PROTOCOL_RELATIVE]" fragment="[string]" ref="[string]" plain="[bool]" ips="[string]" noprotocol="[bool]"} Generates an \IPS\Http\Url instance of a URL. Can be used in CSS files. Parameters csrf - Adds the CSRF Key to the query string base - The base to use, if this is an internal URL. seoTemplate - The SEO template for this URL to construct a friendly URL. seoTitle - The title to use for the friendly URL. seoTitles - An array of friendly URL titles. Not used if seoTitle is used. protocol - One of the \IPS\Http\Url::PROTOCOL_* constants to define the protocol to use. fragment - Adds a fragment to the end of the URL. ref - Sets a base64 encoded referring URL as a query string to the URL (used in conjunction with \IPS\Request::i()->referrer()). plain - To output the string value of the URL raw. If omitted, the string value is run through htmlspecialchars(). ips - If this is an internal IPS URL to the documentation. Ignores all other parameters. noprotocol - Makes the URL protocol relative regardless of the defined protocol. This is deprecated, and \IPS\Http\Url::PROTOCOL_RELATIVE should be used instead.

It is possible to use arbitrary PHP in your templates. Generally this is discouraged, but in some situations a simple statement can be of benefit to initialize a variable or aid debugging (for example). Note: templates also support a special expression template tag; consider using this tag in favor of arbitrary PHP. We cover the tag in a later step of this guide. To use PHP, you can enclose your statement in double-curly parenthesis, like so: {{$myVar = 0;}} Be sure to include the semi-colon so that your statement is valid. This syntax allows for one-line statements. If you have a larger block, each line must contain its own double-curly parenthesis. Note: templates use output buffering; attempting to echo, print_r or similar in the middle of a template is likely to cause errors. If you need to do this, we recommend following the statement with an {{exit;}} so that script execution ends immediately.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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