Doc > Editor > EditorConfig.ts

Doc > Editor > EditorConfig.ts

The file src/polygonjs/EditorConfig.ts allows you to configure various aspect of the editor.

If you do not the file present in your project, you can get this file by either:

  • copy it from the code sample below
  • start a project with npx polygonjs-editor, save your scene, and the file will be created.

Here is the list of the elements you can configure:

  1. Set meta tags in the html
  2. Load additional javascript
  3. Add custom HTML to the viewer
  4. Run a post export command

1. Meta tags in the html

When you export a scene, an index.html is exported, along with the necessary javascript files. All the functions below starting with options.api.html.head allow you to set specific elements of that index.html. Of course, you can always edit the file by hand after it is created, but this makes the process easier.

2. Load additional javascript

This has been added for the fxhash integration, which requires a specific function to be loaded while you create your scene.

You can then add any javascript to the editor, using options.api.html.head.addScript

3. Add custom HTML to the viewer

There are situation where it would be very useful to add other html elements to the editor's 3D viewer:

  1. when you need to compare the color of the 3D objects to html elements.
  2. when you need to animate objects based on page scroll
  3. when some html elements events trigger events in the 3D scene, and vice-verse

In those situations, you can use options.api.panel.viewer.setData. This method takes an option arguments, with 3 entries:

  • html (string): the html string
  • viewerId (string): the id of the element inside this html, to mount the viewer onto
  • inShadowRoot (string): if true, the CSS inside the loaded html will not be affected by the editor's CSS, and vice-versa. But you also won't be able to interact with the viewer with javascript. This is good for cases A anb B above, but not for C.

3. Run a post export command

If you would like to export your scene to site builders like Webflow, Wix, Squarespace or Bubble, this post export command will allow you to do that.

Use the method below options.api.export.setPostExportCommand, and you can use as starting point the sample below currently set up to run aws s3 cp on the exported project, and it will upload every file to the s3 bucket of your choice.

And this command could just as well be edited to instead upload to an ftp or a different cloud storage.

Once you've set it up, go to the editor, open the Save Options (from File->Save Options) and you can see a javascript snippet you can use.

import {EditorApiOptions, ConfigureEditor} from 'polygonjs-editor/public/editor/api';
import {ProgressBarTop} from '@polygonjs/polygonjs/src/engine/viewers/progressBars/Top';

export const configureEditor: ConfigureEditor = (options: EditorApiOptions) => {

    // This defines meta tags that will be added to the exported html file
    options.api.html.head.setTitle(options.sceneName);
    options.api.html.head.setDescription('a WebGL experience created with @polygonjs');
    options.api.html.head.setSiteUrl('https://polygonjs.com');
    options.api.html.head.setTwitter('@polygonjs');

    //
    // Add custom javascript to the editor
    //
    options.api.html.head.addScript({
        id: 'my-script',
        content: `alert('this is running my custom script')`,
    });

    //
    // Update the progress bar used in the export
    //
    options.api.html.viewer.setProgressBar(new ProgressBarTop());

    //
    // Add a custom viewer html
    //
        options.api.panel.viewer.setData({
            html: `
    <div id='my-viewer'></div>
    <div id=color-bars>
        <div class='color-bar red'></div>
        <div class='color-bar green'></div>
        <div class='color-bar blue'></div>
    </div>
    <style>
    #my-viewer {
      height: 100%;
    }
    #color-bars {
        position: absolute;
        top: 0px;
        left: 0px;
        width: 100%;
        height: 20px;
    }
    .color-bar {
        width: 32%;
        height: 100%;
        display: inline-block;
    }
    .color-bar.red { background-color: red; }
    .color-bar.green { background-color: green; }
    .color-bar.blue { background-color: blue; }

    </style>`,
        viewerId: 'my-viewer',
        inShadowRoot: true
        });

    options.api.panel.viewer.setData({
        html: `
      <div id="main-container">
      <div id="my-viewer"></div>
      <div id="scroll-container">
        <div class="checkpoint-padding orange">padding 1</div>
        <div id="checkpoint red">#checkpoint1</div>
        <div class="checkpoint-padding green">padding 2</div>
        <div id="checkpoint green">#checkpoint2</div>
        <div class="checkpoint-padding purple">padding 3</div>
        <div id="checkpoint teal">#checkpoint3</div>
        <div class="checkpoint-padding yellow">padding 4</div>
        <div id="checkpoint4 lightgreen">#checkpoint4</div>
        <div class="checkpoint-padding red">padding 5</div>
      </div>
    </div>
    <style>
    #main-container{
      position: relative;
      height: 100%;
      background-color: rgb(0, 255, 0);
    }
    #my-viewer {
      position: absolute;
      width: 100%;
      height: 100%;
    }
    #scroll-container {
      pointer-events: none;
      position: relative;
      height: 100%;
      overflow-y: scroll;
    }
    .checkpoint-padding {
      pointer-events: none;
      height: 120vh;
      color: orange;
      border: 4px solid transparent;
    }
    .checkpoint {
      pointer-events: none;
      height: 120vh;
      color: white;
      border: 4px solid transparent;
    }
    .orange { border-color: orange; }
    .red { border-color: red; }
    .green { border-color: green; }
    .blue { border-color: blue; }
    .purple { border-color: purple; }
    .teal { border-color: teal; }
    .yellow { border-color: yellow; }
    .lightgreen { border-color: lightgreen; }

    </style>
      `,
    viewerId: 'my-viewer',
    inShadowRoot: false
    });

    // setup a post-export command,
    // this is typically used to publish your files online
    options.api.export.setPostExportCommand((args)=>{
        const {exportFolder, sceneName} = args; 
        // This command uses aws cli (https://docs.aws.amazon.com/cli/index.html)
        // to copy the exported files on an s3 bucket and making them publicly available.
        // This is used to easily export for sites builder like: Webflow, Squarespace, Wix, Bubble.
        const awsS3Config = {
            bucket: 'my-s3-bucket',
            region: 'eu-west-2',
            folder: 'my-project/polygonjs/scenes',
            version: '01'
        }
        return {
            // this is the command that is run once the export is completed
            command: `aws s3 cp '${exportFolder}' 's3://${awsS3Config.bucket}/${awsS3Config.folder}/${sceneName}/v${awsS3Config.version}' --acl public-read --recursive`,
            // publicPath is needed when importscript the javascript from another site, so it knows where all other files can be fetched from
            publicPath: `https://${awsS3Config.bucket}.s3.${awsS3Config.region}.amazonaws.com/${awsS3Config.folder}/${sceneName}/v${awsS3Config.version}/` 
        }
    });
};
Is this doc helpful/not helpful? Is there any information you would like that is not available? Don't hesitate to get in touch with any question or feedback, either by email, on Discord or the forum.