- Notifications
You must be signed in to change notification settings - Fork93
Extensibly serialize & deserialize Draft.js ContentState with HTML.
License
HubSpot/draft-convert
Folders and files
| Name | Name | Last commit message | Last commit date | |
|---|---|---|---|---|
Repository files navigation
Extensibly serialize & deserializeDraft.js content with HTML
Seedraft-extend for more on how to use draft-convert with plugins
npm install draft-convert --save oryarn add draft-convert
Jump to:
Extensibly serialize Draft.jsContentState to HTML.
Basic usage:
consthtml=convertToHTML(editorState.getCurrentContent());
Advanced usage:
// convert to HTML with blue text, paragraphs, and linksconsthtml=convertToHTML({styleToHTML:(style)=>{if(style==='BOLD'){return<spanstyle={{color:'blue'}}/>;}},blockToHTML:(block)=>{if(block.type==='PARAGRAPH'){return<p/>;}},entityToHTML:(entity,originalText)=>{if(entity.type==='LINK'){return<ahref={entity.data.url}>{originalText}</a>;}returnoriginalText;}})(editorState.getCurrentContent());// convert content state to HTML with functionality defined in the plugins appliedconsthtml=compose(FirstPlugin,SecondPlugin,ThirdPlugin)(convertToHTML)(editorState.getCurrentContent());
styleToHTML,blockToHtml, andentityToHTML are functions that take Draft content data and may return aReactElement or an object of shape{start, end} defining strings for the beginning and end tags of the style, block, or entity.entityToHTML may return either a string with or without HTML if the use case demands it.blockToHTML also may return an optionalempty property to handle alternative behavior for empty blocks. To use this along with aReactElement return value an object of shape{element: ReactElement, empty: ReactElement} may be returned. If no additional functionality is necessaryconvertToHTML can be invoked with just aContentState to serialize using just the default Draft functionality.convertToHTML can be passed as an argument to a plugin to modularly augment its functionality.
Legacy alternative conversion optionsstyleToHTML andblockToHTML options may be plain objects keyed by style or block type with values ofReactElement s or{start, end} objects. These objects will eventually be removed in favor of the functions described above.
Type info:
typeContentStateConverter=(contentState:ContentState)=>stringtypeTag=ReactElement|{start:string,end:string,empty?:string}|{element:ReactElement,empty?:ReactElement}typeRawEntity={type:string,mutability:DraftEntityMutability,data:Object}typeRawBlock={type:string,depth:number,data?:object,text:string}typeconvertToHTML=ContentStateConverter|({styleToHTML?:(style:string)=>Tag,blockToHTML?:(block:RawBlock)=>Tag),entityToHTML?:(entity:RawEntity,originalText:string)=>Tag|string})=>ContentStateConverter
Extensibly deserialize HTML to Draft.jsContentState.
Basic usage:
consteditorState=EditorState.createWithContent(convertFromHTML(html));
Advanced usage:
// convert HTML to ContentState with blue text, links, and at-mentionsconstcontentState=convertFromHTML({htmlToStyle:(nodeName,node,currentStyle)=>{if(nodeName==='span'&&node.style.color==='blue'){returncurrentStyle.add('BLUE');}else{returncurrentStyle;}},htmlToEntity:(nodeName,node,createEntity)=>{if(nodeName==='a'){returncreateEntity('LINK','MUTABLE',{url:node.href})}},textToEntity:(text,createEntity)=>{constresult=[];text.replace(/\@(\w+)/g,(match,name,offset)=>{constentityKey=createEntity('AT-MENTION','IMMUTABLE',{name});result.push({entity:entityKey, offset,length:match.length,result:match});});returnresult;},htmlToBlock:(nodeName,node)=>{if(nodeName==='blockquote'){return{type:'blockquote',data:{}};}}})(html);// convert HTML to ContentState with functionality defined in the draft-extend plugins appliedconstfromHTML=compose(FirstPlugin,SecondPlugin,ThirdPlugin)(convertFromHTML);constcontentState=fromHTML(html);
If no additional functionality is necessaryconvertToHTML can be invoked with just an HTML string to deserialize using just the default Draft functionality. AnyconvertFromHTML can be passed as an argument to a plugin to modularly augment its functionality. Aflat option may be provided to force nested block elements to split into flat, separate blocks. For example, the HTML input<p>line one<br />linetwo</p> will produce twounstyled blocks inflat mode.
Type info:
typeHTMLConverter=(html:string,{flat: ?boolean},DOMBuilder: ?Function,generateKey: ?Function)=>ContentStatetypeEntityKey=stringtypeconvertFromHTML=HTMLConverter|({htmlToStyle: ?(nodeName:string,node:Node)=>DraftInlineStyle,htmlToBlock: ?(nodeName:string,node:Node)=> ?(DraftBlockType|{type:DraftBlockType,data:object}|false),htmlToEntity: ?(nodeName:string,node:Node,createEntity:(type:string,mutability:string,data:object)=>EntityKey,getEntity:(key:EntityKey)=>Entity,mergeEntityData:(key:string,data:object)=>void,replaceEntityData:(key:string,data:object)=>void): ?EntityKey,textToEntity: ?(text:string,createEntity:(type:string,mutability:string,data:object)=>EntityKey,getEntity:(key:EntityKey)=>Entity,mergeEntityData:(key:string,data:object)=>void,replaceEntityData:(key:string,data:object)=>void)=>Array<{entity:EntityKey,offset:number,length:number,result: ?string}>})=>HTMLConverter
Any conversion option forconvertToHTML orconvertFromHTML may also accept a middleware function of shape(next) => (…args) => result , where…args are the normal configuration function paramaters andresult is the expected return type for that function. These functions can transform results of the default conversion included inconvertToHTML orconvertFromHTML by leveraging the result ofnext(...args). These middleware functions are most useful when passed as the result of composition ofdraft-extend plugins. If you choose to use them independently, a__isMiddleware property must be set totrue on the function fordraft-convert to properly handle it.
About
Extensibly serialize & deserialize Draft.js ContentState with HTML.