Extend Editor

Integration Options

The Extend Editor can be integrated into your product to provide your users with a first-class, web-based development experience for extensions. There are two ways to expose the Extend Editor to your users: you can host it as part of your own web site, or you can link to it and open it up as a stand-alone web application.

Extend Editor

In either mode of integration, Extend Editor supports a range of configuration options to allow you to tailor it’s behavior.

Hosting the Editor in Your Web Site

Extend Editor can be hosted within your own web site and customized to provide your users with the most streamlined, built-in experience. Extend Editor can be added with just a few lines of script:

<!DOCTYPE html>
<html>
<head>
  <script src="https://cdn.auth0.com/auth0-extend/1/extend-editor.js"></script>
</head>
<body>
  <div id="extend-editor" style="height: 400px; width: 600px"></div>
  <script>
    ExtendEditor.create(document.getElementById('extend-editor'), {
      hostUrl: '{host_url}',
      webtaskContainer: '{webtask_container}',
      token: '{webtask_token}',
      webtaskName: 'webtask-sample',
      // If `webtask-sample` does not exist, Extend editor will create 
      // a webtask `webtask-sample` with a sample code.
      createIfNotExists: true 
    });
  </script>
</body>
</html>

In the typical situation, the Extend Editor would be presented to an authenticated user from the administration section of your web site, and the {webtask_container} and {webtask_token} would be specific to the tenant in your system they are managing. In a more general case, the {host_url}, {webtask_container}, and {webtask_token} are specific to the selected isolation scope.

See Express handler that renders the page with Extend Editor.
See how the Extend Editor is embedded in the settings page.

NOTE When experimenting with the code snippet above, you can use the same parameters as you use for running the sample application. However, remember to never disclose your {master_webtask_token} to customers.

The minimal configuration above will display the Extend Editor using all the default options:

Default Extend Editor

Configuring Extend Editor

Several aspects of the Extend Editor can be controlled through the options object passed to it on initialization.See how Extend Editor is configured in the sample application.

Configuration Options

Option Description
token* The webtask token the Extend Editor will use to authorize calls to Auth0 Extend management APIs. This token is specific to the selected isolation scope. In the most common case it is a tenant webtask token.
webtaskContainer* The webtask container the Extend Editor will use when managing extensions. Similarly to the token, the webtask container is specific to the selected isolation scope. In the most common case it is specific to the tenant in your system.
webtaskName The name of the extension (webtask) the Extend Editor will load to enable the user to edit. In the integration pattern described in this guide, extensions are created in code before the Extend Editor is opened to edit them, which means you will always specify this parameter.
hostUrl The base URL of the Auth0 Extend deployment to use. If you are an Auth0 Extend customer, this will be a URL that is unique to you. If you are trying out Auth0 Extend, you can get this parameter from this page. If not specified, defaults to https://webtask.it.auth0.com.
theme The enumeration or URL to select the CSS that allows you to customize the look & feel of the Extend Editor. We provide two themes to choose from out of the box: light and dark. Alternatively, you can specify a URL to custom CSS with overrides of the default styles.
allowHashParams Determines whether individual configuration options can be overriden with hash parameters specified in the URL of the page where Extend Editor is hosted.
allowCreating Determines whether the user will be able to create new extensions. Setting this to false will only allow the user to edit the extension identified with webtaskName.
allowSwitching Determines whether the user will be able to switch the extension (webtask) being edited within the webtaskContainer. Set this to false if you want to only allow the user to edit a specific webtask.
allowUpdating Determines if changes the user makes can be saved.
allowAccessingLogs Determines whether the user can open the real-time logs panel to inspect the logs generated by code executing in their webtask container.
allowEditingSecrets Determines whether the user can open the secrets panel to add, edit, or inspect the secret configuration parameters associated with the edited extension.
allowEditingMeta Determines whether the user can open the metadata panel to add, edit, or inspect the metadata associated with the edited extension. Direct manipulation of metadata by end users is only required in advanced cases, so in most situations you will set this to false.
allowEditingSchedule Determines whether the user can manage the execution schedule for the extension. Extensions with an associated execution schedule are CRON jobs - they are automaticaly executed by the Auth0 Extend runtime without having to be explicitly invoked from your platform.
allowSwitchingTemplates Determines whether the user can switch to a different extension template when editing an existing extension. This is useful if you want to provide the user with a choice of extension templates, possibly addressing different use cases of using a specific extensibility point.
allowCreatingFromTemplate Determines whether the user can use the list of templates you specified as a basis for new extensions that create. This setting is only effective if allowCreating is set to true.
allowRenaming Determines whether the user can rename a webtask or not.
allowDeleting Determines whether the user can delete a webtask or not.
allowEditingDependencies Determines whether the user can edit npm dependencies or not.
preventClosingWindowIfDirty Determines if Extend editor should check for browser closing event.
createIfNotExists If webtaskName is provided, determines if Extend editor should create a webtask if the name provided does not exist.

Header Options

Controls how the header is displayed. You can set this property to false if you want to hide the header completely.

Option Description
enabled Setting it to false will have the same effect as setting the header property itself to false: it will hide the header.
logoUrl URL to a logo to display on the header line. This allows you to white-label the Extend Editor to use your brand.

Toolbar Options

Controls how the toolbar is displayed. You can set this property to false if you want to hide the toolbar completely.

Option Description
enabled Setting it to false will have the same effect as setting the toolabr property itself to false: it will hide the toolbar.
displayName Setting this to false will hide the name of the edited extension (webtask).

Controls how the footer is displayed. You can set this property to false if you want to hide the footer completely.

Option Description
enabled Setting it to false will have the same effect as setting the footer property itself to false: it will hide the footer.
displayWebtaskUrl Settings this to false will hide the url of the current webtask.
displayWebtaskWeight Setting this to false will hide the weight metter.
allowCustomItems Settings this to false will disallow editors to publish content to the footer.

Runner Options

Determines whether and how the editor displays the runner pane for executing the extensions. Set to false to disable the runner, or to an object with options as outlined below.

Option Description
methods Array of HTTP methods the runner will allow the user to choose from.
explanation A short description of the purpose of the request.
sample Sample request payload to pre-populate the runner with.
expandLogs Automatically show logs when pressing run.
methodSelector Derterminates if the method selector will be visible or not.
headersEditor Determines whether and how the editor displays the HTTP request header section for executing the extensions. Set to false to disable the the ability to manipulate request headers, or to an object with options as outlined below.
headersEditor.defaultHeaders A hash of header names to string header values or a function (ctx) => 'strig' that maps webtask runtime context to a header value.
headersEditor.expand Automatically expand the headers section
paramsEditor Determines whether to show the query parameter editor for users to specify custom request headers.
paramsEditor.defaultParams A hash of params names to string params values.
paramsEditor.expand Automatically expand the params section
bodyEditor Determines whether and how the editor displays the HTTP request body editor section for executing the extensions. Set to false to disable the the ability to manipulate request body, or to an object with options as outlined below.
bodyEditor.typeSelector Determines whether to show the request body type selector.
bodyEditor.defaultType Allowed types are raw, form-data, x-www-form-urlencoded.
bodyEditor.expand Automatically expand the body section
bodyEditor.rawTypeOptions.defaultMode Determines the default mode for editing raw request body. Allowed values are json, xml, or text.
bodyEditor.rawTypeOptions.enabled Determines whether to allow the user to change the mode of editg the rawType option.

Expand Options

Determines which panels will be expanded when Extend Editor is displayed.

Option Description
left Determines which panel will be expanded at left. Allowed values are explorer, secrets, meta, dependencies, github, scheduler, templates.
right Determiens which panel will be expanded at right. Allowed value runner.
bottom Determines which panel will be expanded at bottom. Allowed value logs.

Configuration Options

Theme {string}

The default value is dark,

// Rendering Extend editor using light-theme. 
var options = {
  theme: 'light'
}

// Rendering Extend editor using dark-theme. 
var options = {
  theme: 'dark' // Default value
}

// Extend editor allows you to use a custom theme by pointing to a CSS file.
var options = {
  theme: 'https://cdn.auth0.com/webtask-editor/styles/develop/auth0-theme.css'
}

Examples of theme:

allowHashParams {boolean}

The default value is false.

var options = {
  allowHashParams: true
}

allowCreating {boolean}

The default value is false.

var options = {
  allowCreating: true
}

allowSwitching {boolean}

The default value is false.

var options = {
  allowSwitching: true
}

Examples of allowSwitching:

allowUpdating {boolean}

The default value is true,

var options = {
  allowUpdating: true
}

allowAccessingLogs {boolean}

The default value is true.

var options = {
  allowAccessingLogs: true
}

Example of allowAccessingLogs:

allowEditingSecrets {boolean}

The default value is true.

var options = {
  allowEditingSecrets: true
}

Examples of allowEditingSecrets:

allowEditingMeta {boolean}

The default value is true.

var options = {
  allowEditingMeta: true
}

Examples of allowEditingMeta:

allowEditingSchedule {boolean}

The default value is true.

var options = {
  allowEditingSchedule: true
}

allowSwitchingTemplates {boolean}

The default value is true.

var options = {
  allowSwitchingTemplates: true
}

allowCreatingFromTemplate {boolean}

The default value is false.

var options = {
  allowCreatingFromTemplate: true
}

allowRenaming {boolean}

The default value is false.

var options = {
  allowRenaming: true
}

allowDeleting {boolean}

The default value is false.

var options = {
  allowDeleting: true
}

allowEditingDependencies {boolean}

The default value is true.

var options = {
  allowEditingDependencies: true
}

Examples of allowEditingDependencies:

preventClosingWindowIfDirty {boolean}

The default value is true.

var options = {
  preventClosingWindowIfDirty: true
}

createIfNotExists {object}

The default value is false.

// If `my-webtask` does not exist, Extend editor will create 
// a webtask `my-webtask` with the following code:
//
//  module.exports = function(context, cb) {
//    cb(null, { hello: 'world' });
//  }; 

var options = {
  webtaskName: 'my-webtask',
  createIfNotExists: true
}
// If `my-webtask` does not exist, Extend editor will create 
// a webtask `my-webtask` with the code at `my-category`.`empty-function`.

var options = {
  webtaskName: 'my-webtask',
  createIfNotExists: {
    enabled: true,
    category: 'my-category'
  },
  categories: [{
    name: 'my-category',
    templates: [{
      default: true,
      name: 'empty-function',
      code: [
        'module.exports = function(context, cb) {',
        '  cb(null, { hello: \'world\' });',
        '};',
      ].join('\n')
    }]
  }]
}

Header Options

header {object}

Header options are grouped in the theme property of the configuration object.

header.enabled {boolean}

The default value is false;

var options = {
  header: {
    enabled: true
  }
}

Example of header.enabled:

header.logoUrl {string}

var options = {
  header: {
    logoUrl: 'https://cdn.auth0.com/auth0-extend/assets/logo-dark.svg'
  }
}

Toolbar Options

toolbar {object}

Toolbar options are grouped in the toolbar property of the configuration object.

toolbar.enabled {boolean}

The default value is true.

var options = {
  toolbar: {
    enabled: true
  }
}

Examples of toolbar.enabled:

toolbar.displayName {boolean}

The default value is true.

var options = {
  toolbar: {
    displayName: false
  }
}

Example of toolbar.displayName:

Footer options are grouped in the footer property of the configuration object.

footer.enabled {boolean}

The default value is true.

var options = {
  footer: {
    enabled: true
  }
}

footer.displayWebtaskUrl {boolean}

The default value is false.

var options = {
  footer: {
    displayWebtaskUrl: true
  }
}

Example of displayWebtaskUrl:

footer.displayWebtaskWeight {boolean}

The default value is false.

var options = {
  footer: {
    displayWebtaskWeight: true
  }
}

Example of displayWebtaskWeight:

footer.allowCustomItems {boolean}

The default value is true.

var options = {
  footer: {
    allowCustomItems: false
  }
}

Runner Options

runner {object}

Runner options are grouped in the runner property of the configuration object.

methods {array}

var options = {
  runner: {
    methods: ['POST']
  }
};

NOTE: If there is only one method declared, the methodSelector prop will be set to false.

methodSelector {boolean}

The default value is true.

var options = {
  runner: {
    methodSelector: true
  }
};

explanation {string}

The default value is empty.

var options = {
  runner: {
    explanation: 'Here you will be able to simulate an ....'
  }
};

Example of explanation:

sample {string}

The default value is empty.

var options = {
  runner: {
    sample: [
      '{',
      ' "key": "value"',
      '}',
    ].join('\n')
  }
};

Example of sample:

expandLogs {boolean}

The default value is false.

var options = {
  runner: {
    expandLogs: true
  }
};

enabled {boolean}

The default value is true.

var options = {
  runner: {
    enabled: true
  }
};

headersEditor {object}

var options = {
  runner: {
    headersEditor: {
      enabled: true,
      defaultHeaders: {
        'Content-Type': 'application-json'
      },
      expand: true
    }
  }
};

Example of headersEditor:

paramsEditor {object}

var options = {
  runner: {
    paramsEditor: {
      enabled: true,
      defaultParams: {
        'q': 'name=john'
      },
      expand: true
    }
  }
};

Example of paramsEditor:

bodyEditor {object}

var options = {
  runner: {
    bodyEditor: {
      enabled: true,
      expand: true,
      typeSelector: false,
      defaultType: 'raw',
      rawTypeOptions: {
        enabled: true,
        defaultMode: 'json'
      }
    }
  }
};

Example of bodyEditor:

Expand Options

expand {object}

Expand options are grouped in the expand property of the configuration object.

expand.left {string}

var options = {
  expand: {
    left: 'secrets'
  }
}

expand.right {string}

var options = {
  expand: {
    right: 'runner'
  }
}

expand.bottom {string}

var options = {
  expand: {
    bottom: 'logs'
  }
}

Available versions

Production
  • https://cdn.auth0.com/auth0-extend/1/extend-editor.js
  • https://cdn.auth0.com/auth0-extend/1.1/extend-editor.js
  • https://cdn.auth0.com/auth0-extend/1.1.1/extend-editor.js
Development
  • https://cdn.auth0.com/auth0-extend/develop/extend-editor.js

Installing from NPM

If you already have a React application, you can just add our NPM module to your project by doing:

npm install @auth0extend/extend-editor-react --save

Note: If you find a bug or you want so share something you’d like to change you can file it here.

Usage

Configuration Options

Name Type Description Default value
settings Object Extend Editor configuration object. For more info click here. -
libUrl Integer The Url to the Extend Editor library. https://cdn.auth0.com/auth0-extend/1/extend-editor.js
on Object The handler for the Extend Editor events like didWebtaskLoad. -
height Integer The heigh of the Extend Editor. 450px
width Integer The width of the Extend Editor. 100%

Examples

Following, you’ll find examples about how to use the different properties of the component.

Customizing the Editor
import React from 'react';
import { Component } from 'react';
import ExtendEditor from '@auth0extend/extend-editor-react';

export default class MyApp extends Component {
  render() {
    return (
      <div>
        <h1>My App</h1>
        <ExtendEditor
          settings= 
          height={500}
        />
      </div>
    );
  }
}

Note: For more information about settings click here.

Attaching to events
import React from 'react';
import { Component } from 'react';
import ExtendEditor from '@auth0extend/extend-editor-react';

export default class MyApp extends Component {
  onEditorDidSaveWebtask(data) {
    console.log(data);
  }

  onEditorError(data) {
    console.log(data);
  }

  render() {
    return (
      <div>
        <h1>My App</h1>
        <ExtendEditor
          settings= 
          on=
        />
      </div>
    );
  }
}

Using Extend Editor as a Stand Alone Web App

You can run the Extend Editor as a stand alone web application instead of embedding it within your web site. Hosted version of the Extend Editor is already part of your Auth0 Extend installation. You can access using the following URL:

{host_url}/edit/{webtask_container}#/{webtask_name}/{webtask_token}

or without specifying the webtask_name

{host_url}/edit/{webtask_container}#/{webtask_token}

The {host_url}, {webtask_container}, {webtask_token}, and {webtask_name} parameters are the same as you would otherwise specify when hosting the editor in your web site.

NOTE: The URL contains the webtask token in the hash params, and as such care must be taken when sharing this URL. There is nothing that would prevent a security-unaware user from passing this URL around and therefore disclosing their webtask token.

NPM Modules

The Auth0 Extend editor allows you to easily manage the list of NPM modules that your code depends upon. You can add, edit or remove NPM module dependencies by clicking on the tools icon in the editor toolbar and then selecting the NPM Modules option to open the NPM Modules panel.

Adding a module

With the NPM Modules panel open, click on the Add Module link to launch the search dialogue box. You can then search for and select any NPM module from the public NPM repository.

After selecting an NPM module, you will notice that the NPM module name and version will be automatically added to the list of dependencies in the NPM Modules panel.

Note: After adding a new module the editor may show the webtask as dirty. This is because the dependencies are only saved when the webtask is saved.

Editing a module

If you have already added an NPM module as a dependency, you can select a different version of the module. Click on the edit icon next to the NPM module entry to launch a dialog box that lists all of the available versions of that given NPM module. After selecting the new version of the module, click on the save button to update the module version.

Note: The module version is only updated when the webtask is saved.

Removing a module

To remove an NPM module that was previously added as a dependency, click on the delete icon next to the NPM module entry. A dialogue box will ask you to confirm that you want to remove that given module from the list of dependencies. Click ‘yes’ to remove the NPM module.

Note: The module is removed when the webtask is saved.