spck-embed

Spck-Embed

Spck Editor is an embeddable online code editor, optimized for the web and building web projects. This library builds is a wrapper around the iframe messaging interface provided by the editor and allows you to control the editor for your needs.

Use cases for this library include:

• Embedding editable demos in your website
• Creating edtor tools (i.e. minifiers, beautifiers, formatters, source-mapping, etc.)
• Creating interactive tutorials

If you like this project please leave a star. Your support is greatly appreciated.

Getting Started

You have two options to install the library:

1. Install with bower:

bower install spck-embed

2. Install with npm:

npm install spck-embed

3. Load the library directly from the web:

<script src="https://embed.spck.io/embed/spck-embed.min.js"></script>

Usage

1. Create an iframe element:

<!--Vanilla editor, no files, no preview-->
<iframe id="editor" src="https://embed.spck.io/" frameBorder="0" width="600" height="360"></iframe>
<!--Load library-->
<script src="https://embed.spck.io/embed/spck-embed.min.js"></script>

<!--With files, but no preview-->
<iframe id="editor" src="https://embed.spck.io/?files=1" frameBorder="0" width="600" height="360"></iframe>
<!--Load library-->
<script src="https://embed.spck.io/embed/spck-embed.min.js"></script>

<!--With files, and preview-->
<iframe id="editor" src="https://embed.spck.io/?files=1&preview=1" frameBorder="0" width="600" height="360"></iframe>
<!--Load library-->
<script src="https://embed.spck.io/embed/spck-embed.min.js"></script>

2. Connect. You have the following options:

Browser Global

// Connect by passing an HTML id to the iframe
var editor = new SpckEditor('#editor');
// Or by passing an HTML element
var editor = new SpckEditor(document.getElementById('editor'));
// Or with any query selector
var editor = new SpckEditor(document.getElementById('iframe'));

// Connect and handle with a callback
editor.connect(function (connected) {
  // Number of tries it took to connect
  console.log(connected.tries)

  editor.send({
    project: 'Simple Project',  // Project name
    open: 'index.js',  // Open file
    files: [  // Create following files
      {path: 'index.js', text: 'console.log("entry point")'}
    ]
  }, function () {
    // Success
  }, function () {
    // Failure
  })
}, function () {
  // Handle connection failure
  console.log('connection failed')
}, {
  maxTries: 20,  // Maximum number of attempts to wait for iframe to load
  interval: 500  // Interval between attempts
});

// Or handle with a promise
editor.connect()
  .then(() => {
    // Control the editor
    return editor.send({
      project: 'Simple Project',  // Project name
      open: 'index.js',  // Open file
      files: [  // Create following files
        {path: 'index.js', text: 'console.log("entry point")'}
      ]
    })
  })
  .catch(() => console.log('failure'))

// Or handle using async/await
await editor.connect()
// Control the editor
await editor.send({
  project: 'Simple Project',  // Project name
  open: 'index.js',  // Open file
  files: [  // Create following files
    {path: 'index.js', text: 'console.log("entry point")'}
  ]
})

AMD

define(['SpckEditor'] , function (SpckEditor) {
  var editor = new SpckEditor('#editor');
  // Do stuff with editor here
});

CommonJS

var SpckEditor = require('SpckEditor');
var editor = new SpckEditor('#editor');
// Do stuff with editor here

ES2015 Modules (after npm install)

import {SpckEditor} from 'spck-embed';

var editor = new SpckEditor('#editor');
// Do stuff with editor here

API Reference

URL

Certain cosmetic features can be set by the iframe's src url by using query parameters.

URL Parameter	Optional	Description
files	Yes	If present, will display a side menu for file management.
preview	Yes	If present, will display a Run button for previewing code output.
theme	Yes	Changes the editor theme. Options: chrome, xcode, ayu-light, dracula, monokai, ayu-mirage.
project	Yes	The name of the project to create.

Example

<iframe src="https://embed.spck.io/?files=1&preview=1&theme=dracula"></iframe>

constructor

new SpckEditor(element, origin)

Parameter	Optional	Description
element	No	Either a CSS selector string or the iframe HTMLElement to connect to.
origin	Yes	String to specify another domain origin for the editor. (Defaults to https://embed.spck.io)

Methods

connect

connect(opts: {
  maxTries: Number,
  interval: Number
}): Promise

Parameter	Optional	Description
opts.maxTries	Yes	Maximum attempts to establish connection with iframe. (default: 20)
opts.interval	Yes	Time to wait between attempts to connect. (default: 500ms)

send

send(msg: {
  project: String,
  clearProjects: Boolean | [String]
  files: [{path: String, text: String?, url: String?}],
  appendFiles: Boolean,
  open: String,
  editor: {
    mode: String,
    text: String,
    fontSize: String,
    tabSize: Number,
    position: {row: Number, column: Number},
    gutter: Boolean
  }
}): Promise

Parameter	Optional	Description
msg.project	Yes	Specifies the project name, projects are namespaced by domain. The same project name from different domains will not overwrite each other.
msg.clearProjects	Yes	If true, clear all projects in the domain; or if an array of project names, then delete the list of projects.
msg.files	Yes	List of files to create in the project, if url is specified instead of text, the contents will be fetched instead.
msg.appendFiles	Yes	Keep existing project files, append/overwrite the files.
msg.open	Yes	Opens this file in the project.
msg.editor	Yes	Configures the editor window directly.

Example

editor.send({
  files: [
    {
      path: 'src/index.html',
      text: '...'
    }, {
      path: 'src/index.js',
      text: '...'
    }
  ],
  // Keep existing files in the project, append/overwrite new files
  appendFiles: false,
  // Open this file
  open: 'index.js',
  // Create a project
  project: 'ProjectA',
  editor: {
    // Sets the language mode
    mode: 'javascript' // 'typescript, javascript, css, less, scss, html, etc.',
    // Sets the editor current text
    text: '...',
    // Sets the editor font size
    fontSize: '12px',
    // Sets the editor tab size
    tabSize: 2,
    // Show line numbers or not
    gutter: true
  }
})

on

editor.on(handlers: {
  textChange: Function,
  positionChange: Function,
  selectionChange: Function,
  fileOpen: Function,
  projectOpen: Function,
  projectClose: Function,
  blur: Function,
  focus: Function
})

Parameter	Optional	Description
handlers.textChange	Yes	Detect whenever the editor text is changed.
handlers.positionChange	Yes	Detect when the cursor position is changed.
handlers.selectionChange	Yes	Detect when the text selection is changed.
handlers.fileOpen	Yes	Detect when a new file is opened.
handlers.projectOpen	Yes	Detect when a project is opened.
handlers.projectClose	Yes	Detect when a project is closed.
handlers.blur	Yes	Detect when editor blurs focus.
handlers.focus	Yes	Detect when editor focuses.

getMode

getMode(): Promise<String>

getPosition

getPosition(): Promise<{row: Number, coluumn: Number}>

getTabSize

getTabSize(): Promise<Number>

getText

getText(): Promise<String>

getTheme

getTheme(): Promise<String>