Google Apps Script

Class HtmlOutput

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 sanitized using Google Caja, which applies some limitations to your client-side code. For more information, see the guide to restrictions in HTML service.

Methods

MethodReturn typeBrief description
append(addedContent)HtmlOutputAppends new content to the content of this HtmlOutput.
appendUntrusted(addedContent)HtmlOutputAppends new content to the content of this HtmlOutput, using contextual escaping.
asTemplate()HtmlTemplateReturns an HtmlTemplate backed by this HtmlOutput.
clear()HtmlOutputClears the current content.
getAs(contentType)BlobReturn the data inside this object as a blob converted to the specified content type.
getBlob()BlobReturn the data inside this object as a blob.
getContent()StringGets the content of this HtmlOutput.
getHeight()IntegerGets the initial height of the custom dialog in Google Docs, Sheets, or Forms.
getTitle()StringGets the title of the output page.
getWidth()IntegerGets the initial width of the custom dialog or sidebar in Google Docs, Sheets, or Forms.
setContent(content)HtmlOutputSets the content of this HtmlOutput.
setHeight(height)HtmlOutputSets the initial height of the custom dialog in Google Docs, Sheets, or Forms.
setSandboxMode(mode)HtmlOutputSets the the ECMAScript sandbox mode used for client-side scripts.
setTitle(title)HtmlOutputSets the title of the output page.
setWidth(width)HtmlOutputSets the initial width of a custom dialog or sidebar in Google Docs, Sheets, or Forms.

Detailed documentation

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

NameTypeDescription
addedContentStringthe content to append

Return

HtmlOutput — this HtmlOutput itself, useful for chaining

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>&lt;p&gt;Hello again, world.&lt;/p&gt;"
 var output = HtmlService.createHtmlOutput('<b>Hello, world!</b>');
 output.appendUntrusted('<p>Hello again, world.</p>');
 Logger.log(output.getContent());
 

Parameters

NameTypeDescription
addedContentStringthe content to append

Return

HtmlOutput — this HtmlOutput itself, useful for chaining

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.

Parameters

NameTypeDescription
contentTypeStringthe 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()

Return the data inside this object as a blob.

Return

Blob — the data as a blob


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


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


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 or sidebar 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. Sidebars that are already open cannot be resized.

 
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

NameTypeDescription
contentStringthe content to serve

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

NameTypeDescription
heightIntegerthe new height in pixels; null results in a default value

Return

HtmlOutput — this HtmlOutput itself, useful for chaining


setSandboxMode(mode)

Sets the the ECMAScript 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. This method allows script authors to choose between different versions of the sandbox. For more information, see the guide to restrictions in HTML service.

If a script does not set a sandbox mode, Apps Script uses SandboxMode.NATIVE mode as the default. Prior to February 2014, the default was SandboxMode.EMULATED. The default is subject to change.

NATIVE imposes fewer restrictions than EMULATED and generally runs faster. By contrast, EMULATED mode is more likely to work in older browsers that do not support ECMAScript 5 strict mode, most notably Internet Explorer 9. If NATIVE mode is set but not supported in the user's browser, the sandbox mode falls back to EMULATED mode for that user.

 
// Serve HTML with a defined sandbox mode (in Apps Script server-side code).
 var output = HtmlService.createHtmlOutput('<b>Hello, world!</b>');
 output.setSandboxMode(HtmlService.SandboxMode.EMULATED);
 
The sandbox mode can also 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

NameTypeDescription
modeSandboxModethe sandbox mode to use, when possible

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

NameTypeDescription
titleStringthe new title

Return

HtmlOutput — this HtmlOutput itself, useful for chaining


setWidth(width)

Sets the initial width of a custom dialog or sidebar 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. Sidebars that are already open cannot be resized.

 
var output = HtmlService.createHtmlOutput('<b>Hello, world!</b>');
 output.setWidth(200);
 

Parameters

NameTypeDescription
widthIntegerthe new width in pixels; null results in a default value

Return

HtmlOutput — this HtmlOutput itself, useful for chaining

Authentication required

You need to be signed in with Google+ to do that.

Signing you in...

Google Developers needs your permission to do that.