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.
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:
Updated 11 days ago