-
-
Notifications
You must be signed in to change notification settings - Fork 4
Customizing the front end viewer
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; -
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 uponAbp01_FrontendTheme_Default
and looks for overrides within the currently active blog theme (see below); if none are found, it reverts to the core elements.
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 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';
}
}
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 bepublic 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 toadmin-ajax.php
.
-
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.
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 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 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.
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.
These are types that describe multiple properties in the front-end viewer data model.
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. |
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 |
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 |