mirror of
https://github.com/Hopiu/django-markdownx.git
synced 2026-03-16 21:40:24 +00:00
258 lines
7.5 KiB
ReStructuredText
258 lines
7.5 KiB
ReStructuredText
MarkdownX
|
|
=========
|
|
|
|
Frontend (JavaScript) management of Django-MarkdownX package.
|
|
|
|
Written in JavaScript ECMA 2016, trans-compiled to ECMA 5 (2011).
|
|
|
|
:Requirements:
|
|
- Modern browser with support for HTML5 and ECMA 2011+ (IE 10+). Older browsers would work but some features may be
|
|
missing.
|
|
- TypeScript 2+
|
|
|
|
JavaScript ECMA 5 files formatted as ``.js`` or ``.min.js`` are trans-compiled files. Please do not modify such files as
|
|
all changes will be lost. To contribute, please edit ``static-src/markdownx/js/markdownx.ts``. See
|
|
:doc:`contributions<../../contribution>` in the documentations for additional instructions.
|
|
|
|
.. note:: Typescript type definitions of this module are defined in ``static-src/markdownx/js/types.ts``.
|
|
|
|
----
|
|
|
|
.. js:data:: GeneralEventHandlers
|
|
|
|
:JSON Object: General (document level) event handlers.
|
|
|
|
.. js:function:: inhibitDefault(event)
|
|
|
|
Routine tasks for event handlers (e.g. default preventions).
|
|
|
|
:param Event|KeyboardEvent event: The events to be inhibited.
|
|
:returns: event
|
|
:return type: Event
|
|
|
|
.. js:function:: onDragEnter (event)
|
|
|
|
Upon enter (when a file, e.g. an image, is dragged into the browser),
|
|
the defualt events are inhibited, and the drop event is set as `copy`.
|
|
|
|
:param DragEvent event: Drag event.
|
|
:returns: Inhibited drag event with `copy` added to the drop event.
|
|
:return type: Event
|
|
|
|
|
|
.. js:data:: keyboardEvents
|
|
|
|
:JSON Object: Keyboard events and their handlers.
|
|
|
|
.. js:data:: keys
|
|
|
|
:JSON Object: Custom hotkeys.
|
|
|
|
.. js:attribute:: TAB
|
|
|
|
- (*string*) - represents: ``Tab``
|
|
|
|
.. js:attribute:: DUPLICATE
|
|
|
|
- (*string*) - represents: ``d``
|
|
|
|
.. js:attribute:: UNINDENT
|
|
|
|
- (*string*) - represents: ``[``
|
|
|
|
.. js:attribute:: INDENT
|
|
|
|
- (*string*) - represents: ``]``
|
|
|
|
.. js:function:: hub(event)
|
|
|
|
Mapping of hotkeys from keyboard events to their corresponding functions.
|
|
|
|
:param KeyboardEvent event: Keyboard event to be handled.
|
|
:return type: Function | Boolean
|
|
|
|
.. js:data:: Handlers
|
|
|
|
Handler functions, as mapped by :js:func:`hub`.
|
|
|
|
:JSON Object: Hotkey response functions.
|
|
|
|
.. note::
|
|
Properties receive a single argument ``properties``, which is an instance of :js:data:`properties`. See the
|
|
``markdownx`` class for additional details.
|
|
|
|
.. js:function:: applyTab(properties)
|
|
|
|
Smart application of tab indentations under various conditions.
|
|
|
|
:param JSON properties: See object descriptions for details.
|
|
:return type: string
|
|
|
|
.. js:function:: removeTab(properties)
|
|
|
|
Smart removal of tab indentations.
|
|
|
|
:param JSON properties: See object descriptions for details.
|
|
:return type: string
|
|
|
|
.. js:function:: _multiLineIndentation(properties)
|
|
|
|
**private**
|
|
|
|
Handles multi line indentations.
|
|
|
|
:param JSON properties: See object descriptions for details.
|
|
:return type: string
|
|
|
|
.. js:function:: applyIndentation(properties)
|
|
|
|
Smart application of indentation at the beginning of the line.
|
|
|
|
:param JSON properties: See object descriptions for details.
|
|
:return type: string
|
|
|
|
.. js:function:: removeIndentation(properties)
|
|
|
|
Smart removal of indentation from the beginning of the line.
|
|
|
|
:param JSON properties: See object descriptions for details.
|
|
:return type: string
|
|
|
|
.. js:function:: applyDuplication(properties)
|
|
|
|
Duplication of the current or selected lines.
|
|
|
|
:param JSON properties: See object descriptions for details.
|
|
:return type: string
|
|
|
|
|
|
.. js:function:: getHeight(element)
|
|
|
|
Returns either the height of an element as defined in the ``style`` attribute or CSS or its browser-computed height.
|
|
|
|
:param element HTMLElement: The element whose height is to be determined.
|
|
:returns: Height of the element.
|
|
:return type: number
|
|
|
|
|
|
.. js:function:: updateHeight(element)
|
|
|
|
Updates the height of an element based on its scroll height.
|
|
|
|
:param HTMLTextAreaElement editor: Editor element whose height is to be updated.
|
|
:return type: HTMLTextAreaElement
|
|
|
|
|
|
.. js:class:: MarkdownX(editor, preview)
|
|
|
|
MarkdownX initializer.
|
|
|
|
:example:
|
|
.. code-block:: javascript
|
|
|
|
>>> let parent = document.getElementsByClassName('markdownx'),
|
|
... editor = parent.querySelector('.MyMarkdownEditor'),
|
|
... preview = parent.querySelector('.MyMarkdownPreview');
|
|
|
|
>>> let mdx = new MarkdownX(parent, editor, preview)
|
|
|
|
:param HTMLElement parent: Markdown editor element.
|
|
:param HTMLTextAreaElement editor: Markdown editor element.
|
|
:param HTMLElement preview: Markdown preview element.
|
|
|
|
.. js:data:: properties
|
|
|
|
:JSON Object: Class variables.
|
|
|
|
.. js:attribute:: editor
|
|
|
|
- (*HTMLTextAreaElement*) - Instance editor.
|
|
|
|
.. js:attribute:: preview
|
|
|
|
- (*HMTLElement*) - Instance preview.
|
|
|
|
.. js:attribute:: parent
|
|
|
|
- (*HMTLElement*) - Instance parent.
|
|
|
|
.. js:attribute:: _latency
|
|
|
|
**private**
|
|
|
|
- (*number* | *null*) - Private property; timeout settings.
|
|
|
|
.. js:attribute:: _editorIsResizable
|
|
|
|
**private**
|
|
|
|
- (*Boolean*) - Private property; ``true`` if instance editor is resizable, otherwise ``false``.
|
|
|
|
.. js:function:: _markdownify()
|
|
|
|
**private**
|
|
|
|
Settings for ``timeout``.
|
|
|
|
.. js:function:: _routineEventResponse(event)
|
|
|
|
**private**
|
|
|
|
Routine tasks for event handlers (e.g. default preventions).
|
|
|
|
:param Event event: Event to be handled.
|
|
|
|
.. js:function:: getEditorHeight(editor)
|
|
|
|
:param HTMLTextAreaElement editor: Markdown editor element.
|
|
:returns: The editor's height in pixels; e.g. ``"150px"``.
|
|
:return type: string
|
|
|
|
.. js:function:: inputChanged()
|
|
|
|
Event handlers in response to alterations in the instance editor.
|
|
|
|
:param Event event: Event to be handled.
|
|
|
|
.. js:function:: onDragEnter(event)
|
|
|
|
Event handler for :guilabel:`dragEnter` events.
|
|
|
|
:param Event event: Event to be handled.
|
|
|
|
.. js:function:: onDragLeave(event)
|
|
|
|
Event handler for :guilabel:`dragLeave` events.
|
|
|
|
:param Event event: Event to be handled.
|
|
|
|
.. js:function:: onDrop(event)
|
|
|
|
Event handler for :guilabel:`drop` events (in drag and drops).
|
|
|
|
:param Event event: Event to be handled.
|
|
|
|
.. js:function:: onKeyDown(event)
|
|
|
|
Event handler for :guilabel:`keyDown` events as registered in the instance editor.
|
|
|
|
:param Event event: Event to be handled.
|
|
:returns: ``null`` if the key pressed is *Tab* (ASCII #9) else ``false``.
|
|
:return type: boolean | null
|
|
|
|
.. js:function:: sendFile(file)
|
|
|
|
Uploading the ``file`` onto the server through an AJAX request.
|
|
|
|
:param File file: File to be uploaded.
|
|
|
|
.. js:function:: getMarkdown()
|
|
|
|
Uploading the markdown text from :attr:`properties.editor` onto the server through an AJAX request, and upon
|
|
receiving the HTML encoded text in response, the response will be displayed in :attr:`properties.preview`.
|
|
|
|
.. js:function:: insertImage(textToInsert)
|
|
|
|
Inserts markdown encoded image URL into :attr:`properties.editor` where the cursor is located.
|
|
|
|
:param string textToInsert: Markdown text (with path to the image) to be inserted into the editor.
|