Class HtmlOutput
AnHtml 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 itcannot perform malicious actions. You can return sanitized HTML like this:
functiondoGet(){returnHtmlService.createHtmlOutput('<b>Hello, world!</b>');}
HtmlOutput can include embedded JavaScript and CSS. (This is standardclient-side JavaScript that manipulates the DOM, not Apps Script). All of this content issandboxed usingiframesandboxing. For more information, see theguide to restrictions in HTML service.Methods
| Method | Return type | Brief description |
|---|---|---|
add | Html | Adds a meta tag to the page. |
append(addedContent) | Html | Appends new content to the content of thisHtml. |
append | Html | Appends new content to the content of thisHtml, using contextual escaping. |
as | Html | Returns anHtml backed by thisHtml. |
clear() | Html | Clears the current content. |
get | Blob | Return the data inside this object as a blob converted to the specified content type. |
get | Blob | Return the data inside this object as a blob. |
get | String | Gets the content of thisHtml. |
get | String | Gets the URL for a favicon link tag added to the page by callingset. |
get | Integer | Gets the initial height of thecustom dialog in GoogleDocs, Sheets, or Forms. |
get | Html | Gets an array of objects that represent meta tags added to the page by callingadd. |
get | String | Gets the title of the output page. |
get | Integer | Gets the initial width of thecustom dialog in GoogleDocs, Sheets, or Forms. |
set | Html | Sets the content of thisHtml. |
set | Html | Adds a link tag for a favicon to the page. |
set | Html | Sets the initial height of thecustom dialog in GoogleDocs, Sheets, or Forms. |
set | Html | This method now has no effect — previously it set thesandboxmode used for client-side scripts. |
set | Html | Sets the title of the output page. |
set | Html | Sets the initial width of acustom dialog in GoogleDocs, Sheets, or Forms. |
set | Html | Sets the state of the page'sX-Frame-Options header, which controls clickjackingprevention. |
Detailed documentation
addMetaTag(name, content)
Adds a meta tag to the page. Meta tags included directly in an Apps Script HTML file areignored. 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="..."/>
constoutput=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
Html — This output, for chaining.
append(addedContent)
Appends new content to the content of thisHtml. Use this only for content from atrusted source, because it is not escaped.
// Log "<b>Hello, world!</b><p>Hello again, world.</p>"constoutput=HtmlService.createHtmlOutput('<b>Hello, world!</b>');output.append('<p>Hello again, world.</p>');Logger.log(output.getContent());
Parameters
| Name | Type | Description |
|---|---|---|
added | String | The content to append. |
Return
Html — This output, for chaining.
Throws
Error — if the HTML is malformed
See also
appendUntrusted(addedContent)
Appends new content to the content of thisHtml, using contextual escaping.
This method correctly escapes content based on the current state of theHtml,so that the result is a safe string with no markup or side affects. Use this instead of usingappend whenever you are adding content from an untrusted source, such as from a user, to avoidaccidentally allowing a cross site scripting (XSS) bug where content or markup that you appendcauses unexpected code execution.
// Log "<b>Hello, world!</b><p>Hello again, world.</p>"constoutput=HtmlService.createHtmlOutput('<b>Hello, world!</b>');output.appendUntrusted('<p>Hello again, world.</p>');Logger.log(output.getContent());
Parameters
| Name | Type | Description |
|---|---|---|
added | String | The content to append. |
Return
Html — This output, for chaining.
Throws
Error — if the HTML is very malformed
See also
asTemplate()
Returns anHtml backed by thisHtml. This method can be used tobuild up a template incrementally. Future changes toHtml affect the contents oftheHtml as well.
constoutput=HtmlService.createHtmlOutput('<b>Hello, world!</b>');consttemplate=output.asTemplate();
Return
Html — The newHtml.
clear()
Clears the current content.
constoutput=HtmlService.createHtmlOutput('<b>Hello, world!</b>');output.clear();
Return
Html — This output, for chaining.
getAs(contentType)
Return the data inside this object as a blob converted to the specified content type. Thismethod adds the appropriate extension to the filename—for example, "myfile.pdf". However, itassumes that the part of the filename that follows the last period (if any) is an existingextension that should be replaced. Consequently, "ShoppingList.12.25.2014" becomes"ShoppingList.12.25.pdf".
To view the daily quotas for conversions, seeQuotas for GoogleServices. Newly created Google Workspace domains might be temporarily subject to stricterquotas.
Parameters
| Name | Type | Description |
|---|---|---|
content | 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. For a Google Docs document,'text/markdown' is also valid. |
Return
Blob — The data as a blob.
getBlob()
getContent()
Gets the content of thisHtml.
// Log "<b>Hello, world!</b>"constoutput=HtmlService.createHtmlOutput('<b>Hello, world!</b>');Logger.log(output.getContent());
Return
String — The content that is served.
getFaviconUrl()
Gets the URL for a favicon link tag added to the page by callingset. Favicon link tags included directly in an Apps Script HTML file areignored.
constoutput=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 thecustom dialog in GoogleDocs, Sheets, or Forms. If theHtml is published as a web app instead, thismethod returnsnull. To resize a dialog that is already open, callgoogle.script.host.setHeight(height) in client-side code.
constoutput=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 callingadd. Meta tags included directly in an Apps Script HTML file areignored.
constoutput=HtmlService.createHtmlOutput('<b>Hello, world!</b>');output.addMetaTag('viewport','width=device-width, initial-scale=1');consttags=output.getMetaTags();Logger.log('<meta name="%s" content="%s"/>',tags[0].getName(),tags[0].getContent(),);
Return
Html — An array of objects that represent meta tags added to the page by callingadd.
getTitle()
Gets the title of the output page. Note that the <title> HTML element is ignored.
constoutput=HtmlService.createHtmlOutput('<b>Hello, world!</b>');Logger.log(output.getTitle());
Return
String — The title of the page.
getWidth()
Gets the initial width of thecustom dialog in GoogleDocs, Sheets, or Forms. If theHtml is published as a web app instead, thismethod returnsnull. To resize a dialog that is already open, callgoogle.script.host.setWidth(width) in client-side code.
constoutput=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 thisHtml.
constoutput=HtmlService.createHtmlOutput();output.setContent('<b>Hello, world!</b>');
Parameters
| Name | Type | Description |
|---|---|---|
content | String | The content to serve. |
Return
Html — This output, 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 AppsScript HTML file are ignored.
constoutput=HtmlService.createHtmlOutput('<b>Hello, world!</b>');output.setFaviconUrl('http://www.example.com/image.png');
Parameters
| Name | Type | Description |
|---|---|---|
icon | String | The URL of the favicon image, with the image extension indicating the image type. |
Return
Html — This output, for chaining.
setHeight(height)
Sets the initial height of thecustom dialog in GoogleDocs, Sheets, or Forms. If theHtml is published as a web app instead, thismethod has no effect. To resize a dialog that is already open, callgoogle.script.host.setHeight(height) in client-side code.
constoutput=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
Html — This output, for chaining.
setSandboxMode(mode)
This method now has no effect — previously it set thesandboxmode used for client-side scripts. To protect users from being served malicious HTML orJavaScript, client-side code served from HTML service executes in a security sandbox thatimposes restrictions on the code. Originally this method allowed script authors to choosebetween different versions of the sandbox, but now all scripts now useIFRAME moderegardless of what sandbox mode is set. For more information, see theguide to restrictions in HTML service.
TheIFRAME mode imposes many fewer restrictions than the other sandbox modes andruns fastest, but does not work at all in certain older browsers, including Internet Explorer9. The sandbox mode can be read in a client-side script by inspectinggoogle.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 supportedin 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 | Sandbox | The sandbox mode to use. |
Return
Html — This output, for chaining.
setTitle(title)
Sets the title of the output page. For web apps, this is the title of the entire page, whileforHtml shown in Google Sheets, this is the dialog title.
constoutput=HtmlService.createHtmlOutput('<b>Hello, world!</b>');output.setTitle('My First Page');
Parameters
| Name | Type | Description |
|---|---|---|
title | String | The new title. |
Return
Html — This output, for chaining.
setWidth(width)
Sets the initial width of acustom dialog in GoogleDocs, Sheets, or Forms. If theHtml is published as a web app instead, thismethod has no effect. To resize a dialog that is already open, callgoogle.script.host.setWidth(width) in client-side code.
constoutput=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
Html — This output, for chaining.
setXFrameOptionsMode(mode)
Sets the state of the page'sX-Frame-Options header, which controls clickjackingprevention.
SettingXFrameOptionsMode.ALLOWALL lets any site iframe the page, so thedeveloper should implement their own protection against clickjacking.
If a script does not set anX-Frame-Options mode, Apps Script usesXFrameOptionsMode.DEFAULT mode as the default.
// Serve HTML with no X-Frame-Options header (in Apps Script server-side code).constoutput=HtmlService.createHtmlOutput('<b>Hello, world!</b>');output.setXFrameOptionsMode(HtmlService.XFrameOptionsMode.ALLOWALL);
Parameters
| Name | Type | Description |
|---|---|---|
mode | XFrameOptionsMode | The XFrame options mode to set. |
Return
Html — This output, for chaining.
Except as otherwise noted, the content of this page is licensed under theCreative Commons Attribution 4.0 License, and code samples are licensed under theApache 2.0 License. For details, see theGoogle Developers Site Policies. Java is a registered trademark of Oracle and/or its affiliates.
Last updated 2024-12-03 UTC.