Themes and Customizations

Subcategories

  1. Getting Started with Themes

    Themes are normally the first port of call when customizing your community. This guide will help you get started.
    7
    guides
  2. Advanced Theming

    If you are a designer/developer looking to build custom themes, find out about the advanced tools we offer.
    8
    guides
  3. Languages and Localization

    The IPS Community Suite fully supports localization for users around the world. Discover how to use the language tools.
    10
    guides
  4. Editor and Emoticons

    Discover how to customize IPS4's powerful rich text editor and how to manage your emoticons.
    6
    guides
  5. Tips & Tricks

    Learn some useful tips & tricks for working with the IPS4 template engine beyond the basic changes you can make.
    6
    guides
  6. Template syntax

    HTML logic is our syntax for allowing more complex handling of HTML in templates. This guide covers the available features.
    7
    guides
  7. Javascript Framework

    Developer documentation covering how to use and create code from IPS4's Javascript framework.
    35
    guides
  8. CSS Framework

    Developer documentation covering how to use the CSS classes available in the IPS Community Suite.
    13
    guides
    • No guides here yet
  1. Upgrading themes to 4.2

    As far as possible, we have tried to ensure compatibility between themes for Invision Community 4.1 and 4.2. However, given the refreshed default theme and many new features, there are places where you may have to manually update your theme to be compatible. How to update theme template bits The most fool-proof way to update a template bit for compatibility is to simply revert it to the default (when viewing the individual template bit in the editor, click the 'Revert' button). This will remove any customizations and should solve issues caused by the template being out of date. Of course, this is invasive because it means having to reapply customizations to that template bit. Alternatively, you can manually fix templates that are causing errors. This isn't quite as foolproof, because it first means identifying what is causing the error, and ensuring you fully resolve the issue. However, it does mean you don't lose customizations to that template bit. Scope of this guide In this guide, we will outline some of the areas you should check and update to ensure compatibility. It is not exhaustive - depending on how modified your theme is, there may be customizations not accounted for here or other unforeseen compatibility issues that you will need to resolve. In addition, some changes noted below may not apply if your theme's customizations already changed the area in question. In addition, this guide doesn't account for updating your templates for new features; its aim is simply to try and help you prevent fatal errors and visual problems after upgrading. We still recommend performing a diff on any of your customized template bits to identify which changes, if any, you should manually apply. However, we hope listing these key areas will go some way to minimizing the impact of the upgrade.   Primary navigation structure change The HTML structure of the primary navigation bar has changed slightly in 4.2 in order to allow it be full-width across the page. The <nav> tag no longer contains the ipsLayout_container class. Instead, the inner ipsNavBar_primary element has this class. This means the template goes from (4.1.19): {{if !in_array('ipsLayout_minimal', \IPS\Output::i()->bodyClasses )}} <nav class='ipsLayout_container' data-controller='core.front.core.navBar'> <div class='ipsNavBar_primary {{if !count( \IPS\core\FrontNavigation::i()->subBars( $preview ) )}}ipsNavBar_noSubBars{{endif}} ipsClearfix'> To (4.2): {{if !in_array('ipsLayout_minimal', \IPS\Output::i()->bodyClasses )}} <nav data-controller='core.front.core.navBar' class='{{if !count( \IPS\core\FrontNavigation::i()->subBars( $preview ) )}}ipsNavBar_noSubBars{{endif}}'> <div class='ipsLayout_container ipsNavBar_primary {{if !count( \IPS\core\FrontNavigation::i()->subBars( $preview ) )}}ipsNavBar_noSubBars{{endif}} ipsClearfix'> With matching closing tags, of course. The primary nav bar also has a negative top value in 4.2, to facilitate the new positioning. However, on existing custom themes this may result in the nav bar being placed higher than it should, potentially overlapping the header. If your theme shows this problem, you can reset the top positioning to fix it: .ipsNavBar_primary { top: 0; } Finally, the default theme now sets a background on #ipsLayout_header nav (using the main_nav_tab theme setting). On custom themes this may result in an unintended block of color showing behind your nav bar. You can remove this by adding this CSS: #ipsLayout_header nav { background: transparent; }   No content background color by default The default 4.2 theme has removed a background color on the #ipsLayout_contentWrapper element. If your custom theme used a colored page background and relied on the contentWrapper background to set the content, you can add the background color back by adding a style to your custom.css file: #ipsLayout_contentWrapper { background-color: #ffffff; }   No margin on #ipsLayout_mainArea, sidebar or breadcrumbs by default If you experience the above issue with #ipsLayout_contentWrapper, its likely you'll also experience this issue. The 4.2 default theme no longer has spacing on the #ipsLayout_mainArea and sidebar elements, or the breadcrumbs. If you apply a background color to #ipsLayout_contentWrapper, you'll likely see the content touching the sides of your background area. You can fix this by adding back spacing like so: #ipsLayout_mainArea { padding: 0 20px; } .ipsBreadcrumb { margin-left: 20px; margin-right: 20px; } #ipsLayout_sidebar { padding-left: 0; padding-right: 0; } html[dir="ltr"] #ipsLayout_sidebar.ipsLayout_sidebarleft, html[dir="rtl"] #ipsLayout_sidebar.ipsLayout_sidebarright { padding-left: 20px; } html[dir="ltr"] #ipsLayout_sidebar.ipsLayout_sidebarright, html[dir="rtl"] #ipsLayout_sidebar.ipsLayout_sidebarleft { padding-right: 20px; }   No background color behind primary navigation by default Due to the new styling of the header and navigation in 4.2, the primary navigation bar no longer uses the background color defined by the theme settings (instead, it's transparent and the header color surrounds the nav). If your theme design relies on this background color, you can add it back using some custom CSS: .ipsNavBar_primary { background: {theme="main_nav"}; padding: 5px 5px 40px 5px; }   Unnecessary titlebars now hidden by default In an effort to hide extraneous design elements from the page, 4.2 hides many of the titlebars (sometimes known as 'maintitle') that appear above tables/sections. In nearly all cases, we have left the markup for these titlebars in the theme, enabling you to show them again if you wish. This may be useful if you particularly rely on these elements to achieve your design. .ipsApp .ipsType_sectionTitle.ipsHide { display: block; }   Changed parameter when breadcrumb template called We will cover changed template parameters in the next section, but I particularly want to highlight a changed parameter in the breadcrumb template, primarily because it's called from within globalTemplate which is the most often customized bit. Previously, the first parameter of the breadcrumb template was a boolean (true or false) value. This is no longer the case and the first parameter has been removed, so you'll need to update the calls to the breadcrumb template in your globalTemplate HTML. It goes from: {template="breadcrumb" app="core" group="global" params="FALSE, 'top'"} to: {template="breadcrumb" app="core" group="global" params="'top'"} The same applies for the second call to breadcrumb in this template, which renders the bottom breadcrumb - simply remove the first parameter.   Change to Contact Us logic that may impact footers If your theme has customized the footer template, you will likely get an Internal Server Error on every page of your community due to a call to a method that no longer exists. This call wraps the Contact Us link and checks that the user permission. You'll need to update: {{if \IPS\core\modules\front\contact\contact::canUseContactUs() and !( \IPS\Dispatcher::i()->application->directory == 'core' and \IPS\Dispatcher::i()->module and \IPS\Dispatcher::i()->module->key == 'contact' )}} to be: {{if \IPS\Member::loggedIn()->canUseContactUs() and !( \IPS\Dispatcher::i()->application->directory == 'core' and \IPS\Dispatcher::i()->module and \IPS\Dispatcher::i()->module->key == 'contact' )}} Note the new canUseContactUs method.   Changed template parameter signatures Some templates have new or changed parameters passed into them from the PHP framework. Check the list below - if you have modified any of the listed template bits, you may have to manually adjust the parameters the template expects otherwise fatal errors may occur. You can do this by editing the template bit in the theme editor, and clicking the "Variables..." button on the toolbar. You'll probably need to update the template contents too, to use the new variable. Core > Global > Forms > address Core > Front > Forms > editContentForm Core > Global > Forms > editorAttachmentsPlaceholder Core > Global > Forms > node Core > Global > Forms > nodeCascade Core > Front > Global > breadcrumb Core > Global > Global > pollForm Core > Front > Global > reputationMini Core > Global > Login > mfaRecovery Core > Front > System > searchResult Core > Front > System > settingsOverview Core > Front > System > settingsProfileSync Forums > Front > Forums > forumPasswordPopup Forums > Front > Index > indexButtons Blog > Front > Submit > submit Calendar > Front > Submit > submitPage Calendar > Front > View > view Gallery > Front > Browse > album Gallery > Front > Global > embedAlbums Nexus > Front > Global > embedProduct Nexus > Admin > Support > request   Reputation has added reactions Invision Community 4.2 introduces Reactions as an upgrade to the existing reputation system. As a result, there are template additions and a method deprecation that affect themes. This change will impact any template bit that calls the $content->reputation() method, including: Forums > Front > Topics > postContainer Forums > Front > Topics > post Blog > Front > Widgets > blogCommentFeed Pages > Display > Database > comment Pages > Display > Database > commentContainer Core > Front > Global > comment Core > Front > Global > commentContainer Core > Front > Statuses > statusReply Downloads > Front > Widgets > downloadsCommentFeed These template bits will need to be updated to correctly check/display reactions on content using the new method. We have added backwards compatibility for the reputation() method where possible, to prevent errors. However, the old reputation() method is deprecated and will be removed in a future update, so you should update any customized template bits that calls reputation() at your earliest convenience. In addition to this new method, the way in which templates check whether reputation/reactions are supported has changed, since reactions use PHP traits. Instead of something like this: {{if $comment instanceof \IPS\Content\Reputation and settings.reputation_enabled}} {template="reputation" group="global" app="core" params="$comment, 'ipsPos_right ipsResponsive_noFloat'"} {{endif}} The code now looks like this: {{if \IPS\IPS::classUsesTrait( $comment, 'IPS\Content\Reactable' ) and settings.reputation_enabled}} {template="reputation" group="global" app="core" params="$comment"} {{endif}} If you determine that one of your customized comment/post template bits requires updating for reactions, we recommend using the diff tool to compare the differences to correctly apply the new code.   New theme settings 4.2 introduces a number of new theme settings. While these shouldn't have a significant impact on existing custom themes, you may find that certain colors don't look as they used to because they're being controlled by a new theme setting. You may wish to review the colors set by these settings and adjust to suit. tag (tag background color) prefix (prefix background color) widget_title_font (text color of widget title bar) comment_count (background color of comment count bubble sometimes shown alongside content) comment_count_font (text color of above) featured (color used to identify featured/popular content) pagination_active (background color of 'active' page in pagination control) link_button (border and text color of link buttons)   Forums 'grid view' is no longer a theme setting In 4.1 and below, the 'grid view' option for Forums was a theme setting. In 4.2 it is now a system setting and ties in with the new fluid view. If you check for grid view in your template bits, you should update the check. Instead of: {{if theme.forum_layout === 'grid'}} //.... Do: {{if \IPS\forums\Forum::getMemberView() === 'grid'}} //...   AdminCP less compatible with customizable themes We are moving away from the concept of allowing the AdminCP to be themeable in the same way the front-end is. While in 4.2 the AdminCP still loads a theme in the same was as it does in 4.1, and so could be customized, many aspects of the AdminCP theme are now hardcoded in its own CSS files and won't honor theme settings. In future versions, we expect to move the AdminCP away from using a customizable theme and instead all sites will use the same, default AdminCP theme.
Sign in to follow this