IPS Staff
  • Content count

  • Joined

  • Last visited

About Rikki

  • Rank
    data-type='member title'
  • Birthday 08/17/1983

Contact Methods

IPS Marketplace

  • Resources Contributor Total file submissions: 3

Profile Information

  • Gender Male
  • Location Lynchburg, VA :o
  1. 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.
  2. Variables

    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.  
  3. Loops

    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}}  
  4. 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. 
  5. if/elseif/else logic

    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}}  
  6. 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"}  
  7. Managing emoticons

    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.
  8. 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.
  9. 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; }  
  10. 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
  11. 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.
  12. 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.
  13. 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"] { left: 15px; padding-left: 30px; } /* RTL styles */ html[dir="rtl"] { 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.
  14. Managing resources

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