Note: This guide has been updated to conform to the new Custom Elements version 1 specification. You can view the specification and learn more about it.
As of July 2021, outdated custom components are no longer be supported in Google Web Designer. To update your custom components, check out the upgrade guide.
Experienced web developers can write their own custom components for Google Web Designer, either extending existing components or building new ones from scratch. Other users can install these custom components to add functionality to their projects without editing any code.
A valid component package consists of a .zip file containing a JSON manifest file. The package may also include other files, such as a JavaScript file that defines a custom HTML element or other necessary JavaScript and CSS files.
1. Define a custom element
Custom components are implemented in Google Web Designer as custom elements.
A custom element is an HTML element type that you define with JavaScript code and give a custom tag name. Once you define a custom element, you can use it just like any standard element. The DOM APIs that work with native HTML elements also work with custom elements.
Learn more about custom elements in the HTML specification at WHATWG.
Follow these guidelines for custom elements in Google Web Designer:
- The tag name for custom elements must contain a hyphen (
-), likex-panelorexpand-button. - The
gwd-namespace is reserved by Google Web Designer and cannot be used in your custom elements.
See an example of custom element code
2. Create any additional JavaScript and CSS files
Write the JavaScript and CSS that provide the functionality and styling you want.
It's possible to serve JavaScript and CSS files from an external server instead of including those files in the package. Include references to external files in the JSON manifest.
3. Transpile your code to ES5 (optional)
For maximum browser compatibility, we recommend that you transpile your component code to use the JavaScript ES5 syntax. This helps ensure that your component runs properly on older browsers.
- Go to Babel, a JavaScript complier, at https://babeljs.io/repl.
- Under the Presets section, select es2015.
- Copy and paste your component JavaScript code into the left pane. A translated version of the code appears in the right pane, which you can use for your component.
4. Create a JSON manifest of the component files
Custom components require a manifest file in JSON format named manifest.json that tells Google Web Designer about the component. Follow the schema detailed below. Properties of note include:
| Property | Notes |
|---|---|
type |
Required. |
version |
Required. Increment the version number whenever updating a custom component. |
customElementsVersion |
Required for new components conforming to the Custom Elements v1 specification. |
files |
List other files included in the custom component package. |
externalScripts |
Specify external script dependencies. These scripts are automatically added in a <script> block to the <head> of the document. |
dependencies |
Specify any component dependencies. These are existing components with JavaScript or CSS files that your component uses. |
attributes |
Users see attributes in the Properties panel. |
events |
Users see events in the Event dialog. |
methods |
Users see methods as actions in the Event dialog. |
Manifest schema
| Manifest schema |
|---|
{
"name": {string} The human-readable name of the component.
"description": {string} A succinct but complete description of the component.
"type": {string} The element type, which must contain a hyphen (-). Required.
"version": {number} The component version number, which must be incremented with each update. Required.
"customElementsVersion": {number} The Custom Element specification version number, which should be set to 1 for newly authored components. Required for new components.
"files": {Array.<FilesObject>} The JavaScript and CSS files for the component.
"externalScripts": {Array.<string>} The external scripts for the component.
"externalStyles": {Array.<string>} The external style sheets for the component.
"dependencies": {Array.<string>} Other components that this component depends on.
"attributes": {Array.<Attribute>} The attributes of the component.
"methods": {Array.<Method>} The methods of the component.
"events": {Array.<Event>} The events sent by the component.
"metrics": {Array.<MetricEvent>} The metrics tracked for the component.
}
|
FilesObject { "js": {Array.<string>} The path to JavaScript files, relative to the manifest.json file. "css": {Array.<string>} The path to the CSS files, relative to the manifest.json file. }
Attribute { "name": {string} The name of the attribute. "label": {string} The human-readable name of the attribute. "type": {string} The data type of the attribute. "description": {string} A short description of the attribute. "required": {boolean} Whether the attribute is required. "defaultValue": {string|boolean} The default value of the attribute. "min": {number} Minimum value for the attribute, if the attribute is a number. "max": {number} Maximum value for the attribute, if the attribute is a number. "accept": {number} File types accepted, if the attribute is a file. "gwdSpecific": { "important": {boolean} When true, includes the attribute in the component tag. "label": {string} The key in the strings file for translation. "advanced": {boolean} Whether this attribute is shown in the Advanced properties section of the Properties panel. "v1Name": {string} The name of this attribute in v.1 of Google Web Designer. } "bindable": {boolean} When true, the attribute is exposed on the Bindings tab of the Dynamic Properties dialog. }
Event { "name": {string} The name of the event. "label": {string} The human-readable name of the event. "description": {string} A couple of sentences describing the event. "parameters": {Array.<string>} The parameters of the event; by default, the Event object. }
Method { "name": {string} The name of the method. "label": {string} The human-readable name of the method. "description": {string} A short description of the method. "parameters": {Array.<Parameter>} The parameters of this method. }
Parameter { "name": {string} The name of the parameter. "label": {string} The human-readable name of the parameter. "type": {string} The data type of the parameter. "optional": {boolean} Whether the parameter is optional. }
MetricEvent { "eventName": {string} The event that's tracked for this metric. "metric": {string} The text used when reporting the tracked event. "isCumulative": {boolean} Whether the metric is cumulative. "exit": {string} The exit associated with the metric event. }
See an example of a JSON manifest
5. Package the custom component files
Once you finish building and testing your custom component, package it for use in Google Web Designer by following these steps:
- Concatenate, minify, and obfuscate (if necessary) the JavaScript files.
- Optionally, minify the CSS.
- Create a .zip file that contains all the component files, including the JSON manifest.
See an example of a custom component package
Provide the .zip file to Google Web Designer users who want to install your custom component.