Marketplace

One of the core features of A8Studio is Forms. We can create almost any type of form and capture the values from our users. The form is provided with a basic set of components which we can drag and drop in the form creation area and create the form.

There are scenarios where the required feature isn’t available in the form and in those cases, we have to rely on the developers to add the desired functionality in the form.

Why do we need a marketplace?

A8Marketplace is a one-stop solution for adding any desired functionalities in the form without the need for developers. The marketplace consists of widgets that can be seamlessly plugged into any form and the form designer can interact with the widgets to build almost any kind of user interface.

Terminologies

Store

Also known as Marketplace store. It contains a list of all the widgets that can be installed to an org, which can then be used in the form.

Widget / Plugin

A widget or plugin is a marketplace component that can be installed in an org, which can then be dragged into the form.

Widget API Functions

Each widget exposes certain custom functions that can be used to interact with the widget.

Config

Each widget provides a specific custom configuration that can be used to display the properties pane in a8studio.

Package

Each widget can be a standalone component or part of a package.

Core concepts

How to see the list of widgets in the marketplace?

1. Login to A8Studio
2. Select an existing app or create a new one.
3. Click the marketplace icon from the sidebar.
4. On the marketplace homepage, you will find the list of widgets.

How to create a new widget?

Create artifact

1. Check if you have a node version >= v12

2. Use the CLI tool to create the artifact template.

   1. Run the command in your terminal:
      1. npx create-a8-component on a Linux system.
      2. npx @autonom8/create-a8-component on a Windows system.
   2. Select the directory name (defaults to a8-component). Keep this as your widget name in order to separate it from other widgets.
   3. Select the desired template for creating the artifact. It can either be Javascript or TypeScript. Defaults to JavaScript.
   4. Select the type. Specify if it is a widget or a package. The artifact will be generated based on this choice.
   5. Initialize the git repository. Type “y” for yes and “n” for no.
   6. Enter the package name. Defaults to a8-marketplace.
   7. Enter the package version. Defaults to 1.0.0
   8. Enter the optional package description.
   9. Enter a unique build-Id. This will be the identifier of each widget.
   10. Install dependencies by selecting the yes option. If you want to manually install the dependencies, then you can opt out by selecting the no option.

   This will create a template with the provided directory name. Open the directory in your favorite IDE. Inside the src folder, you will find the file App.jsx or App.tsx based on the template selected. This is where you can add the desired functionality of the widget.

3. Run the command npm run start to view the plugin locally during development.

4. After development is finished, run the command npm run build to build the project locally.

5. Run the command npm run package to create an artifact out of the build directory. This will create a zip folder in the root directory of this widget. We will use this to create a widget in a8Studio in the next step.

Create a widget in a8Studio

1. Login to A8Studio
2. Select an existing app or create a new one.
3. From the sidebar select the marketplace icon.
4. On the marketplace homepage, click + icon on the top right corner to access the Create Widget page.
5. Enter a unique application name.
6. Enter a build ID. This buildID has to be unique and will be used as an identifier while creating the artifact.
7. Enter widget description and an optional short description.
8. Attach widget screenshots (optional)
9. Upload application preview image. This will be the widget icon.
10. Upload the widget artifact which you have created in this step.
11. Add helpful tags.
12. Add a widget version (For example: 1.0.0)
13. Write release notes to identify the features of this widget.
14. Write the author's email and website.

Create widget config

To provide dynamic content, you can add properties to the widget by providing the config. After creating the template in this step, you will find a file called config.ts or config.js based on the template type. These configurations can be accessed inside the properties panel in the form designer.

The following types are supported in the config file:

• String
• Array
• Number
• Object
• Function

To do: You can find an example config file for reference here.

Create widget API

When creating a marketplace plugin, you have the option to expose a set of APIs. The user can interact with the exposed APIs to change/modify certain properties of that particular plugin. To create an API for your plugin, create a function, typically named "api".

const api = (widgetId) => {}

This function will return an object where each field will be a function on its own (aka methods). Our function will take one parameter (conventionally referred to as "widgetId") which will be used by 'a8forms' internally. More on that later.

  const api = (widgetId) => { 
    return { 
      methodName() { 
      // implementation will go here
      },
    }
  }

To make life easier for the plugin developers, we have a8forms, which will be available in the global window object. a8forms contain utility methods that can be used to retrieve/update the properties of a plugin.

This means most of the work is taken care of by a8forms and you only have to learn the surface level API of a8forms.

Let's go through an example. We are going to create an API for a simple plugin called "Label". For reference, the schema for this plugin might look like this:

  {
    elementId: "myLabel",
    data: {},
    properties: {
      label: "",
    },
    // other properties here...
  }

For this example, we are going to expose a method called setLabel which can be used to set the label. We'll be making use of the utility method setValue available in a8forms to achieve this.

  const api = (widgetId) => {
    return {
      setLabel(label) {
        window.a8forms.setValue(widgetId, "properties", { label })
      },
    }
  }

The setValue method takes three parameters. The first one is widgetId. It will be used to uniquely identify a plugin inside our forms.

The second parameter is the "key". If you look at the schema above, you can see that the label field is lying inside the properties field. That's the reason we are passing "properties" in the second argument. If you want to update the fields residing inside the "data" field, you need to pass "data" in the second argument.

The third parameter is the actual data that we want to set. In this case, since we are only interested in changing the label, we are passing an object with only one field named "label".

That's it. Wait, there's one thing still left to do. You need to additionally provide type definitions so that the A8Studio editor can provide useful IntelliSense when the user is trying to interact with your plugin.

For our simple API, you can provide type definitions like the one shown below:

  const typeDefs = `
    interface ILabel {
      setLabel(label: string) => void;
    }

    Label(widgetId: string) => ILabel;
  `;

Finally, the user will be able to interact with the API like this:

a8forms.Label("myLabel").setLabel("The End")

To keep this section short and concise, some explanations might be left out. You may need to check out this repository for reference.

How to install a widget?

A widget can be installed to an org from the marketplace homepage and also from the widget detail page.

1. Login to A8Studio.
2. Select an existing app or create a new one.
3. From the sidebar select the marketplace icon.
4. Click the install button, widget card.
5. The widget will be installed in the org and the label will change to installed.

Note: Only org admin or user with required permissions, can install the widget.

How to uninstall a widget?

1. Login to A8Studio.
2. Select an existing app or create a new one.
3. From the sidebar select the marketplace icon.
4. Click on the menu icon present on the widget card.
5. Select the uninstall menu to uninstall the widget.

Note: Only an org admin or a user with required permissions can uninstall the widget.

How to edit a widget in the marketplace?

1. Login to A8Studio.
2. Select an existing app or create a new one.
3. From the sidebar select the marketplace icon.
4. Click on the menu icon on the widget card.
5. Select the Edit menu to edit the widget.
6. Edit a unique application name.
7. Build ID can't be edited (Disabled).
8. Edit widget description and an optional short description.
9. Edit widget screenshots (optional).
10. Edit application preview image. This will be the widget icon.
11. Upload widget can’t be edited (Disabled).
12. Edit helpful tags.
13. The widget version can’t be edited (Disabled).
14. Release notes can’t be edited (Disabled).
15. Edit the author's email and website.

Note: Only an org admin or a user with required permissions can edit the widget.

How to release a new version of the widget?

1. Login to A8Studio.
2. Select an existing app or create a new one.
3. From the sidebar select the marketplace icon.
4. Click on the widget card.
5. Preview page select releases tab from sidebar.
6. Click Add Version.
7. Enter a version that is not an existing version.
8. Enter release notes.
9. Upload the widget artifact that you created.

Note: Only an org admin or a user with required permissions can edit the widget.

How to add reviews to a widget?

1. Login to A8Studio.
2. Select an existing app or create a new one.
3. From the sidebar, click the marketplace icon.
4. Click on the widget card.
5. Select write review.
6. Add ratings by clicking stars.
7. Enter a title and an optional review.

Note: Only installed widgets can add reviews.

How to import a widget in a form?

1. Login to A8Studio.
2. Select an existing app or create a new one.
3. From the sidebar, click the Apps icon.
4. Select Apps.
5. Switch to the forms tab.
6. Choose form.
7. Click the import icon in the header.
8. Switch to the installed widgets tab.
9. Click on the import button on the widget card.

Note: Only installed widgets can be imported.

How to delete a widget?

1. Login to A8Studio.
2. Select an existing app or create a new one.
3. From the sidebar select the marketplace icon.
4. Click on the menu icon on the widget card.
5. Select the Delete menu to delete the widget.

Note: Only an org admin or a widget owner and a user with required permissions can delete the widget.