The template system

The Customer Area plugin allows you to fully customize the way information gets displayed. You can change that at different levels: from the general layout of all pages, to the way each item in a list gets displayed.

Introduction

To help you find the template you want to modify, each add-on (both commercial and core add-ons) implements his templates in his own templates sub-folder. For example:

  • If you want to change the way the customer files are displayed, you would look into the /customer-area/src/php/core-addons/customer-private-files folder;
  • If you want to change the way the customer account is displayed, you would look into the /customer-area/src/php/core-addons/customer-account folder;
  • If you want to change the way they create new file page is displayed, you would look into the folder /customer-area-collaboration/src/php/customer-new-private-page.

If you have a look at the plugin code, you will notice that all customer pages are each located in their own add-on folder and that folder’s name always begins with customer-.

Developers will enjoy a new setting that will output debug information about which templates are used within a page. When enabling that, some HTML comments will be output within the page source code to tell you which template is used and in which folder it has been found. This setting is available under Settings > WP Customer Area > Frontend and Debug templates.

Overriding the templates

To avoid losing your changes when you update the plugin, you can override those templates by copying them either in /wp-content/ or directly in your theme under /wp-content/themes/THEME_NAME:

  • Create a folder named /customer-area/
  • Create a sub-folder named /templates
  • Locate the template file you want to change (hint: look in the plugin folders, they are all named .template.php)
  • Make your changes and do not forget to save the file
  • You should be able to see the changes immediately online

Templates versioning

You will notice that all our templates start with a required block of code managing the template version and changelog. After you duplicated the template, you’ll need to bump the last digit of its current version.

Eg. if you update from 3.2.0 template, you should version it to 3.2.1 so you’ll get notified later if there are some changes to reflect in that template. Do not update others digit because they are already used by WP Customer Area.

So, the following block of code:

<?php
/** Template version: 3.1.0
*
* -= 3.1.0 =-
* - Add hooks
*
* -= 3.0.0 =-
* - Initial version
*
*/
?>

Should become this:

<?php
/** Template version: 3.1.1
*
* -= 3.1.1 =-
* - My own personal class customization
* - Added new button
*
* -= 3.1.0 =-
* - Add hooks
*
* -= 3.0.0 =-
* - Initial version
*
*/
?>

Templates listing

To see which templates have been overridden, you can visit the Customer Area > Status > Templates page. You will get a lot of information about:

  • which templates are overridden and which ones are original
  • if their version number matches the original template version number (useful to detect if some overridden templates need to be updated after you have updated the plugin)

Tip: if you are using a theme that could be upgraded in the future, we recommend to put your customer area templates in the WordPress content directory /wp-content/customer-area/templates

General structure

All the pages defined in the Customer Area (except the detail pages for single private content) are following the same layout. The template you will need to copy is named customer-page.template.php and can be found in /customer-area/src/php/core-classes/templates/

Individual page parts

If you want to make changes to a particular customer page, you can also override a part of it. Each page may contain 4 areas: a header, a footer, a sidebar and a content area. Of course, not all pages output content in those areas. For example, by default, the customer dashboard does not show a sidebar.

By convention, each page part (header, footer, content and sidebar) corresponds to a template file named after the page slug:

  • myslug-header.template.php for the header
  • myslug content.template.php for content
  • myslug-sidebar.template.php to sidebar (if needed)
  • myslug-footer.template.php for footer

You can find the slug of each page in WP Customer Area > Status > Pages.

Content listing pages

Pages listing content is loaded to display private content. These are templates that you can reuse in your theme:

  • myslug-content-item.template.php represents a content item in the list on the main page of content – for example, in the My Files page
  • myslug-content-item-dashboard.template.php represents a content item in the list of the corresponding section of the dashboard – for example, recent files
  • myslug-content-item-empty.template.php is displayed in the absence of content
  • myslug-content-item-empty-category_archive.template.php is displayed in the absence of content in a category page
  • myslug-content-item-empty-date_archive.template.php is displayed in the absence of content in a page archive by date

You can find the slug of each page in WP Customer Area > Status > Pages.

Single content pages

WP Customer Area will show the details of a private content just after its description (author, owner, date of publication, the download link for a private file, etc.). Again, you can make your changes to the model myslug-single-post-footer.template.php. It will be used to display this information just below the details of the content.

Add-ons

The add-ons also work with that very same template system. Because there are too many of them, it would be useless to list them all here. You should use the developer tools which will allow you to see on each page, directly in the HTML source code, which templates are in use.