Skip to content

5 Examples

Jump to bottom
Lauri Koutaniemi edited this page Nov 8, 2023 · 10 revisions

Introduction

Use these examples to get started with the integration and understanding the logic behind commands and messages.

Integration

Integrating Sumo custom is very easy. See Integration chapter for more info.

Basic setup

Use this template for adding support for commands and messages.

<!DOCTYPE html>
<html lang="en">

  <head>

    <meta charset="utf-8" />
    <title>Sumo Custom Example</title>
    <script src="https://cdn.sumopaint.com/assets/postmessage.js"></script>

    <style>
    * { margin:0; padding:0; border:0; }
    #custom { position: absolute; top: 0px; bottom:0px; left:0px; right:0px; }
    #sumo { width:100%; height:100%; }
    </style>

  </head>

  <body>

    <div id="custom">
      <iframe id="sumo" src="https://custom.sumo.app?target=parent&app=custom"></iframe>
    </div>

    <script>

      // get messages from sumo
      function message(m,d={}) {
        // show layers panel when the app is loaded
        if(m==='app-ready') command('panel-layers')
      }

      // send commands to sumo
      function command(c) {
        // send command to sumo using post message method
        document.getElementById('sumo').contentWindow.postMessage({'command': c }, "*");
      }

    </script>

  </body>

</html>

All inclusive

Use this template for custom header and own event listeners for commands and messages.

<!DOCTYPE html>
<html lang="en">

  <head>

    <meta charset="utf-8" />
    <title>Sumo Custom Example</title>
    <meta name="description" content="Example how to use Sumo Custom" />
    <link rel="icon" type="image/png" href="https://cdn.sumo.app/images/icon.png"/>
    <!--<script src="https://cdn.sumopaint.com/assets/postmessage.js"></script>-->

    <style>
    * { margin:0; padding:0; border:0; }
    button { padding: 5px; margin: 5px; }
    #header { display:flex; align-items:center; margin:5px; }
    #custom { position: absolute; top: 45px; bottom:0px; left:0px; right:0px; }
    #sumo { width:100%; height:100%; }
    </style>

  </head>

  <body>

    <div id="header">
      <img src="https://cdn.sumo.app/images/icon.png" width="30">
      <button onclick="command('layer-add')">Add Layer</button>
      <button onclick="command('panel-layers')">Show Layers</button>
      <button onclick="command('tool-gradient')">Gradient Tool</button>
      <button onclick="command('image-canvas:1024:512')">Resize Canvas</button>
      <button onclick="command('app-style:apisave:background:black')">Style Save button</button>
    </div>

    <div id="custom">
      <iframe id="sumo" src="https://custom.sumo.app?target=parent&mode=dev"></iframe>
    </div>

    <script>

      // next 20 lines can be removed if you don't use messages, only commands
      // you can also remove the next 12 lines if you uncomment script tag above

      // add event listener for listening messages from sumo custom
      if(window.addEventListener) window.addEventListener("message", onMessage, false);
      else if (window.attachEvent) window.attachEvent("onmessage", onMessage);

      // message receiver for sumo custom, will pass it to message function
      function onMessage(e) {
        if (typeof(window[e.data.f]) == "function") {
          if(e.data.d) window[e.data.f].call(null, e.data.m, e.data.d);
          else window[e.data.f].call(null, e.data.m);
        }
      }

      // get messages from sumo
      function message(m,d={}) {
        if(m==='app-ready') console.log('Sumo Custom is ready')
        else console.log(m,d);
      }

      // send commands to sumo
      function command(c) {
        document.getElementById('sumo').contentWindow.postMessage({'command': c }, "*");
      }

    </script>

  </body>

</html>

As you can see, you can add any Query Parameters to the iframe url.

Sending and receiving events in Sumo

Here's a quick summary how Sumo handles the messages and commands.

Sumo Custom is full of window.parent.postMessage calls, where it sends the message and the data to parent document.

Here is an example what is sends when the new layer is added: (it will also send the modified layers array with all the layer objects.

window.parent.postMessage({ 'f': 'message', 'm': 'layer-add', 'd': { layers:[{...},{...}] } }, '*')

You can find the complete list of messages from Messages page.

Sumo custom is also listening the messages received from your parent document and performing actions when it receives them:

window.addEventListener('message', (e) => {
  if(e.data.command) {
    switch (e.data.command) {
      case 'layer-add': addNewLayer(); break
    }
  }
})

In some cases it will get the command parameters and send it to the method. Command "layer-add" doesn't have any parameters. It will always just add a new layer on top of the layer stack, that you can select, move or modify with other commands. But for ex. "layer-add-color:hex" has the hex color as parameter, so you can add a new layer with red color using "layer-add-color:ff0000" command. Read more from Commands page.

Clone this wiki locally