-
-
Notifications
You must be signed in to change notification settings - Fork 20
Templating plugin
This plugin allows you to easily theme your GuideChimp, replace the default templates with your custom templates.
Please refer to the plugins' installation and configuration Wiki page.
Note: Commercial GuideChimp plugins require a valid customer account with the assigned plan and additional configuration, which will be used to validate the availability of particular GuideChimp functions or plugins for the given customer account.
GuideChimp template engine has a number of features to help applying arbitrary data to your templates:
- Nested data and arbitrary Javascript ({{title}})
- Registration of event handlers (@click="next()")
- Conditional evaluation (if="condition")
- Looping (for="(step, index) in steps")
- Updates the element’s innerHTML with html attribute (html="{{title}}")
- Inserting variables containing DOM Element({{document.createElement('div')}})
- Template tag (
<template>
)
{{...}}
blocks can be in attribute values and in HTML content.When used in an attribute value, the retrieved data is converted to a string before being added to the DOM. When used in element content, {{...}}
blocks can return either strings or return DOM elements, in which case the DOM element will be added to the tree.
Simple use:
<div class="gc-title">{{title}}</div>
Using javascript expressions:
<div class="gc-navigation-next {{ (!nextStep || !showNavigation) ? 'gc-hidden': '' }}"></div>
You can use the @eventName
attribute to listen events and run some function when they’re triggered.
<div class="gc-navigation-next"
@click="next"></div>
The template above is equal to:
const next = ()=>{ console.log('User clicked Next') };
const el = document.createElement('div');
el.classList.add('gc-navigation-next');
el.addEventListener('click', ()=>{
return next();
});
Sometimes you need to pass an event object, it is available in the $event variable:
<div class="gc-navigation-next"
@click="next($event)"></div>
const next = (e)=>{ console.log(e) };
If an element contains an "if" attribute, then its value will be evaluated, and if the result is "false", then the entire element will be removed from the tree. This allows for simple if statements.
<div if="title"
class="gc-title">{{ title }}</div>
You can also use elseif and else:
<div>
<div if="condition1">
...
</div>
<div elseif="condition2">
...
</div>
<div else>
...
</div>
</div>
If an element contains a for attribute, then that element will be repeated in the final document once for each member of the array returned by the attribute value.
<div for="step in steps">
{{ step.title }}
</div>
You can also specify an alias for the index or object key:
<div for="(step, index) in steps"></div>
The html attribute inserts its value into the innerHTML.
const title= '<div>Lorem ipsum</div>'
<div html="{{ title }}"></div>
It will be rendered to:
<div>
<div>Lorem ipsum</div>
</div>
You can insert Dom element and NodeList.
const el = document.createElement('div');
el.classList.add('gc-title');
el.innerHTML = 'Lorem ipsum'
el.addEventListener('click', (e) => {
console.log(e);
});
<!--template-->
<div>{{ el }}</div>
It will be rendered to:
<div>
<div class="gc-title">Lorem ipsum</div>
</div>
Sometimes you need to use if or for attributes, but you don't want to display their html el, in which case you can use the <template>
tag that won't display.
<!--template-->
<div>
<template if="title">
{{ title }}
</template>
<template else>
no title
</template>
</div>
In case title is false, it will be rendered to:
<div>
no title
</div>
The plugin allows you to modify the following templates:
- tooltip - is a container for other templates
- preloader - preloader template that occurs when waiting for asynchronous events
- close - tour closing element template
- progressbar - progressbar template
- title - step title template
- description - step description template
- customButtons - template for displaying custom buttons
- pagination - pagination template
- previous - previous arrow template
- next - next arrow template
Attention: The templateы should only have one root element.
Examples of incorrect template:
<div class="first-element">...</div>
<div class="second-element">...</div>
Examples of correct template:
<div class="root-element">
<div class="first-element">...</div>
<div class="second-element">...</div>
</div>
The following data is passed to each template above except preloader by default:
- previousStep - definition of the previous step or null in case of the first step
- currentStep - definition of the current step
- nextStep - definition of the next step or null in case of the last step
- fromStep - defenition of the step from which the transition to the current step was made or null in case the tour has just started
- toStep - defenition of the step to which the transition, in most cases is equal to currentStep
- previousStepIndex - the index of the previous step in the array of steps
- currentStepIndex - the index of the current step in the array of steps
- nextStepIndex - the index of the next step in the array of steps
- fromStepIndex - the index of the step from which the transition to the current step was made in the array of steps
- toStepIndex - the index of the step to which the transition in the array of steps
- steps - array of steps
- go - method to go to a specific step number
- previous- method to go to the previous step
- next - method to go to the next step
- stop - method to stop the tour
In addition to the default data, the following variables are available in the template:
- progressbar - rendered progressbar template
- title - rendered title template
- description - rendered description template
- close - rendered close template
- customButtons - rendered custom buttons template
- previous - rendered previous template
- pagination - rendered pagination template
- next - rendered next template
- copyright - rendered attribution template
- notification - rendered template for displaying messages appearing in guidechimp
Example:
<div class="gc-tooltip">
<div class="gc-tooltip-tail"></div>
{{ progressbar }}
{{ title }}
{{ description }}
{{ close }}
{{ customButtons }}
<div if="previous || pagination || next"
class="gc-navigation">
{{ previous }}
{{ pagination }}
{{ next }}
</div>
{{ copyright }}
{{ notification }}
</div>
The preloader appears during the execution of asynchronous events.
Example:
<div class="gc-preloader"></div>
Tour closing template
Example:
<div class="gc-close"
@click="stop({ event: $event })"></div>
Template for displaying the progressbar of the tour.
In addition to the default data, the following variables are available in the template:
- showProgressbar - boolean based on whether or not to show navigation
- progressMin - the minimum value of the progress bar
- progressMax - the maximum value of the progress bar
- progress - the current value of the progress bar
Example:
<div if="showProgressbar"
class="gc-progressbar"
role="progressbar"
aria-valuemin="{{ progressMin }}"
aria-valuemax="{{ progressMax }}"
aria-valuenow="{{ progress }}"
style="width:{{ progress }}%;"></div>
Step title display template.
In addition to the default data, the following variables are available in the template:
- title - current step title
<div if="title"
html="{{ title }}"
class="gc-title">
</div>
Step description display template.
In addition to the default data, the following variables are available in the template:
- description - current step description
<div if="description"
html="{{ description }}"
class="gc-description"></div>
Template for displaying custom buttons.
In addition to the default data, the following variables are available in the template:
- showProgressbar- array of buttons
Example:
<div if="buttons.length"
class="gc-custom-buttons">
<template for="button in buttons">
{{ button }}
</template>
</div>
Pagination template.
Example
<div if="showPagination && steps.length > 1"
class="gc-pagination">
<div class="gc-pagination-theme-circles">
<template for="(step, index) in steps">
<div if="index === currentStepIndex"
class="gc-pagination-item gc-pagination-item-current gc-pagination-active"></div>
<div elseif="index === previousStepIndex"
class="gc-pagination-item gc-pagination-item-previous"
@click="previous({ event: $event })"></div>
<div elseif="index === nextStepIndex"
class="gc-pagination-item gc-pagination-item-next"
@click="next({ event: $event })"></div>
<div else
class="gc-pagination-item"
@click="go(index, true, { event: $event })"></div>
</template>
</div>
</div>
Template to go to the previous step.
In addition to the default data, the following variables are available in the template:
- showNavigation - boolean based on whether or not to show navigation
Example:
<div if="previousStep && showNavigation"
class="gc-navigation-prev"
@click="previous({ event: $event })"></div>
Template to go to the next step.
In addition to the default data, the following variables are available in the template:
- showNavigation - boolean based on whether or not to show navigation
Example:
<div if="nextStep && showNavigation"
class="gc-navigation-next"
@click="previous({ event: $event })"></div>