Modules

8th Wall Modules Overview

8th Wall Modules is a powerful 8th Wall feature designed to dramatically increase the efficiency of project development. 8th Wall Modules allow you to save and reuse components (code, assets, files) within your Workspace and also find and import 8th Wall created Modules into your project.

8th Wall Modules aim to:

• Increase the efficiency of your WebAR and WebVR development.
• Reduce the time to market for your project to launch.
• Free up your time to focus on the unique challenges within a project OR to develop more projects.
• Create a resource library to upskill your full-time and freelance team members as well as increase consistency and quality of your work.
• Enable non-technical members of your team to customize projects through a visual configuration system.
• Discover and easily use 8th Wall created resources including popular components and new features.

Module Compatibility

8th Wall Modules may be made available for only 8th Wall hosted projects, only Self-Hosted projects, or both 8th Wall hosted & Self-Hosted projects. By default modules are available for both 8th Wall hosted & Self-Hosted projects. This can be changed in the settings page for the module.

Modules must be properly coded to work in both 8th Wall hosted and Self-Hosted projects. In particular assets referenced from within modules must be loaded as cross-origin enabled so that they can load into Self-Hosted domains. For example, explicitly setting the crossorigin attribute on media:

Or pre-loading a web worker blob using fetch before invoking the web worker:

Creating a New Module

Modules enable you to add modularized assets, files, and code and import them into your projects with a versioning system. This allows you to focus your project code on key differentiators and easily import common functionality via a module that you create.

To create a new module in your workspace:

1. From your Workspace Dashboard, click the "Modules" tab:

2. From the "Modules" tab on the Workspace Dashboard, click "Create new module"

You can also create a new module directly within the context of a project. Within your Cloud Editor project, press the "+" button next to Modules. Then press "Create New Modules" and continue with the instructions below.

3. Enter Basic info for the module: Please provide a Module ID (This ID appears in your workspace url and can be used to reference your module in project code.), and Module Title. The Module Title can be edited later in the Module Settings page.

4. Once you have created your module, you’ll be taken to the module.js file within the Cloud Editor. From here you can begin developing your modules. More details on module development can be found in the Developing your Module section.

Developing a Module

Module development is slightly different from project development. Modules cannot be run on their own and can only be run after being imported into a project. Modules can be developed within a module specific view of the Cloud Editor, or within the context of a project. Modules are only available to the workspace they are developed in.

When developing a module within the module specific view you will not see a “Preview” button on the top navigation of the Cloud Editor since modules can only be previewed when imported into a project.

The main components of a module include:

manifest.json

Within manifest.json you can create parameters that are editable via a visual configurator when modules are imported into projects. Your module.js code can subscribe to the parameters you make available in the module manifest to dynamically change based on user input when configuring the module within the context of a project.

The module config builder automatically starts with one parameter group available. Parameter groups can be used for logical divisions of parameters which are then expressed and grouped visually when using your module in a project.

1. Rename a config group by double clicking the group title.
2. Add a new config group by pressing the "New Config Group" button.
3. Add a parameter to a config group by pressing "+ New parameter".

4. When creating a new parameter you must give your parameter a name. This name could be used in module and project code so it should not include spaces or special characters.
5. Select the type of parameter. Currently supported parameter types include String, Number, Boolean, & Resource.
6. Once you have made your selections press "Next".

NOTE: The order of config groups, and of parameters within these groups, dictates the order that is displayed to users when using a module within a project. You can easily reorder parameters within a group, as well as reorder config groups by dragging them in the order that you want. To switch a parameter from one group to another group press the arrow icon on the parameter field and select the group you want to move the parameter to from the dropdown.

Module Parameter Types & Options

If you are creating a module manifest for your module you will be able to select from different parameter types including String, Number, Boolean, & Resource. Details on each parameter type:

String

String parameters have the following editable fields:

Parameter Fields	Type	Description
Label (1)	String	A human readable name for your parameter that will be displayed in the configuration UI when the module is imported into a project. The default is dynamically generated based on the parameter name.
Default [Optional] (2)	String	The default string value if none is specified when the module is imported into a project. The default is "".

Number

Number parameters have the following editable fields:

Parameter Fields	Type	Description
Label (1)	String	A human readable name for your parameter that will be displayed in the configuration UI when the module is imported into a project. The default is dynamically generated based on the parameter name.
Default [Optional] (2)	Number	The default number value if none is specified when the module is imported into a project. The default is null.
Min [Optional] (3)	Number	The maximum number value a user can input when the module is imported into a project. The default is null.
Max [Optional] (4)	Number	The minimum number value a user can input when the module is imported into a project. The default is null.

Boolean

Boolean parameters have the following editable fields:

Parameter Fields	Type	Description
Label (1)	String	A human readable name for your parameter that will be displayed in the configuration UI when the module is imported into a project. The default is dynamically generated based on the parameter name.
Default [Optional] (2)	Boolean	The default boolean value if none is specified when the module is imported into a project. The default is false.
Label if True [Optional] (3)	String	The label for the true boolean option that will be displayed in the configuration UI when the module is imported into a project. The default is true.
Label if False [Optional] (4)	String	The label for the false boolean option that will be displayed in the configuration UI when the module is imported into a project. The default is false.

Resource

Resource parameters have the following editable fields:

Parameter Fields	Type	Description
Label (1)	String	A human readable name for your parameter that will be displayed in the configuration UI when the module is imported into a project. The default is dynamically generated based on the parameter name.
Allow None (2)	Boolean	Enables/disables the ability to explicitly set the resource to null from the configuration UI when the module is imported into the project. The default is false.
Allowed Asset Extensions [Optional] (3)	File Types	Enables the ability to upload specified file types via the displayed in the configuration UI when the module is imported into a project. The default is all file types.
Default Resource [Optional] (4)	File	The default resource if none is specified when the module is imported into a project. The default is null.

module.js

module.js is the main entry point for your 8th Wall module. Code in module.js will execute before the project is loaded. You can also add other files and assets and reference them within module.js.

Modules can be very different depending on their purpose, and your development style. Typically modules contain some of the following elements:

Subscription to Module Configuration Values

import {subscribe} from 'config'  // config is how you access your module options

subscribe((config) => {
  // Your code does something with the config here
})

Export Properties that Are Referenced in Project Code

export {
  // Export properties here
}

README.md

You can include a readme in your module simply by creating a file named README.md in your module's file directory. Just like project readme module readmes can be formatted using markdown and can include assets like pictures and video.

NOTE: If your module has a readme it will automatically be packaged with the module when you deploy a version. This appropriate module readme will be shown in-context to the module depending on the version of the module being used in the project.

Developing a Module Within the Context of a Project

You can enable development mode within the context of a project on modules owned by your workspace by toggling “Development Mode” (shown in red in the image below) on the module configuration page. Once Development mode is enabled the modules underlying code and files will become visible in the left side-pane.

When a module is in Development Mode within the context of a project you will see additional options on the configuration page including: module client controls (in teal), a module deployment button (in pink), and an "Edit mode" toggle to switch between editing the content of the visual configuration page and using the configuration.

When you are developing modules within the context of a project and have changes to land you will see a land flow that takes you through project and module changes. You can choose whether or not to land specific changes. Any project or module that has changes that you are landing must have a commit message added before you will be able to complete landing your code.

When you are developing modules within the context of a project and have changes you will also notice update to the Abandon & Revert changes options in the cloud editor. You can choose whether or not to Abandon/Revert only project changes or changes to both your project and any modules in development.

Deploying a Module

Initial Module Deployment

Deploying modules enables you to share stable versions, while allowing projects to subscribe to module updates within a version family. This can allow you to push non-breaking module updates to your projects automatically.

To deploy a module for the first time

1. If developing from the module specific view of the Cloud Editor, press the "Deploy" button in the upper right corner. If you are developing a module from within the context of a project, press the “Deploy” button on the upper right corner of the module configuration page.

2. Validate your module title.
3. Select the desired commit for your module version.
4. Write out a description of the initial module functionality in the Release Notes section. This section accepts markdown formatting.
5. Click "Next".

6. Optionally, add a module description and/or a cover image. The module description and cover image are shown in the module import flow when bringing a module into a project. Adding a description and cover image can help differentiate the module, and give other members of your workspace context about the module's use.
7. Click "Deploy".

Deploying Module Updates

Deploying module updates is similar to deploying a module for the first time with two additional deployment options.

1. Version Type: When deploying a module update you will be prompted to choose whether the update is a bug fix, new feature, or major release.
   • Bug Fix: Should be selected for refactored code & fixes for existing issues. Projects with modules subscribed to Bug Fixes or New Features will automatically receive an update when a new Bug Fix module version is available.
   • New Features: Should be selected when you've added additional non-breaking functionality to your module. Projects with modules subscribed to New Features will automatically receive an update when a new New Features module version is available.
   • Major Release: Should be selected for breaking changes. Projects with modules do not receive automatic updates for Major Releases.
2. Set as Pre-Release: After selecting a version type you can mark the version as a pre-release. This will add a pre-release badge to notify other users that the module version is a pre-release, if the version type is Bug Fixes or New Features projects will also not receive an automatic update while a version is marked as a pre-release. To use a pre-release version within a module imported into your project manually select the pre-release version from the version pinning target.

Edit Module Pre-Release

When there is a pre-release active, you can continue to update the pre-release version until you either promote the pre-release, or abandon it.

To edit a module pre-release:

1. If developing from the module specific view of the Cloud Editor after previously setting a new version as a pre-release, press the "Deploy" button in the upper right corner. If you are developing a module from within the context of a project after previously setting a new version as a pre-release, press the "Deploy" button on the upper right corner of the module configuration page.

2. Select a new commit for your pre-release or keep the current commit.
3. Change the description of the module version functionality in the Release Notes section. This section accepts markdown formatting.
4. Check the "Promote to Release" checkbox if you are ready to convert your pre-release to a standard release.
5. Press "Abandon Pre-Release" to delete the pre-release. This would typically be used to select a different version type from what the pre-release is currently set to (ex. Move from bug fixes to major release with breaking changes). Projects with modules currently pinned to the pre-release will continue to run with the pre-release version until they receive a subscribed update, or are manually changed.
6. The "Deploy" button makes your edited pre-release changes available (either updating the pre-release, or promoting to release if that checkbox is selected):

Importing Modules into a Cloud Editor Project

Modules enable you to add reusable components to your project, allowing you to focus on the development of your core experience. The 8th Wall Cloud Editor allows you to import modules you own, or modules published by 8th Wall directly into your projects.

To import a module into your Cloud Editor project:

1. Within the Cloud Editor, press the "+" button next to Modules.

2. Press "Public Modules" to import a module created by 8th Wall, or "My Modules" to import a module created by a member of your workspace. Only modules that are 8th Wall hosted project compatible will be available to import. (Learn more about Module Compatibility)

3. Select the module that you want to import from the list.

4. Press "Import" to add your module to your project. Take note of the module alias. If you already have a module in your project with the same alias, you may need to rename your module.

5. The module is now visible in your project listed under the "Modules" section.

6. If you select the imported module, you will be taken to the module config page. This page can be used to configure various module parameters.

7. If you import a module that your team create you will see multiple pinning target options including "Version" (only if the module has been deployed at least once), "Commit" (allows you to pin the module to any commit of the module code), and "Development" (allows you to use module code that you have in your local client and has not been landed yet - this is mainly used for testing / active development). If you select a "Version" pinning target you can subscribe your imported module to bug fix updates, minor updates, or disable automatic module updates.

8. Once you have added a module to your project you may have to make changes to your code to fully integrate the module. Modules with readmes contain documentation that should be referenced to understand how to integrate the specific module into your project code.

Importing Modules into a Self-Hosted Project

Modules enable you to add reusable components to your project, allowing you to focus on the development of your core experience. You can import modules you own, or modules published by 8th Wall directly into your self-hosted projects.

To import a module into your Self-Hosted project:

1. Within the Cloud Editor, open your Self-Hosted project and press the Module icon in the left navigation:

2. Press "+" or "Import Module" to add an available module to your project.

3. Press "Public Modules" to import a module created by 8th Wall, or "My Modules" to import a module created by a member of your workspace. Only modules that are Self-Hosted project compatible will be available to import. (Learn more about Module Compatibility)

4. Select the module that you want to import from the list.

5. Press "Import" to add your module to your project. Take note of the module alias. If you already have a module in your project with the same alias, you may need to rename your module.

6. You can add up to 10 modules to your Self-Hosted project. These modules will be visible as tabs on the Project Modules page of the 8th Wall Cloud Editor.

7. If you select the imported module, the module configuration details will be displayed. This can be used to configure various module parameters.

8. If you import a module that your team created you will see multiple pinning target options including "Version" (only if the module has been deployed at least once), and "Commit" (allows you to pin the module to any commit of the module code). If you select a "Version" pinning target you can subscribe your imported module to bug fix updates, new feature updates, or disable automatic module updates.

9. Once you have added a module to your project press "Copy Code" and paste the contents of your clipboard into the head.html file of your project. This snippet enables modules to be loaded into your Self-Hosted project with the module config settings you have specified. You will have to re-copy the code snippet and update the head.html of your project whenever you make a change to the module config settings.

10. You may have to make changes to your code to fully integrate the module.