This page chapter describes the process of customizing the Planet4 platform. This can be useful to NROs that want their website to have a slightly different UI than the International website or even for specific microsites (handbooks, campaigns, etc). With this process we can change styling through css code, but also parts of the functionality through markup template changes.

  • DISCLAIMER: All the modifications below are not part of the core P4 application. They have not been peer reviewed, and solely responsible for them are the NROs that applied them on their website. If you choose to adopt them, be aware that you are taking that responsibility for your website. The P4 team cannot help if your custom code breaks your site, or if it does not behave as it should.
 

KEY INFO >> Please talk to the P4 Team before doing custom development and theming. If we are ever going to reach the full potential of Greenpeace’s engagement platform it is absolutely essential that we work TOGETHER

Current Structure

All theming and UI elements of Planet4 happen mostly on two places, the master-theme and the child-theme.

The master-theme contains all core functionality and the baseline UI and it should be used as it is on all planet4 deployments. While the child-theme is used to extend that functionality and achieve custom look and feel. For more information on how WordPress child themes work in general one should check the relevant upstream documentation.


Custom theming

In order to differentiate a Planet4 instance from the default the first step is to fork the child-theme and create a new repository that follow a naming scheme similar to planet4-child-theme-<custom_name>. From there we can start modifying css and templates.

CSS

All css changes should happen inside style.css that lies on the root of the child theme and initially is empty. This css code is loaded after the master-theme’s css, so anything put in there will override the corresponding class or element.

Keep in mind though, that in the master-theme many elements and classes are nested (using Sass). For that reason we have to be careful with precedence and take that fact into account when we write our css code for our custom child theme. The more specific and explicit a css declaration is, the bigger precedence it has.

So for instance, if we want to adjust the color of the post tags, adding a css rule similar to this won’t work:

.top-page-tags a {
color: #2980b9;
}

⛒ doesn’t work

Neither will this:

.top-page-tags {
a {
color: #2980b9;
}
}

⛒ doesn’t work

Instead we should do something like this:

.single-post .page-header .top-page-tags a {
color: #2980b9;
}

✓ works


Templates

If we want to override an existing template the first step is to create a new folder named templates inside the root of our custom child theme.

Inside that folder, we create a twig template with the same name it has on the master-theme. The best approach would be to actually copy it from the master-theme so we can have its original code as a base for modifications.

So for instance, If we want to adjust the default page template we have to copy the one from the master-theme that exists at templates/page.twig and at the moment contains this code:

{% extends "base.twig" %}
{% block content %}
<div class="page-template">
{{ post.content|raw }}
</div>
{% endblock %}

Assuming we want to display more metadata to the pages content, we would have to use the same code and do any additions (or deletions) we want.

{% extends "base.twig" %}
{% block content %}
<div class="page-template">
<div>{{ post.author.name }}</div>
{{ post.content|raw }}
</div>
{% endblock %}


Blocks Plugin templates override

A lot of the presentation of planet4 is handled by the shortcake blocks in the planet4-plugin-blocks plugin. Like the master-theme, this plugin uses twig templates for rendering. Those twig templates are located in the directory includes/blocks

You can overide the default block twig templates by including in your child theme a file with the same name in the subdirectory /templates/plugins/planet4-plugin-blocks/includes/


Live examples

Since we already have some production running websites that use their own customized child-theme we can use them as a guide for more advanced and specific tweaks.

Change default font (Greece, Thailand, etc.)

For the needs of the Greek website or the Thai website we needed to change the Lora serif font, that is used in the master-theme, to a Sans option. Noto Sans is the font we use for body copy if a language doesn’t support serif font. In order to avoid overriding every present or future occurrence of the Lora font, instead we used the same font-family name to load the new font. So every class or element that uses Lora will automatically use the new one.

As an example, here is a snippet of code that sets the Greek letterspace for normal font-face:

@font-face {
font-family: 'Lora';
font-style: normal;
font-weight: 400;
src: url(https://fonts.gstatic.com/s/notosans/v7/o-0IIpQlx3QUlC5A4PNr5jRAW_0.woff2) format('woff2');
}

The full code of the Greek website customizations can be seen at the planet4-child-theme-greece repository.


Change navigation bar colour (Nordics, NL, CH, East Asia, etc.)

Many NROs have decided to change their primary navigation toolbar, below a full list and some screenshots:

Transparent white navigation bar – GP Finland P4 site
Full white nav bar – GP NL P4 site
Full green nav bar – GP Hong Kong P4 site


Create a navigation sidebar (Handbook)

For the needs of this awesome Handbook website we needed to add a sidebar and move the navigation links to that. In order to achieve that we created two new templates in the child theme. One for the top navigation bar and one for the sidebar. Following master theme naming scheme, the first one is navigation-bar.twig, where we removed the code that generates the navigation links and left only the logo and the search form. The second one is the sidebar.twig where we added the code for generating the navigation menu and through custom css code we style it to be vertical.

Full code for this example can be found at the planet4-child-theme-handbook repository.


Moving top GPI NRO switcher to the bottom of the page (Lux)

If you need more space in the top bar navigation (for instance you have multilingual site and need a language switcher at the top), you might need to move the GPI NRO selector from the top bar to the bottom of the page like on GPLux website.

To move the selector you need to :


<button
class="country-dropdown-toggle"
data-toggle="open"
data-target="#country-list"
aria-expanded="false"
aria-label="{{ data_nav_bar.country_dropdown_toggle }}"
>
<span class="screen-reader-text">{{ __( 'Selected', 'planet4-master-theme' ) }}:</span> {{ website_navbar_title }}
<span class="screen-reader-text">{{ __( 'Change Country', 'planet4-master-theme' ) }}</span>
</button>
{% include 'countries.twig' %}


<ul class="list-unstyled footer-links-country">
<button
class="country-dropdown-toggle"
data-toggle="open"
data-target="#country-list"
aria-expanded="false"
aria-label="{{ data_nav_bar.country_dropdown_toggle }}"
>
<span class="screen-reader-text">{{ __( 'Selected', 'planet4-master-theme' ) }}:</span> {{ website_navbar_title }}
<span class="screen-reader-text">{{ __( 'Change Country', 'planet4-master-theme' ) }}</span>
</button>
{% include 'countries.twig' %}
</ul>


.footer-links-country .country-dropdown-toggle{
color: #5d646b;
background-color: white;
}


.country-list {
position: absolute;
top: -600px;
height: 600px;
width: 100%;
background: white;
border : 1px solid #73be31;
a {
color: #5d646b;
&:hover {
color: #73be31;
}
}
}

@media (min-width: 992px){
.country-list {
width: 80%;
}
}

NOTE : If you want to change the little arrow which opens the selector, you can rewrite the “after” element with an image from your theme directory :

.country-dropdown-toggle:focus::after,
.country-dropdown-toggle:hover::after {
background-image: url(/wp-content/themes/planet4-child-theme/YOUR-IMAGE.svg);
}


Split css code (Greece, NL)

Since our css code on child themes is located in just one file it can easily start getting difficult to maintain as it grows in size. To avoid that, we can create a new folder and break up our css code to blocks that make sense. Then we can just import them to the main style.css.

@import 'css/variables.css';
@import 'css/navigation.css';
@import 'css/footer.css';

As an example, you can see the planet4-child-theme-greece and planet4-child-theme-netherlands repository.


Using css variables (Handbook, NL)

To make some of the custom css code more maintainable we can use css variable. Especially for the things that re-used in many places inside our code. Our theme colors is a good example for that.

:root {
--black: black;
--white: white;
--light-grey: #f6f4e7;
--blue: #01223D;
--blue-60: #007799;
--blue-40: #03aad6;
--red: #e51538;
}
.nav-search-wrap .form-control {
background-color: var(--blue);
color: var(--white);
}

As an example, you can see the planet4-child-theme-handbook and planet4-child-theme-netherlands repository.


Using underline titles effect (Lux)

GPLux child theme implements a short css section to underline titles with a green gradient line. We had an unexpected good feedback on this effect thus we share the code here :

.page-header-title{
width: auto;
background-image: linear-gradient(10deg, #73be31 0%, rgba(115,190,49,0.3) 100%);
background-repeat: repeat-x;
display: inline;
padding: 0 10px 20px 0px;
background-position: 0 0.8em;
background-size: 10px 9px;
}

If you don’t use postcss prefix you can use this code :

.page-header-title{
width: auto;
background-image: -webkit-linear-gradient(80deg, #73be31 0%, rgba(115,190,49,0.3) 100%);
background-image: -o-linear-gradient(80deg, #73be31 0%, rgba(115,190,49,0.3) 100%);
background-image: linear-gradient(10deg, #73be31 0%, rgba(115,190,49,0.3) 100%);
background-repeat: repeat-x;
display: inline;
padding: 0 10px 20px 0px;
background-position: 0 0.8em;
background-size: 10px 9px;
}


Building a contact form (Lux, NL)

You will find on GP Luxembourg a custom contact form. On this form, changing the input Objet de votre message will open many different use cases for the user (like changing his bank account). An e-mail is sent to the admin on submit.

If you want to reproduce this form you can simply grab the code here :

The front code :
https://github.com/greenpeace/planet4-child-theme-luxembourg/blob/master/templates/contact.twig

and the js code which handle all forms actions, field filtering and event triggered here :
https://github.com/greenpeace/planet4-child-theme-luxembourg/blob/master/src/gplu.js

on server side, the code is in the function.php file between line 28 and 166 :
https://github.com/greenpeace/planet4-child-theme-luxembourg/blob/master/functions.php

and optionally the css :
https://github.com/greenpeace/planet4-child-theme-luxembourg/blob/master/src/contact.scss
(please note scss is compiled with a webpack script to minified scripts and scss in the /dist folder)


Adding scripts (NZ)

Form validation, masking, animation, 3rd party popups.
See GitHub for examples / source code.
https://github.com/greenpeace/planet4-child-theme-newzealand


Links & Resources