mirror of https://github.com/artf/grapesjs.git
Browse Source
* Initial setup for custom code parser * Update ParserHtml * Move methods * Up * Move utils * Fix tests * Up sanitize * Up domToParsedNode * Up fragment node * Remove node cloning * Convert ParserHtml to class * Convert ParserCss to a class * Update Custom CSS/HTML docs * Always use isParsedNode if available * Update API * Update docs for isParserNoderelease-v0.23.1-rc.0
Artur Arseniev
4 months ago
committed by
GitHub
GitHub
25 changed files with 1609 additions and 634 deletions
@ -0,0 +1,143 @@ |
|||
--- |
|||
title: Use Custom HTML Parser |
|||
--- |
|||
|
|||
# Use Custom HTML Parser |
|||
|
|||
If your GrapesJS integration needs to parse HTML in environments where DOM APIs are not available, you can register a custom HTML code parser and let GrapesJS compile the returned parsed nodes into components. |
|||
|
|||
This is useful for: |
|||
|
|||
- server-side or worker-based HTML imports |
|||
- integrations that already have their own HTML parser |
|||
- cases where component recognition should not depend on browser DOM nodes |
|||
|
|||
::: warning |
|||
This guide requires GrapesJS v0.23.1 or higher |
|||
::: |
|||
|
|||
[[toc]] |
|||
|
|||
## Register a parser |
|||
|
|||
Code parsers are managed by the `Parser` module. |
|||
|
|||
```js |
|||
const { Parser } = editor; |
|||
|
|||
Parser.addParserCode( |
|||
'my-parser', |
|||
(input) => { |
|||
return [ |
|||
{ |
|||
nodeType: 1, |
|||
tagName: 'section', |
|||
attributes: { class: 'hero' }, |
|||
childNodes: [{ nodeType: 3, textContent: 'Hello world' }], |
|||
}, |
|||
]; |
|||
} |
|||
); |
|||
``` |
|||
|
|||
The parser function must always return an array of parsed nodes. |
|||
|
|||
## Select a parser |
|||
|
|||
You can select the active parser globally: |
|||
|
|||
```js |
|||
Parser.parserCode = 'my-parser'; |
|||
const result = Parser.parseHtml('<section>Hello world</section>'); |
|||
``` |
|||
|
|||
Or for a single call: |
|||
|
|||
```js |
|||
const result = Parser.parseHtml('<section>Hello world</section>', { |
|||
parserCode: 'my-parser', |
|||
}); |
|||
``` |
|||
|
|||
Passing `parserCode: ''` forces the built-in DOM parser path for that call. |
|||
|
|||
## Parsed nodes |
|||
|
|||
Custom parsers return nodes shaped like this: |
|||
|
|||
```ts |
|||
interface ParsedNode { |
|||
nodeType?: number; |
|||
tagName?: string; |
|||
namespaceURI?: string; |
|||
attributes?: Record<string, string>; |
|||
childNodes?: ParsedNode[]; |
|||
textContent?: string; |
|||
} |
|||
``` |
|||
|
|||
Supported node types in the current implementation are: |
|||
|
|||
- `1` for elements |
|||
- `3` for text nodes |
|||
- `8` for comments |
|||
- `9` for documents |
|||
- `11` for document fragments |
|||
|
|||
When `asDocument: true` is used, GrapesJS normalizes the parser output to a document-like root so `root`, `head`, and `body` can still be compiled. |
|||
|
|||
## Component recognition |
|||
|
|||
For headless parsing, component types can implement `isParsedNode`: |
|||
|
|||
```js |
|||
editor.Components.addType('my-component', { |
|||
isParsedNode(node, opts) { |
|||
if (node.tagName === 'my-component') { |
|||
return { type: 'my-component' }; |
|||
} |
|||
}, |
|||
}); |
|||
``` |
|||
|
|||
When `parserCode` is active, `isParsedNode` is preferred over `isComponent`. |
|||
|
|||
## Legacy `isComponent` fallback |
|||
|
|||
Existing components that only implement `isComponent` continue to work with `parserCode`. |
|||
GrapesJS passes a read-only synthetic element that exposes the most common DOM-like properties: |
|||
|
|||
- `nodeType` |
|||
- `tagName` |
|||
- `nodeName` |
|||
- `namespaceURI` |
|||
- `textContent` |
|||
- `nodeValue` |
|||
- `parentNode` |
|||
- `childNodes` |
|||
- `children` |
|||
- `getAttribute` |
|||
- `hasAttribute` |
|||
|
|||
If you need more DOM-like helpers, extend the base synthetic element: |
|||
|
|||
```js |
|||
editor.Parser.config.customSyntheticElement = (SyntheticElement) => |
|||
class MySyntheticElement extends SyntheticElement { |
|||
get foo() { |
|||
return this.getAttribute('data-foo') || ''; |
|||
} |
|||
}; |
|||
``` |
|||
|
|||
## Registry helpers |
|||
|
|||
You can inspect and manage the registry at runtime: |
|||
|
|||
```js |
|||
const parser = Parser.getParserCode('my-parser'); |
|||
const removed = Parser.removeParserCode('my-parser'); |
|||
const registry = Parser.parsersCode; |
|||
``` |
|||
|
|||
Removing the selected parser clears `Parser.parserCode`. |
|||
@ -0,0 +1,105 @@ |
|||
import { ParsedNode, ParsedNodeNamespace, ParsedNodeType, SyntheticElementCtor } from '../types'; |
|||
|
|||
const getTagName = (node: ParsedNode) => { |
|||
const tagName = node.tagName || ''; |
|||
return tagName && (!node.namespaceURI || node.namespaceURI === ParsedNodeNamespace.html) |
|||
? tagName.toUpperCase() |
|||
: tagName; |
|||
}; |
|||
|
|||
const getNodeTextContent = (node: ParsedNode): string => { |
|||
if (node.nodeType === ParsedNodeType.text || node.nodeType === ParsedNodeType.comment) { |
|||
return node.textContent ?? ''; |
|||
} |
|||
|
|||
if (node.textContent && !node.childNodes?.length) { |
|||
return node.textContent; |
|||
} |
|||
|
|||
return (node.childNodes || []).map(getNodeTextContent).join(''); |
|||
}; |
|||
|
|||
const getClassList = (node: ParsedNode) => { |
|||
const value = node.attributes?.class || ''; |
|||
const items = value.split(/\s+/).filter(Boolean); |
|||
|
|||
return { |
|||
value, |
|||
length: items.length, |
|||
contains(name: string) { |
|||
return items.includes(name); |
|||
}, |
|||
item(index: number) { |
|||
return items[index] || null; |
|||
}, |
|||
toString() { |
|||
return value; |
|||
}, |
|||
}; |
|||
}; |
|||
|
|||
export class SyntheticElement { |
|||
node: ParsedNode; |
|||
parent?: SyntheticElement; |
|||
|
|||
constructor(node: ParsedNode, parent?: SyntheticElement) { |
|||
this.node = node; |
|||
this.parent = parent; |
|||
} |
|||
|
|||
get nodeType() { |
|||
return this.node.nodeType; |
|||
} |
|||
|
|||
get tagName() { |
|||
return getTagName(this.node); |
|||
} |
|||
|
|||
get nodeName() { |
|||
return this.tagName; |
|||
} |
|||
|
|||
get namespaceURI() { |
|||
return this.node.namespaceURI; |
|||
} |
|||
|
|||
get parentNode() { |
|||
return this.parent; |
|||
} |
|||
|
|||
get childNodes() { |
|||
return (this.node.childNodes || []).map((node) => new (this.constructor as SyntheticElementCtor)(node, this)); |
|||
} |
|||
|
|||
get children() { |
|||
return this.childNodes.filter((node) => node.nodeType === 1); |
|||
} |
|||
|
|||
get textContent() { |
|||
return getNodeTextContent(this.node); |
|||
} |
|||
|
|||
get nodeValue() { |
|||
return this.nodeType === ParsedNodeType.text || this.nodeType === ParsedNodeType.comment ? this.textContent : null; |
|||
} |
|||
|
|||
get className() { |
|||
return this.getAttribute('class') || ''; |
|||
} |
|||
|
|||
get classList() { |
|||
return getClassList(this.node); |
|||
} |
|||
|
|||
getAttribute(key: string) { |
|||
return this.node.attributes?.[key]; |
|||
} |
|||
|
|||
hasAttribute(key: string) { |
|||
return Object.prototype.hasOwnProperty.call(this.node.attributes || {}, key); |
|||
} |
|||
} |
|||
|
|||
export const getSyntheticElementCtor = ( |
|||
customSyntheticElement?: ((SyntheticElement: SyntheticElementCtor) => SyntheticElementCtor) | null, |
|||
) => (customSyntheticElement ? customSyntheticElement(SyntheticElement as SyntheticElementCtor) : SyntheticElement); |
|||
@ -0,0 +1,200 @@ |
|||
import { each } from 'underscore'; |
|||
import { doctypeToString } from '../../utils/dom'; |
|||
import { HTMLParserOptions } from '../config/config'; |
|||
import { ParsedNode, ParsedNodeMeta, ParsedNodeNamespace, ParsedNodeType } from '../types'; |
|||
|
|||
export const getNodeChildNodes = (node: ParsedNodeMeta) => node.childNodes || []; |
|||
|
|||
export const getNodeTagName = (node: ParsedNodeMeta) => `${node.tagName || ''}`.toLowerCase(); |
|||
|
|||
export const getSourceNode = (node: ParsedNodeMeta) => node.__domNode || node; |
|||
|
|||
export const getDomChildNodes = (node: Node) => { |
|||
const template = node as HTMLTemplateElement; |
|||
const childNodes = template.content?.childNodes || node.childNodes || []; |
|||
return Array.from(childNodes); |
|||
}; |
|||
|
|||
export const createElementNode = (tagName: string, childNodes: ParsedNodeMeta[] = []): ParsedNodeMeta => ({ |
|||
nodeType: ParsedNodeType.element, |
|||
tagName, |
|||
namespaceURI: ParsedNodeNamespace.html, |
|||
childNodes, |
|||
}); |
|||
|
|||
export const createFragmentRoot = (childNodes: ParsedNode[]): ParsedNodeMeta => ({ |
|||
nodeType: ParsedNodeType.fragment, |
|||
childNodes, |
|||
}); |
|||
|
|||
export const appendChildElement = (node: ParsedNodeMeta, tagName: string) => { |
|||
const child = createElementNode(tagName); |
|||
node.childNodes = [...getNodeChildNodes(node), child]; |
|||
return child; |
|||
}; |
|||
|
|||
export const findChildElement = (node: ParsedNodeMeta, tagName: string) => |
|||
getNodeChildNodes(node).find((child) => getNodeTagName(child) === tagName); |
|||
|
|||
export const getNodeTextContent = (node: ParsedNodeMeta): string => { |
|||
if (node.nodeType === ParsedNodeType.text || node.nodeType === ParsedNodeType.comment) { |
|||
return node.textContent ?? ''; |
|||
} |
|||
|
|||
if (node.textContent && !node.childNodes?.length) { |
|||
return node.textContent; |
|||
} |
|||
|
|||
return getNodeChildNodes(node) |
|||
.map((child) => getNodeTextContent(child)) |
|||
.join(''); |
|||
}; |
|||
|
|||
export const removeElementNodes = (root: ParsedNodeMeta, tagName: string) => { |
|||
const removed: ParsedNodeMeta[] = []; |
|||
const remove = (node: ParsedNodeMeta) => { |
|||
if (!node.childNodes?.length) return; |
|||
const nextNodes: ParsedNodeMeta[] = []; |
|||
|
|||
node.childNodes.forEach((child) => { |
|||
if (getNodeTagName(child) === tagName) { |
|||
removed.push(child); |
|||
return; |
|||
} |
|||
|
|||
remove(child); |
|||
nextNodes.push(child); |
|||
}); |
|||
|
|||
node.childNodes = nextNodes; |
|||
}; |
|||
|
|||
remove(root); |
|||
return removed; |
|||
}; |
|||
|
|||
export const sanitizeNode = (node: ParsedNodeMeta, opts: HTMLParserOptions) => { |
|||
const attrs = node.attributes || {}; |
|||
const cleanAttrs: Record<string, string> = {}; |
|||
|
|||
each(attrs, (value, name) => { |
|||
const attrValue = `${value}`; |
|||
const isUnsafeAttr = !opts.allowUnsafeAttr && name.startsWith('on'); |
|||
const isUnsafeValue = !opts.allowUnsafeAttrValue && attrValue.startsWith('javascript:'); |
|||
|
|||
if (!isUnsafeAttr && !isUnsafeValue) { |
|||
cleanAttrs[name] = attrValue; |
|||
} |
|||
}); |
|||
|
|||
if (Object.keys(cleanAttrs).length) { |
|||
node.attributes = cleanAttrs; |
|||
} else { |
|||
delete node.attributes; |
|||
} |
|||
|
|||
getNodeChildNodes(node).forEach((child) => sanitizeNode(child, opts)); |
|||
}; |
|||
|
|||
export const domDocumentToParsedNode = (doc: Document): ParsedNodeMeta => ({ |
|||
nodeType: ParsedNodeType.document, |
|||
__domNode: doc, |
|||
__doctype: doctypeToString(doc.doctype), |
|||
childNodes: doc.documentElement ? [domToParsedNode(doc.documentElement)] : [], |
|||
}); |
|||
|
|||
export const domToParsedNode = (node: Node): ParsedNodeMeta => { |
|||
const { nodeType } = node; |
|||
if (nodeType === ParsedNodeType.document) return domDocumentToParsedNode(node as Document); |
|||
|
|||
const el = node as HTMLElement; |
|||
const parsedNode: ParsedNodeMeta = { |
|||
nodeType, |
|||
tagName: el.tagName || '', |
|||
namespaceURI: el.namespaceURI || undefined, |
|||
__domNode: node, |
|||
}; |
|||
|
|||
if (nodeType === ParsedNodeType.text || nodeType === ParsedNodeType.comment) { |
|||
parsedNode.textContent = node.textContent ?? ''; |
|||
} |
|||
|
|||
if (nodeType === ParsedNodeType.element) { |
|||
const el = node as HTMLElement; |
|||
|
|||
const attrs = el.attributes || []; |
|||
if (attrs.length) { |
|||
parsedNode.attributes = {}; |
|||
} |
|||
|
|||
const boolAttributes: string[] = []; |
|||
for (let i = 0; i < attrs.length; i++) { |
|||
const attr = attrs[i]; |
|||
parsedNode.attributes![attr.nodeName] = attr.nodeValue || ''; |
|||
if (attr.nodeValue === '' && (el as any)[attr.nodeName] === true) { |
|||
boolAttributes.push(attr.nodeName); |
|||
} |
|||
} |
|||
|
|||
boolAttributes.length && (parsedNode.__boolAttributes = boolAttributes); |
|||
|
|||
const childNodes = getDomChildNodes(el); |
|||
childNodes.length && (parsedNode.childNodes = childNodes.map((child) => domToParsedNode(child))); |
|||
parsedNode.__selfClosing = `${el.outerHTML || ''}`.slice(-2) === '/>'; |
|||
} |
|||
|
|||
return parsedNode; |
|||
}; |
|||
|
|||
export const domRootToFragmentParsedNode = (root: HTMLElement): ParsedNodeMeta => ({ |
|||
nodeType: ParsedNodeType.fragment, |
|||
__domNode: root, |
|||
childNodes: getDomChildNodes(root).map((node) => domToParsedNode(node)), |
|||
}); |
|||
|
|||
export const normalizeDocumentRoot = (nodes: ParsedNode[]) => { |
|||
const flatNodes = nodes.flatMap((node) => |
|||
node.nodeType === ParsedNodeType.fragment ? getNodeChildNodes(node) : [node], |
|||
); |
|||
const documentNode = flatNodes.find((node) => node.nodeType === ParsedNodeType.document); |
|||
if (documentNode) { |
|||
return documentNode; |
|||
} |
|||
|
|||
const htmlNode = flatNodes.find((node) => getNodeTagName(node) === 'html'); |
|||
const documentRoot: ParsedNodeMeta = { |
|||
nodeType: ParsedNodeType.document, |
|||
childNodes: [], |
|||
}; |
|||
|
|||
if (htmlNode) { |
|||
const extraNodes = flatNodes.filter((node) => node !== htmlNode); |
|||
if (extraNodes.length) { |
|||
const bodyNode = findChildElement(htmlNode, 'body') || appendChildElement(htmlNode, 'body'); |
|||
bodyNode.childNodes = [...getNodeChildNodes(bodyNode), ...extraNodes]; |
|||
} |
|||
|
|||
documentRoot.childNodes = [htmlNode]; |
|||
return documentRoot; |
|||
} |
|||
|
|||
const remaining = [...flatNodes]; |
|||
const headIndex = remaining.findIndex((node) => getNodeTagName(node) === 'head'); |
|||
const bodyIndex = remaining.findIndex((node) => getNodeTagName(node) === 'body'); |
|||
const headNode = headIndex >= 0 ? remaining.splice(headIndex, 1)[0] : undefined; |
|||
const bodyNode = |
|||
bodyIndex >= 0 |
|||
? remaining.splice(bodyIndex > headIndex && headIndex >= 0 ? bodyIndex - 1 : bodyIndex, 1)[0] |
|||
: undefined; |
|||
const htmlRoot = createElementNode('html'); |
|||
const htmlChildren: ParsedNodeMeta[] = []; |
|||
|
|||
headNode && htmlChildren.push(headNode); |
|||
const normalizedBody = bodyNode || createElementNode('body'); |
|||
normalizedBody.childNodes = [...getNodeChildNodes(normalizedBody), ...remaining]; |
|||
htmlChildren.push(normalizedBody); |
|||
|
|||
htmlRoot.childNodes = htmlChildren; |
|||
documentRoot.childNodes = [htmlRoot]; |
|||
return documentRoot; |
|||
}; |
|||
@ -0,0 +1,75 @@ |
|||
import Editor from '../../../src/editor/model/Editor'; |
|||
|
|||
describe('Parser module', () => { |
|||
let em: Editor; |
|||
|
|||
beforeEach(() => { |
|||
em = new Editor({}); |
|||
}); |
|||
|
|||
afterEach(() => { |
|||
em.destroy(); |
|||
}); |
|||
|
|||
test('adds, gets, removes code parsers and selects them by default', () => { |
|||
const parse = jest.fn(() => []); |
|||
const parser = em.Parser.addParserCode('test-parser', parse); |
|||
|
|||
expect(parser).toEqual({ |
|||
id: 'test-parser', |
|||
parse, |
|||
}); |
|||
expect(em.Parser.getParserCode('test-parser')).toBe(parser); |
|||
expect(em.Parser.parserCode).toBe('test-parser'); |
|||
expect(em.Parser.removeParserCode('test-parser')).toBe(parser); |
|||
expect(em.Parser.getParserCode('test-parser')).toBeUndefined(); |
|||
expect(em.Parser.parserCode).toBe(''); |
|||
}); |
|||
|
|||
test('loads code parsers from init config and selects the last one by default', () => { |
|||
const first = jest.fn(() => []); |
|||
const second = jest.fn(() => []); |
|||
const editor = new Editor({ |
|||
parser: { |
|||
parsersCode: { |
|||
first, |
|||
second, |
|||
}, |
|||
}, |
|||
}); |
|||
|
|||
expect(editor.Parser.getParserCode('first')?.parse).toBe(first); |
|||
expect(editor.Parser.getParserCode('second')?.parse).toBe(second); |
|||
expect(editor.Parser.parserCode).toBe('second'); |
|||
|
|||
editor.destroy(); |
|||
}); |
|||
|
|||
test('allows init config to skip selecting a default parser', () => { |
|||
const editor = new Editor({ |
|||
parser: { |
|||
parserCode: '', |
|||
parsersCode: { |
|||
first: () => [], |
|||
second: () => [], |
|||
}, |
|||
}, |
|||
}); |
|||
|
|||
expect(editor.Parser.parserCode).toBe(''); |
|||
|
|||
editor.destroy(); |
|||
}); |
|||
|
|||
test('supports global parserCode, per-call overrides, and legacy fallback', () => { |
|||
em.Parser.addParserCode('section-parser', () => [{ nodeType: 1, tagName: 'section' }]); |
|||
em.Parser.addParserCode('article-parser', () => [{ nodeType: 1, tagName: 'article' }], { skipSelect: true }); |
|||
|
|||
expect(em.Parser.parseHtml('<div></div>').html).toEqual({ tagName: 'section' }); |
|||
expect(em.Parser.parseHtml('<div></div>', { parserCode: 'article-parser' }).html).toEqual({ tagName: 'article' }); |
|||
expect(em.Parser.parseHtml('<div></div>', { parserCode: '' }).html).toEqual({ tagName: 'div' }); |
|||
expect(() => em.Parser.parseHtml('<div></div>', { parserCode: 'missing-parser' })).toThrow( |
|||
'Parser code "missing-parser" not found', |
|||
); |
|||
}); |
|||
}); |
|||
Loading…
Reference in new issue