Creating user interfaces with the HTML service follows many of the same patterns and practices as other types of web development. However, there are some aspects that are unique to the Apps Script environment or are otherwise worth highlighting. Below we'll cover some best practices you should keep in mind when developing your own HTML-service UIs.
To help demonstrate these best practices, we have created a sample web app using the HTML service called Simple Tasks. The full source code and setup instructions are available in our GitHub repository.
Separate HTML, CSS, and JavaScript
Keeping all the HTML, CSS, and JavaScript code in one file can make your project difficult to read and develop. While Apps Script does require client-side code to be placed in .html files, you can still separate your CSS and client-side JavaScript into different files and then include them in the main HTML page with a custom function.
The example below defines a custom server-side include() function in the
Code.gs file to import the Stylesheet.html and JavaScript.html file content
into the Page.html file. When called using
printing scriptlets,
this function imports the specified file content into the current file. Notice
that the included files contain <style> and <script> tags because
they're HTML snippets and not pure .css or .js files.
Code.gs
function doGet(request) {
return HtmlService.createTemplateFromFile('Page')
.evaluate();
}
function include(filename) {
return HtmlService.createHtmlOutputFromFile(filename)
.getContent();
}
Page.html
<!DOCTYPE html>
<html>
<head>
<base target="_top">
<?!= include('Stylesheet'); ?>
</head>
<body>
<h1>Welcome</h1>
<p>Please enjoy this helpful script.</p>
<?!= include('JavaScript'); ?>
</body>
</html>
Stylesheet.html
<style>
p {
color: green;
}
</style>
JavaScript.html
<script>
window.addEventListener('load', function() {
console.log('Page is loaded');
});
</script>
Load data asynchronously, not in templates
Templated HTML can be used to quickly build simple interfaces, but its use should be limited to ensure your UI is responsive. The code in templates is executed once when the page is loaded, and no content is sent to the client until the processing is complete. Having long-running tasks in your scriptlet code can cause your UI to appear slow.
Use scriptlet tags for quick, one-time tasks such as including other content
or setting static values. All other data should be loaded using
google.script.run calls.
Coding in this asynchronous manner is more difficult but allows the UI to load
more quickly and gives it the opportunity to present a spinner or other
loading message to the user.
Don't — load in templates
<p>List of things:</p>
<? var things = getLotsOfThings(); ?>
<ul>
<? for (var i = 0; i < things.length; i++) { ?>
<li><?= things[i] ?></li>
<? } ?>
</ul>
Do — load asynchronously
<p>List of things:</p>
<ul id="things">
<li>Loading...</li>
</ul>
<script
src="//ajax.googleapis.com/ajax/libs/jquery/1.9.1/jquery.min.js">
</script>
<script>
// The code in this function runs when the page is loaded.
$(function() {
google.script.run.withSuccessHandler(showThings)
.getLotsOfThings();
});
function showThings(things) {
var list = $('#things');
list.empty();
for (var i = 0; i < things.length; i++) {
list.append('<li>' + things[i] + '</li>');
}
}
</script>
In the Simple Tasks sample application, the HTML-service page Page.html loads data this way, and only uses templating to include other source code into the page.
Load resources using HTTPS
If your page is served using the newer IFRAME
sandbox mode, including
JavaScript or CSS files not served using HTTPS will result in errors like the
one below.
Mixed Content: The page at 'https://...' was loaded over HTTPS, but requested an insecure script 'http://...'. This request has been blocked; the content must be served over HTTPS.
Most popular libraries support both HTTP and HTTPS, so switching is usually just a matter of inserting an addition 's' into the URL.
Use the HTML5 document type declaration
If your page is served using the newer IFRAME
sandbox mode, make sure
to include the following snippet of code at the top of your HTML file.
<!DOCTYPE html>
This document type declations tells the browser that you designed the page for modern browsers, and that it shouldn't render your page using quirks mode. Even if you don't plan to take advantage of modern HTML5 elements or JavaScript APIs, this will help ensure your page is displayed correctly.
Load JavaScript last
Many web developers recommend loading JavaScript code at the bottom of the page
to increase responsiveness, and this is even more important with the HTML
service. Moving your <script> tags to the end of your page will let HTML
content render before the JavaScript is processed, allowing you to present a
spinner or other message to the user.
Take advantage of jQuery
jQuery is a popular JavaScript library that simplifies many common tasks in web development.