Start typing to search...
DocsTutorialsReference
Back to withkoji.com
Docs
Enabling customizations
Building custom VCCs
Search

Building your first custom VCC

Visual Customization Controls (VCCs) enable users to quickly edit elements of your application on Koji. The Koji platform includes VCCs for standard elements, such as images, text, and sounds. In addition, you can build custom VCCs to provide new types of customizations that match closely with the application you are developing. For example, some Koji templates provide tile map editors, sound enhancers, or custom avatar creators to enhance the interactivity for remixers.

In this tutorial, you will build and publish a custom VCC that recreates the standard text VCC on Koji. After completing the tutorial, you will be able to use your custom VCC interchangeably with a text VCC.

Prerequisites

  • Familiarity with web development. React and ES6 basics are a plus.

  • Familiarity with the Koji editor and remix process. For an overview, go through the Koji quick-start tutorial.

Setting up the consumer application

To test and use your custom VCC, you need a Koji application to act as the "consumer" of it.

  1. Remix the following scaffold:

    https://withkoji.com/~seane/simple-react-scaffold

  2. After the editor has loaded, rename the project. For example: Custom VCC Consumer.

  3. In VCC Explorer, open the Strings file.

    This file contains one option for Page Title, which uses a text VCC. You will replace this text VCC with custom VCC that you create in this tutorial.

Setting up the custom VCC application

Custom VCCs are also applications on Koji. You can create them in the same way that you create any application or game — by remixing a scaffold.

  1. Remix the following scaffold:

    https://withkoji.com/~seane/react-project-no-vccs

  2. After the editor has loaded, rename the project. For example: My Custom Text VCC.

Adding the custom-vcc-sdk package

The koji-custom-vcc-sdk package enables you to extend Koji applications with custom VCCs.

  1. At the bottom of the editor, click New Tab to open a new terminal tab.

  2. Navigate to the frontend folder: cd frontend.

  3. Install the package.

    npm install --save @withkoji/custom-vcc-sdk

  4. Close the terminal tab.

    exit

  5. In the frontend termimal tab, cancel the running process, and then restart it to reflect the change.

    npm start

  6. To collapse the terminal pane, click the down arrow in the upper right.

Adding a text input and state management

The VCC must provide an input to accept a value from the user and a way to manage the state of the input value.

  1. Open /frontend/common/App.js from the file browser.

  2. In the App class, add a state property to store the value.

    class App extends React.Component {
  state = { value: '' };
  ...}

  3. Replace the contents of the Container component.

    <Container>
  <input
    onChange={(e) => {
      this.setState({ value: e.currentTarget.value });
    }}
    value={this.state.value}
  />
</Container>

  4. Save the file and refresh the live preview.

    You should see a text input in the preview window.

Importing the VCC package and initializing the custom VCC

Next, use the koji-custom-vcc-sdk package you installed earlier to initialize the custom VCC and register it, so that the consumer knows it’s ready to use.

  1. At the top of the App.js file, import the package.

    import CustomVcc from '@withkoji/custom-vcc-sdk';

  2. In the App class, initialize the custom VCC.

    customVcc = new CustomVcc();

  3. Add a componentDidMount method and register the VCC.

    componentDidMount() {
  this.customVcc.register('300','300');
}

Testing the custom VCC

To save development time, Koji provides an easy way to test a custom VCC before it is published.

  1. In your custom VCC project, click the remote staging button Remote staging button in the preview pane to open your template in a new browser tab.

  2. Copy the URL from the address bar of the tab.

  3. Open your consumer project.

  4. In your consumer project, open the Strings customization file, and click Code to view the raw JSON.

  5. For the title field, change the type to match this format, using the URL you just copied as YOURURL:

    "type": "custom<YOURURL>"

  6. Save the file, and return to the Visual view of the customization file.

    You should see your custom VCC.

Connecting the custom VCC to the consumer

If you type in your custom VCC in the consumer application, you will see that nothing happens yet. To support the dynamic customization updates of a Koji template, the custom VCC must be able to read and update the values in the JSON file of the consumer application.

You can use methods exposed by the custom-sdk-vcc package to get the initial value from the JSON file and then to write a new value to the file when the user changes it in the VCC.

Getting the value from the consumer

In your custom VCC, use the onUpdate method to get the latest value from the JSON file in the consumer application.

  1. In the App.js file of your custom VCC application, add the following code to the componentDidMount method, after the register call:

    this.customVcc.onUpdate(({ value }) => {
  this.setState({ value });
});

    The componentDidMount method should now look like this example:

    componentDidMount() {
  this.customVcc.register('300', '300');

  this.customVcc.onUpdate(({ value }) => {
    this.setState({ value });
  });
}

    This code automatically updates the state of the VCC component when the value in the consumer application changes.

  2. Save the file, and return to your consumer application. Switch to the Code view, and then back to the Visual view to trigger a reload of your custom VCC.

    You should now see the correct value in the input.

Setting a new value using the custom VCC

In your custom VCC, use the change and save methods to send changes from the custom VCC to the consumer application.

  1. In the App.js file of your custom VCC application, update the onChange function for the input:

    <input
  onChange={(e) => {
    this.customVcc.change(e.currentTarget.value);
    this.customVcc.save();
  }}
  value={this.state.value}
/>

    This code updates the value and triggers a save of the JSON file.

  2. Save the file, and return to your consumer application. Switch to the Code view, and then back to the Visual view to trigger a reload of your custom VCC.

    You should now be able to update the title of the application using your own custom VCC.

Publishing your custom VCC

The staging URL makes it easy to test a custom VCC while it is under development. However, it is temporary and changes each time you open a new instance of the project. Instead, you can publish your custom VCC so that you can use it in other projects and share it with other developers.

  1. In the left pane, click Publish Now. Give your VCC a descriptive name, and add a thumbnail if you would like.

    The name and thumbnail make it easier for other developers to find your custom VCC and understand what it does. For a VCC, a custom thumbnail might be a better representation of the functionality than the automatically generated screenshot.

  2. Click Publish New Version.

  3. When the publishing process is completed, click the link to open your live template.

  4. Go to Manage this Koji > Open Creator Dashboard > Custom Domains.

  5. In the top right, click New.

  6. For the type of custom domain, select Subdomain, and then click Next.

  7. For the root domain, select koji-vccs.com.

  8. In Domain, enter a unique name for your VCC. For example, myname-custom-text-vcc.

    You will use this name to implement your custom VCC in consumer applications.

  9. Click Save.

Using a published custom VCC

After your custom VCC has been published, you can use it by replacing the type in your VCC with the domain name you entered in the last step.

"type": "custom<YOURDOMAINNAME>"

For example:

"type": "custom<myname-custom-text-vcc>"

Refining your custom VCC

You can refine the custom VCC by styling it to look more like a standard text VCC. In this example, we’ll define new styling and use additional information from the consumer application to provide context to our custom VCC input.

  1. To be able to test your work in progress, open your consumer application and switch back to the staging URL of your custom VCC application.

  2. In the App.js file of your custom VCC application, remove the unused styled component (Image).

  3. Replace the Container styled component and add the following new styled components near the top of the file.

    const InputContainer = styled.div`
    display: flex;
    flex-direction: column;
    width: 100%;

    input {
        width: 100%;
        background-color: rgb(255, 255, 255);
        color: rgb(17, 17, 17);
        border-width: 1px;
        border-style: solid;
        border-color: rgba(0, 0, 0, 0.1);
        border-image: initial;
        border-radius: 0px;
        padding: 8px;
        outline: none;
    }

    input:focus {
        outline: none;
        border-width: 1px;
        border-style: solid;
        border-color: rgb(21, 122, 251);
        border-image: initial;
    }

    .description {
        width: 100%;
        opacity: 0.4;
        font-size: 12px;
        line-height: 1;
        padding-top: 4px;
    }
`;

const Container = styled.div`
    background-color: #ffffff;
    color: #000000;
    padding: 16px;
    display: flex;
    align-items: start;
    width: calc(100% - 40px);
`;

const Label = styled.label`
    display: inline-flex;
    flex-direction: column;
    align-items: flex-end;
    padding-right: 16px;

    .name {
        font-size: 14px;
    }

    .variable-name {
        font-size: 10px;
        line-height: 1.5;
        color: rgb(102, 102, 102);
        opacity: 0.9;
        font-family: Menlo, Monaco, "Courier New", monospace;
    }
`;

  4. Update the state assignment to add the following properties.

    state = {
  description: '',
  name: '',
  value: '',
  variableName: '',
};

  5. Update the onUpdate command to set the values of the additional properties with information from the consumer application.

    this.customVcc.onUpdate(({ value, name, variableName, description }) => {
  this.setState({
      description,
      name,
      value,
      variableName,
  });
});

  6. Replace the contents of the Container component with the updated input.

    <Label>
    <div className="name">{this.state.name}</div>
    <div className="variable-name">{this.state.variableName}</div>
</Label>
<InputContainer>
    <input
        onChange={(e) => {
            this.customVcc.change(e.currentTarget.value);
            this.customVcc.save();
        }}
        value={this.state.value}
    />
    <div className="description">{this.state.description}</div>
</InputContainer>

  7. Save the App.js file, return to your consumer application, and reload the VCC.

    You should see an updated VCC that looks just like the standard text VCC.

  8. Publish your changes to update the presentation of your custom VCC.

Wrapping up

You’ve now created a replacement for an existing text VCC and learned the basics of how a custom VCC "talks" to the consumer application.

If you want to create more complex custom VCCs, you can find more information in the Custom VCC package reference.

You can also find existing custom VCCs by searching for "vcc" on https://withkoji.com.