Getting started
To get started with Copenhagen, add copenhagen.0-1-4.min.css
and copenhagen.0-1-4.min.js to your web project.
You can find them on GitHub.
Then import them to your webpage by adding the following lines in the
<head> tag of your webpage:
<link rel="stylesheet" href="./compiled/copenhagen.0-1-4.min.css">
<script src="./compiled/copenhagen.0-1-4.min.js"></script>
You can then instantiate a new Editor adding the following JavaScript
within a <script> tag:
// Use DOMContentLoaded or whatever instantiation code you'd like,
// just make sure the page is ready...
window.addEventListener('DOMContentLoaded', function () {
// instantiated CPHEditor instance with config
var editor = new Copenhagen.Editor({language: 'javascript'});
// open, but do not auto-focus the editor
editor.open(this.selector('.some-selector'), false);
// set a value
editor.setValue('var message = `hello world`;');
});
Alternatively, you can automatically convert all elements matching a
specific selector. This will automatically pass in config values
via data-* attributes on the HTML tag.
<div class="editor" data-language="html" data-maxrows="20">
// some code
</div>
window.addEventListener('DOMContentLoaded', function () {
var editors = Copenhagen.initSelectorAll('.editor');
});
Constructor
Creates a Copenhagen editor instance with a supplied config when using
new Copenhagen.editor(cfg).
objectcfg Configuration settings
stringlanguage
Sets the language of the editor. Currently supported languages are
"javascript", "json", "markdown",
"html", "css" and "text".
booleanreadonly
Sets readonly status on the editor. Defaults to false.
booleanhidden
Hides the editor. Defaults to false.
booleandisabled
Disables the editor. Defaults to false.
booleanmaximized
Sets whether or not the editor takes up the entirety of the relative parent or not.
Defaults to false.
integerrows
Sets the minimum number of rows of the editor. Defaults to 1.
integermaxrows
Sets the maximum number of rows of the editor. Defaults to 30
and can not be set above 30. Use maximized if
you need a larger editor.
booleantabout
Sets whether or not you can "tab out" of the editor. If set to true,
the tab key will not be usable to insert tabs. Defaults to false.
booleannolines
Hides line numbers when enabled. Defaults to false.
Methods
Create a custom autocompletion detector to add your own autocomplete box.
The enableFn takes the form function (editor, selection, inString, inComment)
and can return any sort of result you want. When rendered, if enableFn()
returns a truthy value, the editor will dispatch an autocomplete event
with the parameters (editor, name, result, cursorRectangle). You can
use this to build your own autcompletion element.
stringname The name of the autocompletion handler
functionenableFn The autocompletion enablement handler
Adds a hotkey handler with the format function (value, cursors) { ... }
If a hotkey is added, the default behavior will be prevented.
stringkey Hotkey format in order ctrl+alt+shift+key
functionfn Hotkey handler
Shakes the editor back-and-forth, indicating no action can be taken.
Blurs the editor (removes focus)
Tells us whether or not the editor can currently return typeahead or
other suggestions.
Clears all user action history. This *does not* re-render the editor.
Clears metadata on the editor, if needed. This will dispatch a metadata event
and metadata/${key}` event that can be listener to via editor.on('metadata', fn).
stringkey The metadata key to clear
Disables the editor. The user can not make further changes or scroll the
editor.
Emulate a user action. Use this when emulation mode is enabled.
Will throw an error if not in emulation mode.
Specific user actions are available on the CPHCursor
object, prefixed with the word calculate.
stringname The name of the user action to dispatch
Open the find and replace dialog for the editor.
stringvalue The value to search for
Finds the complement of a character at a specific index based on the
language dictionary.
e.g. finds } when { is located at the specified index.
stringvalue The value to search through
integern The character index to check
arrayResult in format [leftIndex, rightIndex]
Sets focus to the editor
booleanselectAll Whether or not to select entire contents of the editor
Retrieves the active formatter function based on the active language
Retrieve the currently active language for the editor
Retrieves the currently active language dictionary for the editor.
Languages are added via CPHEditor#languages.
Retrieves the formatter function for a language or return the text
formatter if it is not found.
stringlanguage The language of the formatter
Retrieves metadata from the editor, if needed
stringkey The metadata key to retrieve
stringdefaultValue The default value to return if not set
Retrieves the current value of the editor
string
Navigate the user action history, forward or backward.
integeramount
Determine whether the editor is focused, returns true if so
boolean
Hide the editor (set display = none)
Determines whether a specific character index is within a block or not
based on the language dictionary.
integern The character index to check
boolean
Determines whether a specific character index is within a comment or not
based on the language dictionary.
integern The character index to check
boolean
Determines whether a specific character index is within a string or not
based on the language dictionary.
integern The character index to check
boolean
Retrieve the current read-only status of the editor.
Opens the editor instance. Typically used after an editor is created manually
via editor = new Copenhagen.Editor().
HTMLElementel The element to open the editor on
booleanfocus Whether or not to focus the editor. Defaults to true.
booleanreplaceText Whether or not to use the existing text inside of the HTMLElement to populate the editor. Defaults to false.
Removes an autocompletion detector
stringname
Removes a hotkey handler
stringkey Hotkey format in order ctrl+alt+shift+key
Renders the editor on the next available frame, if applicable.
Multiple calls to .render will not negatively impact performance, extra
calls are debounced.
stringvalue The value to render within the editor, should typically be editor.value or editor.getValue()
booleanforceRender Force an update on the next frame
Dispatches a "save" event and creates a history entry if the user has performed an action.
You can listen to this action via editor.on('save', function (editor, value) { ... })
stringvalue The value to set in the editor
string
Scrolls the editor by a visible "page" amount based on the height of the
editor. This *will* trigger a re-render.
stringdirection Either "up" or "down"
Scrolls to the currently selected text in the editor. This *will* trigger
a re-render.
Scrolls to a specific line index in the editor. This *will* trigger a
re-render.
integerindex The line index to scroll to
Scrolls the editor to a specific (x, y) coordinate from the top left of
the editor. This *will* trigger a re-render.
integerx the x coordinate (from left)
integery the y coordinate (from top)
Selects text in the editor at a specific start and end index.
This *will* trigger a re-render.
integerstart The start index to select
integerend The end index to select
Sets emulation mode. Turning this on will cause the editor to always appear "in focus".
It will also allow you to use "emulateUserAction", which can dispatch a user action
even in "readonly" mode.
booleanvalue Enable or disable emulation, will default to true
boolean
Sets an error state in the editor. This *will* trigger a re-render.
integerlineIndex The line index the error is on, 0-indexed
integercolumn The column index the error is on, 0-indexed
object
Sets a custom formatter for a language. Custom formatter functions take the
form function (line, inString, inComment) { ... } where inString and
inComment are determined by the language dictionary.
stringlanguage The language the formatter applies to
functionfn The formatter function
Sets the language for the editor. This *does not* automatically re-render the editor.
stringlanguage The language to set, e.g. javascript. Must be supported in the languages dictionary
stringThe active language
Set maximized mode on the editor so that it takes up all of its relative parent's
height. This *does not* trigger a re-render. You must do that manually.
booleanvalue
Sets metadata on the editor, if needed. This will dispatch a metadata event
and metadata/${key} event that can be listener to via editor.on('metadata', fn).
stringkey The metadata key to set
stringvalue The metadata value to set
Set read-only mode on the editor. This *does not* trigger a re-render. You
must do that manually.
booleanvalue if undefined, will set true
Sets the value of the editor. If a user has already performed an action,
this creates a history entry. This *will* trigger a re-render.
stringvalue The value to set in the editor
string
Show the editor (make it visible)
Perform a user action. Specific user actions are available on the CPHCursor
object, prefixed with the word calculate.
stringname The name of the user action to dispatch