API Reference v0.1.35

A metapage manages piping metaframe outputs to metaframe inputs.

Ways to initialize a metapage:

1. Create a metapage from a MetapageDefinition JSON object:

     const metapage = Metapage.from(def :MetapageDefinition, ?opts :Options): Metapage
   

2. Create an empty metapage via the constructor. Metaframes and pipes are added manually. This is mostly used for testing or debugging:

     const metapage = new Metapage(?opts :Options): Metapage
   

The optional opts argument defineds some extra options, mostly used for debugging:

interface Options {
  color?: String;  // Color of console.logs, since all iframes and the main page will output logs to the same console
  id?   : String;  //Id, not required, but useful if you have multiple metapages in a single website.
}

MetapageDefinition

The JSON description consists of metaframes and the metaframe inputs.

Example minimal metapage with two metaframes:

Defined by:

{
    "version": "0.1.0",
    "iframes": {
      "metaframe1": {
        "url": "https://metapages.org/metaframes/example00_iframe1/",
        "inputs": [
          {
            "metaframe": "metaframe2",
            "source"   : "output1",
            "target"   : "input1"
          }
        ]
      },
      "metaframe2": {
        "url": "https://metapages.org/metaframes/example00_iframe2/",
        "inputs": [
          {
            "metaframe": "metaframe1",
            "source"   : "data-stream"
          }
        ]
      }
    }
}

The target key of the inputs array element can be omitted if the value is the same as the source value.

Metapage#addMetaframe

metapage.addMetaframe(url :String, ?iframeId :String): MetaframeClient

url: URL to a metaframe website

iframeId: optional

Add a new metaframe using the URL. Optionally provide a (locally unique to the metapage) id. If an id is not provided, one will be generated.

Metapage#addPipe

metapage.addPipe(targetMetaframe :String, pipeInput :PipeInput)

targetMetaframe: metaframeId of the target metaframe

pipeInput: object describing the source metaframe, output pipe name, and input pipe name

{
  "metaframe": "<sourceMetaframeId>",
  "source": "<sourceMetaframePipeName>",
  "target": "<thisMetaframePipeName>",
}

pipeInput.metaframe: source metaframeId

pipeInput.source: source metaframe output pipe name. Can be * or any glob, this will forward all output pipes matching the glob

pipeInput.target: target metaframe input pipe name. If target is omitted, then the input pipe name will be the same as the output pipe name.

Add a new metaframe input pipe, from the source metaframes output source, to the target metaframes target input.

Metapage#dispose

metapage.dispose()

Removes all metaframes, window listeners, event listeners.

Metapage#get

metapage.get(metaframeId :String): MetaframeClient

Get the MetaframeClient for the given id.

Metapage#iframes

metapage.iframes(): Map<String, IFrameElement>

Returns a plain Object with metaframe ids mapped to the underlying metaframe iframes.

Metapage#metaframeIds

metapage.metaframeIds(): Array<String>

Returns an array of metaframe ids.

Metapage#metaframes

metapage.metaframes(): Map<String, MetaframeClient>

Returns a plain Object with metaframe ids mapped to MetaframeClient objects.

Metapage#removeAll

metapage.removeAll()

Removes all metaframes, essentially resetting the metapage. It doesn’t remove window listeners though, for proper disposal call dispose().

Metapage#setInput

metapage.setInput(metaframeId :String, inputPipeId :String, value :any)

Set the pipe input value for the given metaframe. It will get sent to the underlying iframe and metaframe object there.

Metapage events

Metapage event allows you to add hooks to the data flow:

/**
 * Example update:
 * {
 *   "metaframe1": {
 *     "input1": "foobar",
 *     "input2": 3
 *   }
 * }
 */
metapage.on('inputs', function(update) {

});

Listens to changes in the inputs for metaframes. The listener is called on every discrete input update.

/**
 * Example update:
 * {
 *   "metaframe1": {
 *     "output1": "foobar",
 *     "output2": 3
 *   }
 * }
 */
metapage.on('outputs', function(update) {

});

Listens to changes in the outputs for metaframes. The listener is called on every discrete output update.

MetaframeClient

An internal object managing the data flow in and out of the actual metaframe iframe. You shouldn’t need to access this object directly.

MetaframeClient#iframe

The concrete metaframe iframe HTML element.