Templating

Templating is the process that allows to completely customize some specific parts of Livestorm.
For instance, templating is used to put HTML content inside a modal, a stream, a chat message.

👍

If you are already familiar with templates and are looking for a framework to quickly design beautiful HTML/CSS templates, checkout our UI kit.

Templates & variables

There are two ways of using templating with Livestorm APIs :

One line templates

For one line template, you can easily declare something like

const something = 'Hello'
Modal.showIframe({
  template: `<p>${something}</p>`
})

This will render the following HTML : <p>Hello</p>

It is a simple way to add custom variables inside a template.

However, HTML templates often need to be long and sometimes include other things such as CSS code, javascript code.

When your template becomes longer than one line you should use the multi-lines template.

Multi-lines template

First, create an html file your-template-name.html, then you'll have to import it using this ES5 syntax :

const template = require('./your-template-name.html').default

This allows you to import the file as a string and use it as a variable to declare as a template.

Variable injections

To inject variables inside a template, you can use the very basic templating syntax built into Livestorm plugin :

Modal.showIframe({ template, variables: { count: 3 }})

<h1>The count is {{ count }}</h1>

Which will obviously display The count is 3.

You can also retrieve the variables within your template using javascript:

<script>
console.log(window.__VARIABLES__)
// => { count: 3 }
</script>

For more granularity, there are options to refine the behavior of a variable in the template. You can decide not to inject or not to replace the variable in the template.

No replacement
Useful if you don't need to replace the occurrences to avoid conflict with an other templating tool.

// The "{{ count }}" occurences won't be replaced

Modal.showIframe({
  ...,
  variables: { 
    count: {
      value: 3,
      replace: false,
    }
  }
})

No injection
Useful to reduce the weight of the template removing unnecessary variables content.

// The "count" variable won't be available in window.__VARIABLES__

Modal.showIframe({
  ...,
  variables: { 
    count: {
      value: 3,
      inject: false,
    }
  }
})

Building your UI with our UI Kit

Since plugin are simply HTML and CSS, you can use any CSS framework or JS framework within any of your templates.

However, in order to maintain visual consistency between plugins, and to ensure that plugins remains light and fast, we strongly recommend you to use our UI Kit as the base of your templates.

This kit will allow you to build plugins branded with Livestorm colors and visuals in a matter of seconds.

Using a JS framework

If you really want to use a JS framework (Vue, React, Svelte...) inside the plugin for different reasons (comfort, productivity, local development...), there are 2 possibilities available to you:

Without bundler

You can add the framework CDN script inside the template and then bootstrap your app and write the code in script tags.

With bundler

If you prefer to work with a bundler tool you already use or directly with your favorite framework CLI, it will require injecting the JS and CSS code from your app bundle into the template of the plugin because the plugin build task bundles all the project into a single file.

To do so, just follow these steps.

Add a folder for your app inside the src one.

Try to choose a unique name since it will be used to import raw files with webpack. Then install your app from the framework CLI then build it. Inside your app you will probably have a dist folder with the bundled JS and CSS files.

Disable the file name hashing option

If the bundler creates file using a hash such as in app.c25e6a26.js, it will make impossible it for you to import the app files, so disable it. You will surely find an option to disable it in the config file of your framework CLI or bundler tool.

Inject the app files into the plugin template

Import the app files and inject them in the template. To do so, you will have to specify to webpack to import the files as raw data. To do so, edit webpack.config.js located at the root of the plugin directory and add a rule to use the raw-loader for the files inside your app.

// In this case, the folder including the app is "external-app"
{ test: /external-app/i, loader: "raw-loader" },

// Here the external-app is rendered inside a Modal

import { Modal } from '@livestorm/plugin'

const mainJS = require('./external-app/dist/js/app.js').default;
const vendorJS = require('./external-app/dist/js/chunk-vendors.js').default;
const mainCSS = require('./external-app/dist/css/app.css').default;

export default function (): void {
  Modal.showIframe({
    size: 'extraLarge',
    template: `
      <!DOCTYPE html>
      <html lang="en">
      <head>
        <meta charset="UTF-8" />
        <link rel="icon" href="/favicon.ico" />
        <meta name="viewport" content="width=device-width, initial-scale=1.0" />
        <title>External App</title>
        <script>
          {{ mainJS }}
        </script>

      </head>
      <body><noscript><strong>We're sorry but hello-world doesn't work properly without JavaScript enabled. Please enable it
                to continue.</strong></noscript>
        <div id="app"></div>
        <script>
          {{ vendorJS }}
        </script>
        <script>
        	{{ mainJS }}
        </script>
        <style type="text/css">
            {{ mainCSS }}
        </style>
    </body>
    </html>
    `,
    variables: {
      mainJS: {
  			value: mainJS,
  			inject: false,
  		},
      vendorJS{
  			value: vendorJS,
  			inject: false,
  		},
      mainCSS: {
  			value: mainCSS,
  			inject: false,
  		},
    }
  })
}

That's all ! Now you can easily develop your app UI using modern tools.
Just publish your plugin ($ livestorm publish) when you think it's ready.
Don't forget you can watch the plugin changes and publish it automatically ($ livestorm watch).

You can find examples of implementation:

• Vue CLI