An HtmlOutput
object that can be served from a script. Due to security considerations,
scripts cannot directly return HTML to a browser. Instead, they must sanitize it so that it
cannot perform malicious actions. You can return sanitized HTML like this:
function doGet() { return HtmlService.createHtmlOutput('<b>Hello, world!</b>'); }The code in the
HtmlOutput
can include embedded JavaScript and CSS. (This is standard
client-side JavaScript that manipulates the DOM, not Apps Script). All of this content is
sandboxed using iframe sandboxing.
For more information, see the guide to restrictions in HTML service.Methods
Method | Return type | Brief description |
---|---|---|
addMetaTag(name, content) | HtmlOutput | Adds a meta tag to the page. |
append(addedContent) | HtmlOutput | Appends new content to the content of this HtmlOutput . |
appendUntrusted(addedContent) | HtmlOutput | Appends new content to the content of this HtmlOutput , using contextual escaping. |
asTemplate() | HtmlTemplate | Returns an HtmlTemplate backed by this HtmlOutput . |
clear() | HtmlOutput | Clears the current content. |
getAs(contentType) | Blob | Return the data inside this object as a blob converted to the specified content type. |
getBlob() | Blob | Return the data inside this object as a blob. |
getContent() | String | Gets the content of this HtmlOutput . |
getFaviconUrl() | String | Gets the URL for a favicon link tag added to the page by calling setFaviconUrl(iconUrl) . |
getHeight() | Integer | Gets the initial height of the custom dialog in Google Docs, Sheets, or Forms. |
getMetaTags() | HtmlOutputMetaTag[] | Gets an array of objects that represent meta tags added to the page by calling addMetaTag(name, content) . |
getTitle() | String | Gets the title of the output page. |
getWidth() | Integer | Gets the initial width of the custom dialog in Google Docs, Sheets, or Forms. |
setContent(content) | HtmlOutput | Sets the content of this HtmlOutput . |
setFaviconUrl(iconUrl) | HtmlOutput | Adds a link tag for a favicon to the page. |
setHeight(height) | HtmlOutput | Sets the initial height of the custom dialog in Google Docs, Sheets, or Forms. |
setSandboxMode(mode) | HtmlOutput | This method now has no effect — previously it set the sandbox
mode used for client-side scripts. |
setTitle(title) | HtmlOutput | Sets the title of the output page. |
setWidth(width) | HtmlOutput | Sets the initial width of a custom dialog in Google Docs, Sheets, or Forms. |
setXFrameOptionsMode(mode) | HtmlOutput | Sets the state of the page's X-Frame-Options header, which controls clickjacking
prevention. |
Detailed documentation
addMetaTag(name, content)
Adds a meta tag to the page. Meta tags included directly in an Apps Script HTML file are ignored. Only the following meta tags are allowed:
<meta name="apple-mobile-web-app-capable" content="..."/> <meta name="google-site-verification" content="..."/> <meta name="mobile-web-app-capable" content="..."/> <meta name="viewport" content="..."/>
var output = HtmlService.createHtmlOutput('<b>Hello, world!</b>'); output.addMetaTag('viewport', 'width=device-width, initial-scale=1');
Parameters
Name | Type | Description |
---|---|---|
name | String | the value of the meta tag's name attribute |
content | String | the value of the meta tag's content attribute |
Return
HtmlOutput
— this HtmlOutput
itself, useful for chaining
append(addedContent)
Appends new content to the content of this HtmlOutput
. Use this only for content from a
trusted source, because it is not escaped.
// Log "<b>Hello, world!</b><p>Hello again, world.</p>" var output = HtmlService.createHtmlOutput('<b>Hello, world!</b>'); output.append('<p>Hello again, world.</p>'); Logger.log(output.getContent());
Parameters
Name | Type | Description |
---|---|---|
addedContent | String | the content to append |
Return
HtmlOutput
— this HtmlOutput
itself, useful for chaining
Throws
Error
— if the HTML is malformed
See also
appendUntrusted(addedContent)
Appends new content to the content of this HtmlOutput
, using contextual escaping.
This method will correctly escape content based on the current state of the HtmlOutput
, so that the result will be a safe string with no markup or side affects. Use this
instead of using append whenever you are adding content from an untrusted source, such as from
a user, to avoid accidentally allowing a cross site scripting (XSS) bug where content or markup
that you append causes unexpected code execution.
// Log "<b>Hello, world!</b><p>Hello again, world.</p>" var output = HtmlService.createHtmlOutput('<b>Hello, world!</b>'); output.appendUntrusted('<p>Hello again, world.</p>'); Logger.log(output.getContent());
Parameters
Name | Type | Description |
---|---|---|
addedContent | String | the content to append |
Return
HtmlOutput
— this HtmlOutput
itself, useful for chaining
Throws
Error
— if the HTML is very malformed
See also
asTemplate()
Returns an HtmlTemplate
backed by this HtmlOutput
. This method can be used to
build up a template incrementally. Future changes to HtmlOutput
will affect the
contents of the HtmlTemplate
as well.
var output = HtmlService.createHtmlOutput('<b>Hello, world!</b>'); var template = output.asTemplate();
Return
HtmlTemplate
— the new HtmlTemplate
clear()
Clears the current content.
var output = HtmlService.createHtmlOutput('<b>Hello, world!</b>'); output.clear();
Return
HtmlOutput
— the HtmlOutput
itself, useful for chaining
getAs(contentType)
Return the data inside this object as a blob converted to the specified content type. This method adds the appropriate extension to the filename—for example, "myfile.pdf". However, it assumes that the part of the filename that follows the last period (if any) is an existing extension that should be replaced. Consequently, "ShoppingList.12.25.2014" becomes "ShoppingList.12.25.pdf".
Parameters
Name | Type | Description |
---|---|---|
contentType | String | The MIME type to convert to. For most blobs, 'application/pdf' is
the only valid option. For images in BMP, GIF, JPEG, or PNG format, any of 'image/bmp' , 'image/gif' , 'image/jpeg' , or 'image/png' are also
valid. |
Return
Blob
— The data as a blob.
getBlob()
getContent()
Gets the content of this HtmlOutput
.
// Log "<b>Hello, world!</b>" var output = HtmlService.createHtmlOutput('<b>Hello, world!</b>'); Logger.log(output.getContent());
Return
String
— the content that will be served
getFaviconUrl()
Gets the URL for a favicon link tag added to the page by calling setFaviconUrl(iconUrl)
. Favicon link tags included directly in an Apps Script HTML file are
ignored.
var output = HtmlService.createHtmlOutput('<b>Hello, world!</b>'); output.setFaviconUrl('http://www.example.com/image.png'); Logger.log(output.getFaviconUrl();
Return
String
— the URL of the favicon image
getHeight()
Gets the initial height of the custom dialog in Google
Docs, Sheets, or Forms. If the HtmlOutput
is published as a web app instead, this
method returns null
. To resize a dialog that is already open, call
google.script.host.setHeight(height)
in client-side code.
var output = HtmlService.createHtmlOutput('<b>Hello, world!</b>'); output.setHeight(200); Logger.log(output.getHeight());
Return
Integer
— the height, in pixels
getMetaTags()
Gets an array of objects that represent meta tags added to the page by calling addMetaTag(name, content)
. Meta tags included directly in an Apps Script HTML file are
ignored.
var output = HtmlService.createHtmlOutput('<b>Hello, world!</b>'); output.addMetaTag('viewport', 'width=device-width, initial-scale=1'); var tags = output.getMetaTags(); Logger.log('<meta name="%s" content="%s"/>', tags[0].getName(), tags[0].getContent());
Return
HtmlOutputMetaTag[]
— an array of objects that represent meta tags added to the page by calling addMetaTag(name, content)
getTitle()
Gets the title of the output page. Note that the <title> HTML element is ignored.
var output = HtmlService.createHtmlOutput('<b>Hello, world!</b>'); Logger.log(output.getTitle());
Return
String
— the title of the page
getWidth()
Gets the initial width of the custom dialog in Google
Docs, Sheets, or Forms. If the HtmlOutput
is published as a web app instead, this
method returns null
. To resize a dialog that is already open, call
google.script.host.setWidth(width)
in client-side code.
var output = HtmlService.createHtmlOutput('<b>Hello, world!</b>'); output.setWidth(200); Logger.log(output.getWidth());
Return
Integer
— the width in pixels
setContent(content)
Sets the content of this HtmlOutput
.
var output = HtmlService.createHtmlOutput(); output.setContent('<b>Hello, world!</b>');
Parameters
Name | Type | Description |
---|---|---|
content | String | the content to serve |
Return
HtmlOutput
— this HtmlOutput
itself, useful for chaining
Throws
Error
— if the HTML is malformed
setFaviconUrl(iconUrl)
Adds a link tag for a favicon to the page. Favicon link tags included directly in an Apps Script HTML file are ignored.
var output = HtmlService.createHtmlOutput('<b>Hello, world!</b>'); output.setFaviconUrl('http://www.example.com/image.png');
Parameters
Name | Type | Description |
---|---|---|
iconUrl | String | the URL of the favicon image, with the image extension indicating the image type |
Return
HtmlOutput
— this HtmlOutput
itself, useful for chaining
setHeight(height)
Sets the initial height of the custom dialog in Google
Docs, Sheets, or Forms. If the HtmlOutput
is published as a web app instead, this
method has no effect. To resize a dialog that is already open, call
google.script.host.setHeight(height)
in client-side code.
var output = HtmlService.createHtmlOutput('<b>Hello, world!</b>'); output.setHeight(200);
Parameters
Name | Type | Description |
---|---|---|
height | Integer | the new height in pixels; null results in a default value |
Return
HtmlOutput
— this HtmlOutput
itself, useful for chaining
setSandboxMode(mode)
This method now has no effect — previously it set the sandbox
mode
used for client-side scripts. To protect users from being served malicious HTML or
JavaScript, client-side code served from HTML service executes in a security sandbox that
imposes restrictions on the code. Originally this method allowed script authors to choose
between different versions of the sandbox, but now all scripts now use IFRAME
mode
regardless of what sandbox mode is set. For more information, see the guide to restrictions in HTML service.
The IFRAME
mode imposes many fewer restrictions than the other sandbox modes and
runs fastest, but does not work at all in certain older browsers, including Internet Explorer
9. The sandbox mode can be read in a client-side script by inspecting google.script.sandbox.mode
. Note that this property returns the actual mode on the client,
which may differ from the mode requested on the server if the requested mode is not supported
in the user's browser.
<!-- Read the sandbox mode (in a client-side script). --> <script> alert(google.script.sandbox.mode); </script>
Parameters
Name | Type | Description |
---|---|---|
mode | SandboxMode | the sandbox mode to use |
Return
HtmlOutput
— this HtmlOutput
itself, useful for chaining
setTitle(title)
Sets the title of the output page. For web apps, this will be the title of the entire page,
while for HtmlOutput
shown in Google Sheets, this will be the dialog title.
var output = HtmlService.createHtmlOutput('<b>Hello, world!</b>'); output.setTitle('My First Page');
Parameters
Name | Type | Description |
---|---|---|
title | String | the new title |
Return
HtmlOutput
— this HtmlOutput
itself, useful for chaining
setWidth(width)
Sets the initial width of a custom dialog in Google
Docs, Sheets, or Forms. If the HtmlOutput
is published as a web app instead, this
method has no effect. To resize a dialog that is already open, call
google.script.host.setWidth(width)
in client-side code.
var output = HtmlService.createHtmlOutput('<b>Hello, world!</b>'); output.setWidth(200);
Parameters
Name | Type | Description |
---|---|---|
width | Integer | the new width in pixels; null results in a default value |
Return
HtmlOutput
— this HtmlOutput
itself, useful for chaining
setXFrameOptionsMode(mode)
Sets the state of the page's X-Frame-Options
header, which controls clickjacking
prevention.
Setting XFrameOptionsMode.ALLOWALL
will let any site iframe the page, so the
developer should implement their own protection against clickjacking.
If a script does not set an X-Frame-Options
mode, Apps Script uses XFrameOptionsMode.DEFAULT
mode as the default.
// Serve HTML with no X-Frame-Options header (in Apps Script server-side code). var output = HtmlService.createHtmlOutput('<b>Hello, world!</b>'); output.setXFrameOptionsMode(HtmlService.XFrameOptionsMode.ALLOWALL);
Parameters
Name | Type | Description |
---|---|---|
mode | XFrameOptionsMode |
Return
HtmlOutput
— this HtmlOutput
itself, useful for chaining