Execution Engine #

Codestrates is a code execution and editing framework. Its main concept is the code fragment. Here’s a short description of the most used functionality. See the Codestrates API documentation for more.

Fragments #

The <code-fragment> element is similar to the traditional <script> element in that it can contain textual code in any language. However, the Codestrates platform governs the execution of code fragments. Here’s a simple example of a fragment that is automatically run on page load:

<code-fragment data-type="text/javascript" id="myFragment"
               name="My Code Fragment" auto>
  console.log("Hello, world!");
</code-fragment>

The fragment has the following attributes:

data-type: Specifies the MIME type of the contained code.
id: Its unique id.
name: Its human-readable name.
auto: If this is present it is run on page load.

Here’s an example of an HTML fragment:

<code-fragment data-type="text/html" id="myContent"
              name="My Content" auto>
  <h1>Hello world!</h1>
</code-fragment>

This fragment contains HTML. Since it has an auto attribute it will automatically be transiently rendered to DOM in the page as its immediate sibling in the following form:

<transient class="autoDom">
  <h1>Hello world!</h1>
</transient>

Any change to the text content of the fragment will automatically be re-rendered to the DOM.

No bidirectional binding: Changes to the .autoDom view element are not synchronized back into the HTML fragment. If changes to the view should be persisted, consider creating a DOM element directly. This can be done by selecting “Insert DOM Element” in the context menu in the tree browser of Cauldron.

Fragments as JavaScript Objects #

It is possible to access a fragment as a JavaScript object as follows:

let myFragment = Fragment.one("#myFragment");

Refer to the Fragment API for further reference.

Requiring Code Between Fragments #

It is possible require code from another fragment. Consider the following fragment:

<code-fragment data-type="text/javascript" id="myLib"
  name="My Library" auto>
  exports.myLibraryFunction = () => {
    console.log("You called.");
  }
</code-fragment>

From another fragment you can now require the fragment above:

let myLibrary = await Fragment.one("#myLib").require();
myLibrary.myLibraryFunction()

Note that the require method is async. See the Codestrates API documentation for more.

Note: In Cauldron you can generate the code for requiring another fragment by dragging it into an editor.

Editors #

Editors (Based on Monaco, CodeMirror, or Ace) can be instantiated to edit the code stored in a code fragment. Here’s an example where an editor is instantiated for a fragment and transiently added to the DOM:

let fragment = Fragment.one("#myFragment");
let editor = EditorManager.createEditor(fragment, {
  editor: MonacoEditor,
  theme: 'light',
  mode: 'full'
});
let editorNode = editor[0].html[0];
let container = document.createElement("transient");
container.append(editorNode);
document.body.append(editorNode);

The rendering of, e.g., an HTML fragment is in fact implemented as a read-only editor called a preview. Here’s an example where a preview of an HTML fragment is transiently inserted into the DOM.

let fragment = Fragment.one("#htmlFragment");
let preview = EditorManager.createEditor(fragment, {
  editor: PreviewEditor,
  mode: "full"
});
let previewNode = preview[0].html[0];
let container = document.createElement("transient");
container.append(previewNode);
document.body.append(container);

See Editor API and EditorManager API documentation for more.

Polyglot Language Interoperability #

Codestrates supports fragments of many language types. By default they are not installed in the base codestrate prototype but can be enabled by using the package manager of Cauldron. The package manager can be opened using the “File” menu in Cauldron and selecting “Packages…”. In the “codestrates-repos” repository, additional fragment types such as fragment_markdown or fragment_python can be checked and installed. Once checked, the new fragment types are immediately available in Codestrates.

Example: Use this link to create a copy of a codestrate with examples of polyglot language interoperability.