Headers, footers and sidebars determine the overall framework of a WordPress page by defining what is to go at its top, bottom and sides. They are called by the template which loads the page. All pages must have a header. In theory, footers are not mandatory but in practice are usually required. For the MGF site, the footer mustbe present as a number of plugins use the footer to insert code of their own. Sidebars are always optional and, despite the name, can appear anywhere on the page. Headers, footers and sidebars are written in PHP but, like templates, can contain HTML, CSS and JavaScript. They are theme dependent and must be placed in the root of the relevant theme’s folder.
Headers
All web pages consist of two sections: head and body (enclosed in <head> and <body> tag pairs, respectively). The whole page is enclosed in an <html> tag pair. The header contains the entire head section. For MGF, it also contains that HTML at the start of the body section which is common to all pages: the logo, the title, the two menus and the translation bar.
In a template, the header is called by the WordPress function get_header(). Most sites (including the MGF one) will only have a single header, in which case its filename is header.php. It is possible to have more than one header to be used in some circumstances. In such cases, the other headers’ filenames will be header-[headername].php and the call in the template will be get-header(‘headername’).
Footers
The footer is the area at the bottom of every page of the site. In a template, the footer is called by the WordPress function get_footer(). Most sites (including the MGF one) will only have a single footer, in which case its filename is footer.php. It is possible to have more than one footer to be used in some circumstances. In such cases, the other footers’ filenames will be footer-[footername].php and the call in the template will be get-footer(‘footername’). For MGF, the single footer consists of: the return links to the top of the page and the home page, the legal mentions and the social media icons.
Sidebars
Sidebars are islands of content that sit on a page in a fixed position decided by the user. Although that position can be affected by changes to the surrounding HTML, the idea is that they should always remain in the same place. Sidebar creation is more complicated than for headers and footers. First, they must be registered via a function in functions.php. The actual sidebar is a PHP file (sidebar-[sidebar-id].php which references that function. For a full description of the sidebar process, see here. In a template, sidebars are called by the WordPress function get_sidebar(‘sidebar-name’).’
MGF uses sidebars to display subsidiary menus along with explanatory text. For example, the sidebar ‘plant-lists’ shows a menu of all plant list pages at the right of any plant list page. All sidebars have the same styling but there are three different widths, depending upon the requirements of the type of page. Content for a sidebar is added from the dashboard: Appearance -> Widgets -> [sidebar-name]. At time of writing, there are ten sidebars:
Name
Sidebar and template file name*
Width (in pixels)
Documentation Member App
documentation-memapp.php
325
Documentation
documentation.php
325
Environmental Gardening
environmental-gardening.php
325
Garden Diaries
sidebar-garden-diaries.php
325
Gardening Articles
gardening-articles.php
325
Garden Visits
garden-visits.php
250
Members Gardens
members-gardens.php
270
Plant Articles
plant-articles.php
325
Plant Lists
plant-lists.php
325
Recommendations
recommendations.php
325
* The template name is preceded by ‘page-‘ and the sidebar name by ‘sidebar-‘. The sidebar id. is the same as the file name, less the php suffix.
Templates used in the MGF site are stored in the wp-content/themes/mgftheme folder and fall into three categories:
WordPress generic templates;
templates formatting the pages of the public site (and also the site documentation);
templates used by the Member App.
The generic templates are part of the standard WordPress installation; all others have been developed in-house. Headers and footers are also templates but these are described separately. In-house developed templates have a filename in the format: page-[templatename].php. They also have a template name which appears in the dropdown list of available templates when a page is created. This template name is defined in the first line of the template file, thus:
<?php /* Template Name: Plant Lists
NOTE: WordPress differentiates between ‘home page’ and ‘front page’. In normal internet usage, ‘home page’ refers to the page which is displayed when a user enters the site URL. WordPress calls this the ‘front page’. In WordPress, ‘home page’ refers to the page which contains the blog posts (not used by MGF). This is because WordPress originated as a blogging platform when the blog posts page would have also been the first page displayed. The front page and home page are defined in the dashboard Settings->Reading.
WordPress generic templates
The generic templates for different types of page are used by WordPress in the event that a template has not been specified or if it cannot be found. There is a hierarchy of templates which WordPress follows to determine which of these generic templates to use. They are recognisable as their filenames do not have a ‘page-‘ prefix. Some of them do not have template names.
Template Name
Filename
Purpose
Not applicable
404.php
Displays a message when a page cannot be found (error 404)
Not applicable
comments.php
Displays comments
Front Page
front-page.php
Special template to display the home page
Not applicable
home.php
Displays the latest posts (WordPress default – not used)*
Not applicable
index.php
Displays the home page in default of any other template
Search Results
search.php
Displays search results*
Single Page
page.php
WordPress default template; same format as Centred Content
Not applicable
single.php
Displays a single post (WordPress default – not used)
All these generic templates have been modified so that they match the overall MGF page sizes. Those marked ‘*’ have additional formatting code
Templates for page formatting
In general, the only difference between these templates is the definition of the sidebar as the characteristics of this is different for each type of page (plant articles, recommendations, etc.).
Template Name
Filename
Purpose
Centred Content
page-centeredcontent.php
Default template: content centred with equal blank space at sides
Documentation
page-documentation.php
Display site documentation pages
Documentation Member App
page-documentation-memapp.php
Display Member App documentation pages
Environmental Gardening
page-environmental-gardening.php
Display environmental gardening pages
Forthcoming Events Header & FAQ
page-events.php
Display Forthcoming Events page
Garden Diaries
page-garden-diaries.php
Display garden diary pages
Gardens to Visit
page-garden-visits.php
Display the Gardens to Visit page
Gardening Articles
page-gardening-articles.php
Display gardening article pages
List Maintenance
page-list-maintenance.php
Display the list maintenance page
Members’ Gardens
page-members-gardens.php
Display the members’ gardens pages
Past Activities Header
page-past-activities.php
Display the Past Activities header page
Plant Articles
page-plant-articles.php
Display plant article pages
Plant Lists
page-plant-lists.php
Display plant list pages
Recommendations
page-recommendations.php
Display the member recommendation pages
Webmailto
page-webmailto.php
Special template for use with email mailto generation
Templates used in the Member App
Templates in the Member App contain the code to process the Member App function concerned. As this is unique for each function, each function will have its own template. Some functions have multiple pages and so will use multiple templates. For details, see the Member App documentation pages.
Template Name
Filename
Purpose
Admin Member Profile for update
page-admin-update-profile.php
Template for administrators to view and update members’s profiles
Broadcast
page-broadcast.php
Template for stage I of the broadcast message form
Broadcast II
page-broadcast2.php
Template for stage II of the broadcast message form
Broadcast IV
page-broadcast4.php
Template for stage IV of the broadcast message form (transmission)
Broadcast Message Detail
page-broadcast-detail.php
Displays the results of a single broadcast message
Broadcast Message Results
page-broadcast-results.php
Displays a list of sent broadcast messages
Changed Member Profile
page-changedprofile.php
Displays a changed member profile
Former Member Profile
page-former-update-profile.php
Displays a former member profile
Historical Statistics
page-statistics-history.php
Displays historical membership statistics
Member Additional Information
page-additional-info.php
Displays the additional information entered by members when they join
Member Cancellation
page-member-cancellation.php
Deletes a member from the active member file
Member Centred Content
page-membercenteredcontent.php
As for Centred Content but with check that user is logged in
Member Change Log
page-changelog.php
Displays the log of changes to member profiles
Member Directory
page-memdir.php
Displays the list of members of the directory
Member Mail
page-membermailto.php
Displays a member’s email details
Member Profile
page-member-update-profile.php
Displays a member profile
Statistics
page-statistics.php
Displays membership statistics
Historical Statistics
page-statistics-history.php
Displays historical membership statistics
Snippet
page-snippet.php
Test bed for code changes
Subscription Payments
page-payments.php
Displays subscription payments
Treasurer
page-treasurer.php
Displays the list of expected subscriptions
View Count
page-viewcount.php
Displays the number of times pages have been viewed
When building a WordPress site, it has to be assigned a theme. This controls the site’s appearance: layout, typography, colour, and other design elements. As a bare minimum, a theme will consist of a stylesheet of standard CSS statements (‘style.css’) to control the appearance of the site and a functions file (‘functions.php’). The latter is a collection of PHP functions and code snippets to perform custom functions not provided by the basic WordPress installation. The theme can also have
additional CSS files;
a collection of special WordPress elements – templates, headers, sidebars and footers (see below);
JavaScript files.
WordPress installations come with a number of default themes and others can be downloaded from the official WordPress theme directory. Many are free; others have paid premium versions. It is also possible to create your own custom themes for a unique website design – which is the case with the MGF site.
Templates
When creating a WordPress page, the user assigns to it a template. This frames the content of the page and, together with the CSS files of the theme, determines its appearance. Templates, which belong to a theme, are executable files which WordPress runs when the page is selected for display. WordPress has a default set of templates but users can create their own and the MGF site makes extensive use of these. Some pages, particularly in the Member App, have a template to themselves; other pages use the same template. For example, all gardening article pages will use the Gardening Articles template thus ensuring that they all have the same general appearance.
Templates are written in PHP but may also contain HTML, CSS and JavaScript. The PHP code is usually a combination of standard PHP statements and special WordPress functions. For example, the WordPress function ‘get_the_title()’ will retrieve the page title*. The primary function of a template is to determine the appearance of the page but it may also contain code carrying out functions specific to the page content. This is particularly so with the Member App where the templates contain the code to carry out the tasks required by the page in question such as updating a member’s profile or sending a message to all members. The templates used in the MGF site fall into three categories:
WordPress generic templates;
templates formatting the pages of the public site (and also the site documentation);
templates used by the Member App.
For more information about how themes and templates are used in the MGF site, click here.
* For a description of all WordPress functions, see the Code Reference.
Pages
Pages, the part of the site that is visible to users, are created by using the WordPress editor (known as ‘Gutenberg’).
All web pages (including WordPress ones) consist of two sections: head and body (enclosed in <head> and <body> tag pairs, respectively) with the whole page enclosed in an <html> tag pair. However, unlike other websites, a WordPress site has no self-standing and permanent HTML files. When a user creates a WordPress page using the editor, WordPress stores the content in a database. Then, when the page is to be displayed, it is constructed dynamically by the WordPress code.
A WordPress page can have four elements:
a header;
the content area;
sidebars (optional);
a footer (also optional).
As their name suggests, headers and footers are blocks of content which precede and follow the principal content on the page. A header for each page is mandatory as it contains the <head> section of the page as well as the initial lines of the <body> section. How much of the body section is included in the header is optional; the MGF header includes the logo, title and the menu bars.
Sidebars are blocks of content within a page. Originally (again as their name suggests) sidebars had to be placed to either the left or right of the principal content but now they can be placed anywhere within the page by using CSS. It is possible to have different versions of the header, sidebar and footer elements for different pages. However, for presentation reasons it is likely that the header and footer elements are will be the same across the whole site (as is the case for MGF). Which of these elements (and which version thereof) is included on any given page is determined by the page template. For a full description of these special WordPress elements and how they are used in the MGF site, see the Headers, Footers, and Sidebars page. Headers, footers and sidebars are part of a theme.
Code
Driving the presentation of pages on the site is the underlying code. The basic code which operates any WordPress site and which is common to all WordPress installations is known as the ‘core’. It is regularly updated and administrators should ensure that the site uses the latest version. Customisation of the code is possible in a number of ways. For more on the code used in a WordPress system, see The System Code.
Brevo is a plugin for mass email marketing. MGF uses it to send emails to the whole or a specific section of the membership and also to individual members. Although the plugin is free, there is a limit of 300 emails per day. The paid versions of the plugin are beyond MGF’s budget which means that only one all-member message can be sent per day (see below for how the Member App handles this). If MGF membership ever exceeds 300 then an alternative solution will need to be found.
Background: Sending emails to a bulk audience has become increasingly difficult in recent years. Certain internet service providers, notably some prominent French ones such as Orange, were regularly rejecting MGF emails as spam and, at one point, there was a risk that MGF would be blacklisted from sending emails at all. The problem also extended to emails sent to individuals by the Member App such as the welcoming message sent to new members or confirmations of subscription payments. Consequently, there was a need for MGF communications to be sent from a source that was trusted. Brevo provides this trusted source.
How it works: In its own space in the Cloud, Brevo maintains a list of people (‘contacts’) to whom its messages should be sent. Messages can be sent to all contacts or to specific subsets. For the latter, lists are set up; a given contact can be a member of more than one list. For example, MGF has a list for English-speaking members and one for French-speaking members. All members are on one or other of these lists which are then used when sending broadcast messages in the appropriate language to all members. These lists are permanent but MGF also uses one-time lists at subscription renewal time. When the subscription renewal procedure is launched at the beginning of each January, those members whose subscription has expired will be placed in a subscription renewal list (again, separate lists for English and French-speaking members) and the renewal notice will be sent to the appropriate members using these lists. The same process is used for the renewal reminders. The lists remain on the Brevo site and can be consulted there to see which members received a given message.
Information held by Brevo: As used by MGF, a Brevo contact record contains three principal items of information: first name, last name and email address. In addition, the database keeps track of which lists each contact belongs to and also whether or not they have been blocklisted (see below). The Member App scripts ensure that the Brevo contact database is kept in sync with the main MGF member database. However, to check that all is satisfactory, open the Subscription Renewal Notices function in the Member App dashboard and select option 1.
Brevo campaigns: A Brevo campaign is where a common message is sent to a set of members (or all of them). Two Member App functions use campaigns:
the broadcast message function to send messages to all members;
the subscription renewal process for sending renewal notices and reminders to the appropriate members.
To send a campaign, you first create the text of the message, indicate to which list(s) the campaign should be sent and then launch the process. Brevo provides statistics on the success of the sending process: how many contacts received the message, how many opened it, and so on. All of these actions can be carried out via the Brevo website but, for MGF, they are integrated into the Member App using Brevo’s API (sse below) so that detailed knowledge of how to operate Brevo is not required. However, the direct Brevo system can be used in extremis if necessary.
Transactional emails: Brevo is also used by the Member App when sending ‘transactional emails‘ to individual members. These are messages which are automatically sent as the result of a specific process. For example, when a person fills out the application form to join MGF, the Member App sends them a welcoming message and also sends a message to the Event Coordinators and the Secretaries to inform them that MGF has a new member.
Member App operationsusing Brevo transactional emails: The following table identifies which Member App operations send one or more Brevo transactional emails.
Operation
Nature of transactional email(s)
New member (via membership form or Membership Secretary action)
Welcome message to new member / notice to administrators
Member personal data change (by member or Membership Secretary)
Notification of change to member / notice to administrators if email address changed
Subscription payment (new member)
Acknowledgement to member / notice to administrators
Subscription renewal payment
Acknowledgement to member
Cancellation notices
List of those removed from membership to administrators
Accessing the Brevo website: From time to time, it may be necessary to go to the Brevo website. To do so, click the Brevo item in the dashboard sidebar and then click ‘Home’. Next click ‘Access to the list of all my contacts’ which will take you to the site. For instructions on how to use the features of the Brevo site, see Using the Brevo Website.
IMPORTANT: UNDER NO CIRCUMSTANCES CLICK THE BUTTON MARKED ‘Sync my users’ AS THIS MAY CAUSE DISCREPANCIES BETWEEN THE MGF MEMBER DATABASE AND THE BREVO CONTACT LISTS.
Mail Senders: Emails sent via Brevo must have a sender defined in the Brevo database (a display name and an email address). For these, use the official MGF mail addresses. For transactional emails and campaigns associated with the subscription renewal process, this will be the Membership Secretary. For other campaigns (broadcast messages), the sender can be any member of the management team who is allowed to send them.
To define a sender in the Brevo database, access the Brevo website as described above and open the drop-down box at top right ‘Mediterr…’. Click ‘Senders, Domains & Dedicated IPs’ and then click ‘Senders’. This will display a list of the existing senders whose name and email address can be modified or deleted by clicking ‘Edit’ or ‘Delete’ as appropriate. To add a new sender, click the ‘Add a sender’ button at top right. Enter the name and address of the new sender and click ‘Save’.
Unsubscribing and blocklisting: GDPR rules that all mass emails include an option for the recipient to unsubscribe from receiving them. Brevo implements this rule and all messages sent via campaigns include this option in the message footer. The actual text to be displayed can be determined by the user and the two Member App functions which use campaigns (Broadcast Message and Subscription Renewal Notices) insert appropriate texts in the code which creates the campaign. If a recipient clicks on the link, Brevo will ‘blocklist’ their contact record in the Brevo database, meaning that they will no longer receive any messages sent via Brevo.
While this concept is correct for conventional mass mailings, it is inappropriate for MGF which only communicates with people who have paid a subscription to receive MGF communications. By clicking the ‘unsubscribe’ link, members would, in essence, be cancelling their membership. To counteract this, a three stage process* has been implemented:
discourage the member from clicking the ‘unsubscribe link’: for broadcast messages, the text of the link has been changed to ‘Cancel my MGF membership’. If the link is clicked, a tab is opened in their browser informing them of the consequences of their action and asking them to confirm it (figure 1 below).
inform the MGF management team of the action: if the member confirms the cancellation, an email with the following text is sent to the Membership Secretary and the Website team: ‘[Member name] has clicked the ‘Cancel my MGF membership’ link at the bottom of a broadcast message. Their email address is: [ member email address]. You should contact them to determine if they really mean to cancel their membership. If so, remove them by opening their profile in the Member App and clicking the ‘Delete this member’ button. If they wish to continue their membership, open their profile and check the ‘Resubscribe blocked member’ box’. In addition to this email, the Member App function ‘View the list of members’ checks for blocklisted members and, if it finds any, will display a message at the top of the list. The names of the members concerned will be highlighted in red.
take corrective action: see text of the email quoted in the previous bullet.
Logs and statistics: Brevo keeps comprehensive information about the messages it sends, both campaigns and transactional emails. For campaigns, the most important statistics can be seen by clicking ‘Broadcast message results‘ in the Member App. To see the rest of the statistics, it is necessary to consult the Brevo web site. For more details on this, see ‘Using the Brevo Website‘.
Bounces: A bounce occurs when an email cannot be delivered. Sometimes, the reason for the non-delivery is temporary: for example, the recipient’s mailbox may be full or their email system may be temporarily unavailable. Usually, Brevo will try to deliver the message again but at a certain moment it will give up. This is called a soft bounce. Soft bounces can also occur if the receiving system thinks that the message is spam. A hard bounce occurs when the message cannot be delivered at all. The usual reason for this is that the email address does not exist (either because of a mistake in the address itself or because the recipient has closed it).
When bounces occur, it is possible to resend the message to just those who did not receive them – see ‘Resending bounced messages‘.
Sending Limit: As mentioned above, MGF is limited to sending no more than 300 emails per day. Emails are sent up to the limit and any excess remains in the Brevo database as a suspended campaign which can only be re-activated via the Brevo website. Consequently, it is advisable to ensure that any mailing will not cause the limit to be exceeded. To do so, before they attempt to send a message, the two Member App functions which use campaigns (see above) call the function ‘check_send’. This is an MGF-developed function which can be found in Section 8 of the functions.php file. It uses the Brevo API to check whether there have been any campaigns sent on the current day. If so, the message ‘Only one broadcast message may be sent per day. Unfortunately, today one has already been sent. Please try again tomorrow’ is displayed and the Member App function is closed.
Using the Brevo API
Communication between the Member App and Brevo is made via the Brevo API, a PHP library which is installed in the public_html/wp-content/library-brevo folder. To use it, it must first be loaded and supplied with MGF’s private validation key. This is performed by the script brevo-header.php. Below is an example of the use of the API.
require($_SERVER['DOCUMENT_ROOT'] . '/wp-content/scripts/brevo-header.php'); // Get the Brevo API
$apiInstance = new SendinBlue\Client\Api\TransactionalEmailsApi(new GuzzleHttp\Client(), $config);
$sendSmtpEmail = new \SendinBlue\Client\Model\SendSmtpEmail();
$sendSmtpEmail['subject'] = 'Blocklisted member';
$sendSmtpEmail['htmlContent'] = 'This member has been blocklisted';
$sendSmtpEmail['sender'] = array('name' => 'MGF Membership Secretary', 'email' => 'membership@mediterraneangardening.fr');
$sendSmtpEmail['to'] = array('name' => 'MGF Membership Secretary', 'email' => 'membership@mediterraneangardening.fr');
try {$result = $apiInstance->sendTransacEmail($sendSmtpEmail);}
catch (Exception $e) {
echo 'Exception when calling TransactionalEmailsApi->sendTransacEmail: ', $e->getMessage(), PHP_EOL;}
Explanation:
‘require…’ : the API is loaded;
$apiInstance… : a new instance of the transactional emails class is created;
the first ‘$sendSmtpEmail…’ statement : a new instance of the SendSmtpEmail array is created;
the remaining ‘$sendSmtpEmail’ statements : the information to be used in the email are used to fill the array;
‘try…’ : the email is sent to Brevo (any return values can be found in $result);
‘catch…’ : what to do if the sending to Brevi failed (not the sending of the email itself).
Information can flow in both directions. The example shown is one where information is sent to Brevo. In others, for example ‘Broadcast message results’, information is retrieved from Brevo and then processed by the Member App.
Full details on how to use the API function described above can be found on the Brevo website. The page concerned has a sidebar where information on all the other functions can be found.
The MGF theme can be found at: public_html/wp-content/themes/mgftheme. It consists of a single CSS file (style.css), a set of templates and a set of sidebars. Details of the templates can be found on the Templates used by the MGF site page. Details of the sidebars are on the Headers, Footers and Sidebars page.
