Appearance

Multimedia Selector Apps ​

Multimedia selector apps allow third-party applications to provide custom content sources in the Canvas UI content selector.

App Configuration ​

To create a multimedia selector app, add multimedia_selector to the provide array in your app.json:

json
{
  "name": "my-multimedia-app",
  "display_name": "My Media App",
  "provide": ["multimedia_selector"],
  "module": {
    "ui_app": {
      "enabled": true,
      "entry": "index.html"
    }
  }
}

Communication Protocol ​

Multimedia selector apps communicate with the Canvas UI content selector through a global initialize function.

Initialization ​

Canvas UI will call the initialize function on your app's window object when the iframe loads:

javascript
window.initialize = function(context, callback) {
  // context contains:
  // {
  //   context: 'contentSelector',
  //   appId: 'your-app-id'
  // }

  // Set up your app
  initializeApp(context)

  // Use the callback to send items back to Canvas UI
  window.sendItem = function(item) {
    callback({
      type: 'add-item',
      item: item
    })
  }

  // Or send multiple items
  window.sendItems = function(items) {
    callback({
      type: 'add-items',
      items: items
    })
  }
}

Example Implementation ​

html
<!DOCTYPE html>
<html>
<head>
  <title>My Multimedia Selector</title>
</head>
<body>
  <div id="app">
    <!-- Your content UI here -->
  </div>
  
  <script>
    // Define the initialize function that Canvas UI will call
    window.initialize = function(context, callback) {
      console.log('Multimedia selector initialized with context:', context)
      
      // Store the callback for later use
      window.canvasCallback = callback
      
      // Initialize your app
      loadContent()
      setupUI()
    }
    
    // Function to send selected item to Canvas UI
    function selectItem(item) {
      if (window.canvasCallback) {
        window.canvasCallback({
          type: 'add-item',
          item: {
            id: item.id,
            name: item.name,
            thumbnailUrl: item.thumbnail,
            url: item.url,
            type: item.type, // 'image' or 'video'
            source: 'my-multimedia-app'
          }
        })
      }
    }
    
    // Function to send multiple items
    function selectMultipleItems(items) {
      if (window.canvasCallback) {
        window.canvasCallback({
          type: 'add-items',
          items: items.map(item => ({
            id: item.id,
            name: item.name,
            thumbnailUrl: item.thumbnail,
            url: item.url,
            type: item.type,
            source: 'my-multimedia-app'
          }))
        })
      }
    }
  </script>
</body>
</html>

Item Format ​

Each multimedia item should have the following properties:

  • id (string): Unique identifier for the item
  • name (string): Display name for the item
  • thumbnailUrl (string): URL for the thumbnail image
  • url (string): URL for the full-size media file
  • type (string): Either 'image' or 'video'
  • source (string): Identifier of your app

Best Practices ​

  1. Always check if the callback exists before using it
  2. Handle errors gracefully and provide user feedback
  3. Optimize thumbnail loading for performance
  4. Support both single and batch item selection
  5. Provide clear visual indicators for selected items
  6. Consider implementing search and filtering capabilities