Advanced theming techniques
This section covers the advanced theming techniques such as simulating AJAX calls and explaining wireframes for enterprise-grade templates.
Simulating AJAX calls
In Styleguide you can simulate AJAX calls so that you can test your client-side JavaScript that processes the server's responses. The underlying concept in Styleguide's implementation of AJAX is that you use a template to submit data in an AJAX session, and you populate another template with the server's response.
The following example shows how to create a form for visitor comments, send the comment to the server, and then display the comment in the original web page.
Step 1: Create directory structure
All the files for your AJAX simulation are under the directory styleguide/
, preferably in their own subdirectory. Create the subdirectory in which you'll create the Styleguide files, such as reader-comments/
.
theme-directory/ or express/ └── styleguide/ ├── All.js └── reader-comments/ ├── ReaderResponse.hbs ├── ReaderResponse.json ├── ReaderSubmit.hbs ├── ReaderSubmit.js └── ReaderSubmit.json
Referring to the previous illustration, the five files in the directory reader-comments/
are the minimum you need to simulate an AJAX session in Styleguide. You'll create those files in the following steps.
Step 2: Create a template with a form
Simple AJAX deployments start with an HTML form. In the subdirectory you created for AJAX files (see illustration AJAX directory structure), create the template for the form used to submit a reader comment and display the AJAX response.
At run time, the reader submission form looks as follows.

Step 3: Create a data file for the form template
{ "_template": "ReaderSubmit.hbs", 1 "method": "post", "formActionUrl": "ReaderResponse.html", 2 "body": "body", "submit": "Submit", "comments": "Comment appears here." }
Step 4: Create template for response
You need to create a template that contains the server's response to the AJAX input.
Step 5: Create data file for response template
Create a data file for the template you created in Step 4.
{ "_template": "ReaderResponse.hbs", 1 "_hidden": true, 2 "_wrapper": false, 3 "body": "Roses are read, violets are blue, most poems rhyme, but this one doesn't." 4 }
Associates this data file with the template you created in Step 4 | |
Prevents the response template from appearing in the Styleguide UI—a typical practice for nested templates. | |
Indicates the returned template is not wrapped in any higher level templates—a typical practice for nested templates. For details about this key, see _wrapper. | |
Populates the response with static text. |
Step 6: Create a JavaScript plugin file
Create a JavaScript file as a class that processes the event callbacks you want to capture as well as the response received from the server.
const COMMENTING_SELECTOR = '.ReaderSubmit' 1 const COMMENTING_COMMENTS_SELECTOR = COMMENTING_SELECTOR + '-comments' const FormData = window.FormData export default class ReaderSubmit { 2 constructor (element) { 3 this.element = element this.bindEvents() } bindEvents () { 4 this.element.addEventListener('submit', (event) => this.onFormSubmit(event)) } onFormSubmit (event) { 5 event.preventDefault() const form = event.target const formData = new FormData(form) window.fetch(form.getAttribute('action'), { 6 method: 'POST', body: formData }).then((response) => { if (response.status !== 200) { throw new Error(response.statusText) } return response.text() }).then((returnedComment) => { 7 document.querySelector(COMMENTING_COMMENTS_SELECTOR).innerHTML = returnedComment } ).catch((error) => { console.log(error) }) } }
Declares constant strings used in functions that access the DOM through class names, such as | |
Declares a class using the statement | |
Class's constructor. The constructor calls the function to bind events to the template's controls. | |
Binds the event | |
Describes the callback | |
Sends the form data to the server and receive the subsequent response. In this example, the response is a static text "Roses are read, violets are blue, most poems rhyme, but this one doesn't." | |
Takes the received response (which is a string) and assign it to the div whose class name is |
Step 7: Register plugin
In the theme's
styleguide/
directory, create or open a fileAll.js
. (See the illustration AJAX directory structure for the location of this file.)Add the following lines:
import plugins from '<path>/core/PluginRegistry.js' 1 import ReaderSubmit from './reader-comments/ReaderSubmit.js' plugins.register(ReaderSubmit, '.ReaderSubmit') 2
Imports the Node.js plugin-registry package. This package comes with Styleguide, so you do not need to install it yourself. | |
Associates the class |
Step 8: Run Styleguide
Build and run your Styleguide project. From the
express/
or theme directory, gulp styleguide.In the browser, click Submit to observe the AJAX interaction.
Referring to the previous illustration, clicking Submit retrieves the text in the data file ReaderResponse.json
that you created in Step 5, and displays it in the div <div class="ReaderSubmit-comments">
.
Getting Started (with AJAX)