Templating plugin

This plugin allows you to easily theme your GuideChimp, replace the default templates with your custom templates.

Installation

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.

Templating engine

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>)

Nested data and arbitrary Javascript ({{title}})

{{...}} 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>

Registration of event handlers (@click="next()")

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) };

Conditional evaluation (if="condition")

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>

Looping (for="(step, index) in steps")

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>

Updates the element’s innerHTML with html attribute (html="{{title}}")

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>

Inserting variables containing DOM Element ({{document.createElement('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>

Template tag (<template>)

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>

Templates

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 templates 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>

Default data

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

Tooltip

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>

Preloader

The preloader appears during the execution of asynchronous events.

Example:

<div class="gc-preloader"></div>

Close

Tour closing template

Example:

<div class="gc-close"
     @click="stop({ event: $event })"></div>

Progressbar

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>

Title

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>

Description

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>

CustomButtons

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

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>

Previous

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>

Next

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>

How to use

The plugin provides special methods to change default templates:

Methods

• setTmpl(templates) - accepts an object of templates to be merged with the default
• setTooltipTmpl(tmpl) - set a template for the tooltip
• setPreloaderTmpl(tmpl) - set a template for the preloader
• setCloseTmpl(tmpl) - set a template for the close
• setProgressbarTmpl(tmpl) - set a template for the progressbar
• setTitleTmpl(tmpl) - set a template for the title
• setDescriptionTmpl(tmpl) - set a template for the description
• setCustomButtonsTmpl(tmpl) - set a template for the custom buttons
• setPaginationTmpl(tmpl) - set a template for the pagination
• setPreviousTmpl(tmpl) - set a template for the previous
• setNextTmpl(tmpl) - set a template for the next

Example:

const guide = GuideChimp(tour);

guide.setTmpl({
   title: '<span class="title">{{ title }}</span>',
   description: '<span class="description">{{ description}}</span>',
});

// It is equal
guide.setTitleTmpl('<span class="title">{{ title }}</span>');
guide.setDescriptionTmpl('<span class="description">{{ description}}</span>');

To set templates globally, use the same methods but only on the GuideChimpobject:

GuideChimp.setTmpl({
   title: '<span class="title">{{ title }}</span>',
   description: '<span class="description">{{ description}}</span>',
});

// It is equal
GuideChimp.setTitleTmpl('<span class="title">{{ title }}</span>');
GuideChimp.setDescriptionTmpl('<span class="description">{{ description}}</span>');