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>