Customizing the front end viewer

Contents

1. Creating a new front-end viewer theme
2. Integrating the front-end viewer into your own theme
3. Structure of theme elements
4. The front-end viewer data model
5. Files that may be of interest

Creating a new front-end viewer theme

A front-end viewer theme describes the trip summary front-end viewer's layout and styling. There are a couple of elements that form a theme:

• the top teaser element (a small hint that's displayed on top of the post to notify the user that there's also some technical - so-to-speak - information related to the trip being described in the post);
• the viewer itself, that's either inserted at the end of the post or at a specific location using a shortcode or a block;
• the CSS styles that's applied to the above-mentioned elements;
• the JavaScript files required to add interactivity, but that's not customizable at this moment.

The customizable theme elements are formalized in an interface, Abp01_FrontendTheme (look it up over here), that defines the following methods:

• function includeFrontendViewerStyles() - Enqueue styles to be used with the front-end viewer;
• function registerFrontendViewerHelpers() - Include the front-end viewer view helpers if needed (see below);
• function renderTeaser(stdClass $data) - Renders the trip summary front-end top teaser;
• function renderViewer(stdClass $data) - Renders the trip summary front-end viewer;
• function getVersion() - Returns the current theme version.

WP-Trip-Summary comes, out of the box, with two implementations of this interface, which you may want to look-up and use as examples:

• Abp01_FrontendTheme_Default, which represents the core theme shipped with the plug-in;
• Abp01_FrontendTheme_Decorator, which builds upon Abp01_FrontendTheme_Default and looks for overrides within the currently active blog theme (see below); if none are found, it reverts to the core elements.

Customizing the stylesheet only

At a bare minimum, you need to provide a custom stylesheet and, truth be told, most of the times that's probably the only thing you'd want.
To achieve this, you need not implement the whole thing, but merely extend one of the above-mentioned classes, depending on whether you would like to allow overrides from the currently active blog theme or not.
Please see the original stylesheet, as well as the structure of the viewer elements described below for additional information.
Example:

class My_Sexy_Theme extends extends Abp01_FrontendTheme_Default {
    public function __construct(Abp01_Env $env) {//required
        parent::__construct($env);
    }

    public function registerFrontendViewerHelpers() {
        //include your own view helpers (see below), if needed, before the following line;
        //if there is no need to overwrite view helpers, skip overriding this method.
        parent::registerFrontendViewerHelpers();
    }

    public function includeFrontendViewerStyles() {
        //Call parent's method if you'd like to keep
        //the original stylesheet and only customize some of the elements
        //If not, you may remove this line
        parent::includeFrontendViewerStyles();
        wp_enqueue_style(/* ... whatever ... */);
    }

    public function getVersion() {
        //not strictly required when extending Abp01_FrontendTheme_Default 
        //but recommended, since, otherwise,
        //Abp01_FrontendTheme_Default's version will be returned.
        return '0.1.0';
    }
}

Customizing the HTML structure

If you would like to customize the HTML structure of some - but not all - of the elements, you may, of course, override additional methods (such as renderTeaser(), for example), but, if the entire core structure must be done await with, just implement the interface directly.
To this end, here are a couple of guidelines:

• While it's possible to change the way the elements are laid out, those elements must exist and have the same ids and classes;
• Tab navigation is implemented using jQuery.EasyTabs, which has its own markup requirements;
• WP-Trip-Summary will pass an instance of Abp01_Env to your theme, so the constructor signature must be public function __construct(Abp01_Env $env);
• Abp01_Env provides you with access to information related to the current WP and plug-in execution environment, such as:
  • function getViewFilePath($viewFile) - gets the path to a specified core WP-Trip-Summary view file;
  • function getViewHelpersFilePath($helperFile) - gets the path to a specified core WP-Trip-Summary view file;
  • function getViewsDir() - gets the root WP-Trip-Summary core views directory;
  • function getAjaxBaseUrl() - URL to admin-ajax.php.

Customizing the view helpers

View helpers are functions used when generating the HTML output.
Currently, there are three view helper functions (check out the entire file over here):

• function abp01_extract_value_from_frontend_data($data, $field) - Extracts a field value from the info data store ($data->info);
• function abp01_format_info_item_value($value, $suffix) - Format the given value, also adding a suffix if not empty.
• function abp01_display_info_item($data, $field, $fieldLabel, $suffix = '') - Render a track information item, given the main data store, the field, the label and an optional suffix (used over here).

Most of the times you will only need to overwrite abp01_display_info_item, especially if you're going to change the entire HTML structure of the front-end viewer.

To overwrite only some of the core view helpers, either inherit from Abp01_FrontendTheme_Default (or Abp01_FrontendTheme_Decorator) as described above or, in case of directly implementing the Abp01_FrontendTheme interface, use Abp01_Env::getViewHelpersFilePath($helpersFilePath) to obtain the path to the core view helpers file and include it:

public function registerFrontendViewerHelpers() {
    //include your own view helpers file before the following line.
    require_once $this->_env->getViewHelpersFilePath('controls.frontend.php');
}

Putting it all together

Besides defining your theme as described above, you need to tell WP-Trip-Summary how to use it.
To achieve this, put all your stuff together in a WP plug-in and bind to the abp01_get_frotend_theme_class hook (which is called during the execution of WP's init action hook) and return the name of your theme class. For instance, you might do this on plugins_loaded:

function my_sexy_plugin_loaded() {
    add_filter('abp01_get_frotend_theme_class', function($currentThemeClass) {
        return 'My_Sexy_Theme';
    });
}

add_action('plugins_loaded', 'my_sexy_plugin_loaded');

Integrating the front-end viewer into your own theme

For theme developers, though, or for anyone that handles his/her own theme, there is a shortcut to all of the nonsense I just described. If you remember, I said something about a class Abp01_FrontendTheme_Decorator, which looks for overrides within the currently active blog theme. If no overrides are found, it reverts to the core elements.
As it turns out, this is the default theme that comes with WP Trip Summary, which means you need only abide by a certain file structure within your theme and you can get a custom front-end viewer with much less hassle:

1. Create a new directory structure in your theme's root: abp01-viewer, abp01-viewer/media/css and abp01-viewer/helpers;
2. In that directory, create all the files you want to override (see table below for names);
3. The data model is accessible via $data variable.

File	Location
Front-end top teaser template	abp01-viewer/wpts-frontend-teaser.php
Front-end viewer template	abp01-viewer/wpts-frontend.php
Front-end viewer CSS file	abp01-viewer/media/css/abp01-frontend-main.css
Front-end viewer helper functions	abp01-viewer/helpers/controls.frontend.php

Structure of theme elements

Front-end top teaser structure

The structure of the front-end top teaser is depicted in the image below. Click here for an enlarged version.

A couple of notes:

• Each element is shown with ids ID, CSS class and default inline style, if present.

Front-end viewer structure

The overall structure of the WP-Trip-Summary front-end viewer is depicted in the image below. Click here for an enlarged version.

A couple of notes:

• Each element is shown with ids ID, CSS class and default inline style, if present;
• If no content is available for a given tab (either track information or map), then that tab is not show;
• If only one tab is shown, then that tab also has the CSS class .abp01-full-tab;
• Each of the content containers (#abp01-techbox-info, #abp01-techbox-map) is only shown when its corresponding tab is selected.

The track information container

The structure of the track information container (#abpp01-techbox-info) is depicted in the image below. Click here for an enlarged version.

A couple of notes:

• Each element is shown with ids ID, CSS class and default inline style, if present;
• Odd list elements are decorated with the abp01-item-odd CSS class;
• Even list elements are decorated with the abp01-item-even CSS class.

The map container

The structure of the map container (#abpp01-techbox-map) is depicted in the image below. Click here for an enlarged version.

A couple of notes:

• Each element is shown with ids ID, CSS class and default inline style, if present;
• The actual map is loaded and rendered inside #abp01-map;
• If the map fails to load, then a retry interface is displayed (#abp01-map-retry-container), with an error message (#abp01-map-retry-message) and a retry button (#abp01-map-retry);
• The #abp01-altitude-profile-container element is only present if altitude profile is enabled in plug-in settings and is used to host the altitude profile chart, when the user requests it to be shown using the corresponding map control.

The front-end viewer data model

When rendering front-end viewer templates, WP-Trip-Summary provides the required data using a plain stdClass object, usually available through the $data variable. The structure of this object is described below.

Commonly used types

These are types that describe multiple properties in the front-end viewer data model.

Lookup data item descriptor

This is a plain stdClass object used to describe a value assigned from a pool of lookup data items. For instance, what type of bike it's recommended for a given trip. This is herein referred to as LookupDataItem.

Property	Type	Description
id	int	ID of the lookup data item assignment
type	string	Type of lookup data item assignment
label	string	The displayable label of the lookup data item. This is either the translated label (if translation is available for the current language) or the default label defined for the item.
hasTranslation	boolean	Whether or not a translation is available for the current language.

Structure of the data model itself

Property	Type	Description
info	stdClass	Contains track information data
info->exists	boolean	Whether or not track information is available
info->isBikingTour	boolean	Whether or not track information is for a biking trip
info->isHikingTour	boolean	Whether or not track information is for a hiking trip
info->isTrainRideTour	boolean	Whether or not track information is for a train ride trip
Fields available for biking trips		You may consult the field definitions over here
info->bikeDistance	float	Total distance
info->bikeTotalClimb	float	Total climb/total altitude gain
info->bikeDifficultyLevel	LookupDataItem	The difficulty level of the trip
info->bikeAccess	string	Access information towards the start point and from the end point
info->bikeRecommendedSeasons	LookupDataItem[]	The recommended seasons for the trip
info->bikePathSurfaceType	LookupDataItem[]	The path surface types encountered along the way
info->bikeBikeType	LookupDataItem[]	What bike types are recommended for the trip
Fields available for hiking trips		You may consult the field definitions over here
info->hikingDistance	float	Total distance
info->hikingTotalClimb	float	Total climb/total altitude gain
info->hikingDifficultyLevel	LookupDataItem	The difficulty level of the trip
info->hikingAccess	string	Access information towards the start point and from the end point
info->hikingRecommendedSeasons	LookupDataItem[]	The recommended seasons for the trip
info->hikingSurfaceType	LookupDataItem[]	The path surface types encountered along the way
info->hikingRouteMarkers	string	Description of what official trail markers to follow
Fields available for train ride trips		You may consult the field definitions over here
info->trainRideDistance	float	Total distance
info->trainRideChangeNumber	int	How many trains were changed (how many connections)
info->trainRideGauge	float	Railroad line gauge
info->trainRideOperator	LookupDataItem[]	What companies operated the used trains
info->trainRideLineStatus	LookupDataItem[]	Statuses for various sections of the line
info->trainRideElectrificationStatus	LookupDataItem[]	Electrification statuses for various sections of the line
info->trainRideLineType	LookupDataItem[]	Types (simple or double railway line) for various sections of the line
track	stdClass	Contains GPX track-related data
track->exists	boolean	Whether or not a GPS track has been uploaded
postId	int	The post ID to which the data set belongs
ajaxUrl	string	Absolut URL to admin-ajax.php
ajaxGetTrackAction	string	Action name to be used with admin-ajax.php in order to retrieve detailed GPS track data
downloadTrackAction	string	Action name to be used with admin-ajax.php in order to download the GPS track file
nonceGet	string	Nonce value to be used with admin-ajax.php in order to retrieve detailed GPS track data
nonceDownload	string	Nonce value to be used with admin-ajax.php in order to download the GPS track file
imgBaseUrl	string	URL to the plug-ins image folder
settings	stdClass	Contains a snapshot of all the plug-in settings

Files that may be of interest

File	Link
Front-end top teaser template	Click here
Front-end viewer template	Click here
Front-end viewer CSS file	Click here
Front-end viewer helper functions	Click here
Front-end viewer JavaScript file	Click here