WIP
Initially inspired by https://github.com/AlastairTaft/draft-js-editor
scholar-draft
aims at providing customizable and easy-to-use components for building academy-oriented editing apps with react-js
and draft-js
libraries.
scholar-draft
Goals of This module provides two react editor components that pursue the following main goals :
- easily connect draft's editor entities to upstream applicationnal logic in a "one-way binding" manner : in scholar-draft, entities state and components are entirely handled upstream separately from the editor state. An entity's data is called an
asset
in the module's vocabulary - provide callbacks for adding, removing, & editing upstream assets from within the editor's interface
- allow to insert, move and edit footnotes within a draft-js editor, while supporting assets as well
- provide two ways to add an asset to the draft : drag-and-drop, inline selection thanks to an input component
To do so, the module provides two components :
BasicEditor
: editor without footnotes supportEditor
: editor with footnotes support
These components are as "pure" as possible, that is they do not contain their content's state but rather receive it in their props and trigger callbacks when subjected to user's change. For that reason the module also provides a set of utils
functions for manipulating editor's state upstream of the editor (Create/Update/Delete operations on contents' notes, Create/Update/Delete operations on contents' assets, ...). Take a look at the stories
folder for implementation examples.
Features
- upstream-connected entities support
- footnotes management & edition support
- assets drag-and-drop support
- block and inline asset wrappers allowing developpers to provide their own assets components (examples : image preview component, video preview component, reference preview component, ...). These components can be provided as plain previews, or can host user interactions and trigger callbacks to change upstream assets.
- asset choice wrapper allowing developpers to provide their own asset selection component (example : an input field enabling to search in the list of relevant assets, ...)
- markdown shortcuts handling
- customizable medium-like contextual toolbar
- customizable style, through css classes selectors
- keyboard shortcuts (default:
@
for inserting an asset,cmd+^
for inserting a footnote)
Editor API
EditorpropTypes = /** * EDITOR STATE */ // draft-js immutable object representing the main editor state mainEditorState: PropTypesobject // map of immutable objects representing the notes editor state notes: PropTypesobject // array of ids for representing the order of notes notesOrder: PropTypesarray assetRequestPosition: PropTypesobject assetRequestContentId: PropTypesstring assetChoiceProps: PropTypesobject focusedEditorId: PropTypesstring // custom context object that will be passed to downstream entity decoration components customContext: PropTypesobject // list of objects possibly embeddable inside the editor assets: PropTypesobject /** * CALLBACKS */ onEditorChange: PropTypesfunc onNoteAdd: PropTypesfunc onAssetChange: PropTypesfunc onAssetRequest: PropTypesfunc onAssetRequestCancel: PropTypesfunc onAssetChoice: PropTypesfunc onAssetClick: PropTypesfunc onAssetMouseOver: PropTypesfunc onAssetMouseOut: PropTypesfunc onAssetBlur: PropTypesfunc handlePastedText: PropTypesfunc onNotePointerMouseOver: PropTypesfunc onNotePointerMouseOut: PropTypesfunc onNotePointerMouseClick: PropTypesfunc onNoteDelete: PropTypesfunc onDrop: PropTypesfunc onDragOver: PropTypesfunc onClick: PropTypesfunc onBlur: PropTypesfunc /** * CUSTOMIZATION */ // (translated) messages to provide to the editor for displaying messages: PropTypesshape addNote: PropTypesstring summonAsset: PropTypesstring cancel: PropTypesstring // custom class for the editor editorClass: PropTypesstring // editor placeholder text editorPlaceholder: PropTypesstring inlineAssetComponents: PropTypesobject blockAssetComponents: PropTypesobject AssetChoiceComponent: PropTypesfunc NotePointerComponent: PropTypesfunc AssetButtonComponent: PropTypesfunc NoteButtonComponent: PropTypesfunc NoteLayout: PropTypesfunc inlineEntities: PropTypesarray iconMap: PropTypesobject inlineButtons: PropTypesarray NoteContainerComponent: PropTypesfunc ElementLayoutComponent: PropTypesfunc // rendering mode to provide to entity decoration components renderingMode: PropTypesstring keyBindingFn: PropTypesfunc // custom inline styles editorStyles: PropTypesobject
Utils API
insertAssetInEditor(editorState, asset, selection)
returns new editorState
insertNoteInEditor(editorState, noteId, selection)
returns new editorState
deleteAssetFromEditor(editorState, id, callback)
returns new editorState
deleteNoteFromEditor(editorState, id, callback)
returns new editorState
updateNotesFromEditor(editorState, notes)
returns updated notes map
updateAssetsFromEditor(editorState, assets)
returns new assets map
getUnusedAssets(editorState, assets)
returns asset map
getUsedAssets(editorState, assets)
returns asset map
insertFragment(editorState, fragment)