Link Search Menu Expand Document
Metapages

API Reference v0.2.1

Table of contents

  1. MetapageDefinition
  2. Metapage
    1. Metapage#addMetaframe
    2. Metapage#addPipe
    3. Metapage#dispose
    4. Metapage#get
    5. Metapage#iframes
    6. Metapage#metaframeIds
    7. Metapage#metaframes
    8. Metapage#onInputs
    9. Metapage#onOutputs
    10. Metapage#removeAll
    11. Metapage#setInput/setInputs
    12. Metapage events
    13. Metapage.MetaframeClient
    14. Metapage.MetaframeClient#iframe
    15. Metapage.MetaframeClient#dispose
    16. Metapage.MetaframeClient#onInputs
    17. Metapage.MetaframeClient#onOutputs
  3. Metaframe
    1. Metaframe#name
    2. Metaframe#getInput
    3. Metaframe#getInputs
    4. Metaframe#getOutput
    5. Metaframe#getOutputs
    6. Metaframe#onInputs
    7. Metaframe#onInput
    8. Metaframe#setInput
    9. Metaframe#setOutput
    10. Metaframe#setOutput
    11. Metaframe#dispose

MetapageDefinition

The JSON description consists of metaframes and the metaframe inputs.

Example minimal metapage with two metaframes:

graph LR metaframe1 -- "output1 -> input1" --> metaframe2 metaframe2 -- "data-stream" --> metaframe1

Defined by:

{
    "version": "0.2",
    "metaframes": {
      "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.

version: This library hasn’t reached version "1" yet. Backwards compatibility is built into this library from it’s first release, and will be automated as much as possible. This is required to maintain long-term compatibility: metaframes should be useful forever, if that is possible from the content. Users should only need to upgrade for bug fixes, performance improvements, or to access new features, and there should never be cognitive load (no worries) about versioning for library users. Mistakes happen, no process is perfect, but this tool assumes the burden of handling all changes to versions over time.

Metapage

A metapage manages piping metaframe outputs to metaframe inputs.

Ways to initialize a metapage:

  1. Load a metapage.json dynamically and add the metaframes. If no loadCallback is given, metaframe iframes will automatically be added to the document element with the id that matches the metaframe id: 
      Metapage.load(?metapage :<string|object>, ?loadCallback :func): Promise<Metapage>


    metapage: URL to metapage definition, defaults to “metapage.json”, or the metapage JSON object
    loadCallback: optional callback with two arguments (metaframeId, IFrameElement)

  2. Create a metapage from a MetapageDefinition JSON object. No metaframes are yet added to the page: 
      const metapage = Metapage.from(def :MetapageDefinition, ?opts :Options): Metapage
  3. 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.
}

If the URL has the parameter MP_DEBUG then debug logging is enabled: https://domain.org/metapage1?MP_DEBUG

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.

graph LR metaframeSource[pipeInput.metaframe] -- "pipeInput.source -> pipeInput.target" --> targetMetaframe

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#onInputs 

metapage.onInputs(function(inputs) {...}): function():

Callback called on every input update event. Example inputs payload:

{
  "metaframeId1": {
    "inputPipeId1": "value"
  }
}

An unbind function is returned.

The same thing can be called via the event:

metapage.on('inputs', function(inputs) {...}): function():

You can also listen on the metaframe clients directly:

metapage.get(metaframeId).on('inputs', function(inputs) {...}): function():

Metapage#onOutputs 

metapage.onOutputs(function(outputs) {...}): function():

Callback called on every output update event. Example outputs payload:

{
  "metaframeId1": {
    "outputPipeId1": "value"
  }
}

An unbind function is returned.

The same thing can be called via the event:

metapage.on('outputs', function(outputs) {...}): function():

You can also listen on the metaframe clients directly:

metapage.get(metaframeId).on('outputs', function(outputs) {...}): function():

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/setInputs

Set metaframe inputs a variety of ways (there is no difference between setInput/setInputs calls).

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

inputsObject:

{
  "inputPipeName": "some value"
}

metaframeInputsObject:

{
  "metaframeId": {
    "inputPipeName": "some value"
  }
}

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.

You can also just listen to a specific metaframe client:

/**
 * Example update:
 * {
*    "output1": "foobar",
 * }
 */
metapage.get(metaframeId).on('outputs', function(update) {

});

Metapage.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. This object is in the metapage page, managing the metaframe data flow.

Metapage.MetaframeClient#iframe

The concrete metaframe iframe HTML element.

Metapage.MetaframeClient#dispose 

metaframe.dispose()

Removes all event listeners and clears internal objects.

Metapage.MetaframeClient#onInputs 

metapage.get(metaframeId).onInputs(function(inputs) {...}): function():

Callback called on every input update event. Example inputs payload:

{
  "inputPipeId1": "value"
}

An unbind function is returned.

The same thing can be called via the event:

metapage.get(metaframeId).on('inputs', function(inputs) {...}): function():

Metapage.MetaframeClient#onOutputs 

metapage.get(metaframeId).onOutputs(function(outputs) {...}): function():

Callback called on every output update event. Example outputs payload:

{
  "outputPipeId1": "value"
}

An unbind function is returned.

The same thing can be called via the event:

metapage.get(metaframeId).on('outputs', function(outputs) {...}): function():

Metaframe

A metaframe is a website running the metaframe library that adds input+output data pipes to the page.

Initialize a metaframe:

const metaframe = new Metaframe();

Wait until it has registered and established a connection with the parent metapage:

await metaframe.ready

or:

metaframe.ready.then(function(_) {
	//Do something, set inputs/outputs
});

Metaframe#name 

let s :String = metaframe.name;

The id the metapage assigned to this metaframe. Defaults to the key in the metapage definition.

Metaframe#getInput 

let inputValue = metaframe.getInput('inputName')

Metaframe#getInputs 

let inputValues = metaframe.getInputs()

Get a object of input pipe names mapped to values.

Do not modify the returned object! For efficiency purposes this is not a copy.

Metaframe#getOutput 

let output = metaframe.getOutput('outputName')

Metaframe#getOutputs 

let outputs = metaframe.getOutputs()

Do not modify the returned object! For efficiency purposes this is not a copy.

Metaframe#onInputs 

metaframe.onInputs(function(inputs) {...}): function():

Callback called on every input update event. Example inputs payload:

{
  "inputPipeId1": "value"
}

Do not modify the returned object! For efficiency purposes this is not a copy.

An unbind function is returned.

Metaframe#onInput 

metaframe.onInput('inputName', function(value) {...}): function():

The callback will fire with the value of the input pipe on every update.

An unbind function is returned.

Metaframe#setInput 

metaframe.setInput('inputName', value :any)

Metaframe#setOutput 

metaframe.setOutput('outputName', value :any)

This value will be send to all downstream metaframe consumers.

Metaframe#setOutput 

metaframe.setOutputs(values :Object)

values: object mapping output names to values.

These values will be send to all downstream metaframe consumers.

Metaframe#dispose 

metaframe.dispose()

Removes window message listener, event listeners, and nulls potentially large fields.