Jump to content

Guides

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.

Edited by Rikki

  Report Guide


×