EpicEditor (alpha 0.0.3)

An Embeddable JavaScript Markdown Editor

EpicEditor is an embeddable JavaScript Markdown editor with some minor Markdown enhancements such as automatic link creation and code fencing.

NOTICE:

We're getting super close to the 0.1.0 beta release! If you're interested in contributing please check out the Contributing Guide. We are currently working on the 0.1.0-build-refactor branch.

This version is a developer preview. We're releasing early so we can get other people's input and pull requests. While it works, there are still bugs and missing features. Use at your own risk.

Why

WYSIWYGs suck and they suck hard. Markdown is quickly becoming the replacement. GitHub, Stackoverflow, and even blogging apps like Posterous support Markdown now. This allows you to generate a Markdown editor with a preview, fullscreen editing, full CSS theming, and offline support with a simple:

var editor = new EpicEditor(element).load();

###How

EpicEditor allows for all kinds of customization. For simple drop-in-and-go support see the quick start right below, otherwise checkout the full API.

####Quick Start EpicEditor is easy to implement simply clone the repo and then it only needs an element to add the editor to and then you call load() when you're ready.

#####Step 1: Clone the repo

$ git clone [email protected]:OscarGodson/EpicEditor

#####Step 2: Load the script

<script src="epiceditor.js"></script>

#####Step 3: Init EpicEditor

var element = document.getElementById('editor-wrapper');
var editor = new EpicEditor(element).load();

####API

API Notes:
The constructor is first (EpicEditor()), but everything after are methods of that constructor. Any parameter inside wrapped in square brackets like load([callback]) below means the parameter optional.

Table of Contents:

EpicEditor()
load()
unload()
options()
get()
open()
import()
rename()
save()
remove()
on()
emit()
removeListener()
preview()
edit()
exportHTML()

#####Constructor

EpicEditor(element)

Creates a new EpicEditor instance. Give it an element you want to insert the editor into

Example:

var editor = new EpicEditor(element);

Note: all the examples below will continue to use this same constructor.

#####Methods

load([callback])

Loads the editor by inserting it into the DOM by creating an <iframe>. Will trigger the load event, or you can use the callback instead

Example:

editor.load();

unload([callback])

Unloads the editor by removing the `<iframe>`, but will keep any options you set and file contents so you can easily call `.load()` again. Will trigger the `unload` event, or you can use the callback instead.

Example:

editor.unload();

options(options)

Lets you set options for the editor. The example below has all the options available currently.

basePath: The base path of the directory containing the /themes, /images, etc. It's epiceditor by default. Don't add a trailing slash!.
file.name: If no file exists with this name a new one will be made, otherwise the existing will be opened.
file.defaultContent: The content to show if no content exists for that file.
themes.editor: The theme for the editor which is a textarea inside of an iframe.
themes.preview: The theme for the previewer which is a div of content inside of an iframe.
focusOnLoad: Will focus on the editor on load. It's false by default.
shortcuts.modifier: The modifying key for shortcuts. It's 18 (the alt key) by default, to reduce default browser shortcut conflicts.
shortcuts.fullscreen: The fullscreen shortcut key. It's 70 (f keycode) by default.
shortcuts.preview: The preview shortcut key. It's 80 (p keycode) by default.
shortcuts.edit: The edit mode shortcut key. It's 79 (o keycode) by default.

Example:

editor.options({
  file:{
    name:'example',
    defaultContent:'Write text in here!'
  },
  themes:{
    editor:'/css/epiceditor/editor-custom.css',
    preview:'/css/epiceditor/preview-custom.css'
  },
  focusOnLoad:true,
  shortcuts: {
    preview: 77 //M
  }
}).load();

get(element)

Will grab an element of the editor for easy DOM manipulation inside of the editor.

'document': Returns the iframe element.
'body': Returns the iframe's inner <body> element.
'editor': Returns the editor which is a <textarea>.
'previewer': Returns the previewer element which is a <div>.
'wrapper': Returns the wrapping <div> containing everything inside the <iframe>.

Example:

someBtn.onclick = function(){
  console.log(ee.get('editor').value); //Would return the editor's content
}

open(filename)

Opens a file into the editor.

Example:

openFileBtn.onclick = function(){
  ee.open('some-file'); //Open a file when the user clicks this button
}

import(filename,[content])

Imports a string of markdown into a file. If the file already exists, it will be overwritten. Useful if you want to inject a bunch of content via AJAX.

Example:

importFileBtn.onclick = function(){
  ee.import('some-file',"#Imported markdown\nFancy, huh?"); //Imports a file when the user clicks this button
}

rename(oldName,newName)

Renames a file.

Example:

renameFileBtn.onclick = function(){
  var newName = prompt('What do you want to rename this file to?');
  ee.rename('old-filename',newName); //Prompts a user and renames a file on button click
}

save()

Manually save a file. EpicEditor will save on keyup by default but if you are inserting content via ajax for example, this is useful.

Example:

saveFileBtn.onclick = function(){
  ee.save();
}

remove(name)

Deletes a file.

Example:

removeFileBtn.onclick = function(){
  ee.remove('some-file');
}

on(event,handler)

Sets up an event handler (callback) for a specified event. For all event types, see the Events section below.

Example:

ee.on('unload',function(){
  console.log('Editor was removed');
});

emit(event)

Sets off an event manually. Like jQuery's `.trigger()`

Example:

ee.emit('unload'); //Would trigger the above handler

removeListener(event,[handler])

Allows you to remove all listeners for an event, or just the specified one.

Example:

ee.removeListener('unload'); //The handler above would no longer fire

preview()

Will put the editor into preview mode.

Example:

previewBtn.onclick = function(){
  ee.preview();
}

edit()

Will put the editor into edit mode.

Example:

editBtn.onclick = function(){
  ee.edit();
}

exportHTML()

Will return the generated HTML from the Markdown that you see in the preview mode. Useful to saving content to a database.

Example:

syncWithServerBtn.onclick = function(){
  var theHTML = ee.exportHTML();
  saveToServerAjaxCall('/save',{data:theHTML},function(){
    console.log('data was saved to a db');
  });
}

Events

load

Fires when the editor is loaded via `.load()`.

unload

Fires when the editor is unloaded via `.unload()`.

preview

Fires when the user clicks the preview button, or when `.preview()` is called.

edit

Fires when the user clicks the edit button, or when `.edit()` is called.

save

Fires when the file is saved automatically by EpicEditor, or when `.save()` is called.

open

Fires when the file is opened on load automatically by EpicEditor, or when `.open()` is called.

####Theming

Theming involves two parts; each are optional. There is an editor and preview theme for each instance of an editor and these themes reside in /themes/editor and /themes/preview. The editor involves just a <textarea> and the #utilbar (the thing with the preview/edit andn fullscreen buttons). The preview is just a <div> with the generated HTML inside. All HTML for each editor is in an <iframe> so there is no need to worry about breaking the page you're embedding this on with similar class names or anything.

The HTML of a generated editor (excluding any content) looks like this:

<div class="epiceditor-wrapper epiceditor-edit-mode">
  <div class="epiceditor-utilbar">
    <img width="16" src="epiceditor/images/preview.png" class="epiceditor-toggle-btn">
    <img width="16" src="epiceditor/images/fullscreen.png" class="epiceditor-fullscreen-btn">
  </div>
  <div class="epiceditor-editor">
    <textarea class="epiceditor-textarea"></textarea>
  </div>
  <div class="epiceditor-preview"></div>
</div>

###Who

Oscar Godson (me!), created EpicEditor with help from Adam Bickford. With many thanks to John Fraser (site is no longer up) for his Showdown.js script and John Gruber for Markdown. Also, Isaac Z. Schlueter for his port of GitHub Flavored Markdown which I forked.

roadlabs / epiceditor Goto Github PK

epiceditor's Introduction

EpicEditor (alpha 0.0.3)

An Embeddable JavaScript Markdown Editor

NOTICE:

Why

EpicEditor(element)

load([callback])

unload([callback])

options(options)

get(element)

open(filename)

import(filename,[content])

rename(oldName,newName)

save()

remove(name)

on(event,handler)

emit(event)

removeListener(event,[handler])

preview()

edit()

exportHTML()

Events

load

unload

preview

edit

save

open

epiceditor's People

Contributors

Stargazers

Watchers

Recommend Projects

Recommend Topics

Recommend Org