Code Coverage
 
Lines
Functions and Methods
Classes and Traits
Total
0.00% covered (danger)
0.00%
0 / 6
0.00% covered (danger)
0.00%
0 / 6
CRAP
0.00% covered (danger)
0.00%
0 / 1
ExtensionTagHandler
0.00% covered (danger)
0.00%
0 / 6
0.00% covered (danger)
0.00%
0 / 6
42
0.00% covered (danger)
0.00%
0 / 1
 sourceToDom
0.00% covered (danger)
0.00%
0 / 1
0.00% covered (danger)
0.00%
0 / 1
2
 processAttributeEmbeddedHTML
0.00% covered (danger)
0.00%
0 / 1
0.00% covered (danger)
0.00%
0 / 1
2
 processAttributeEmbeddedDom
0.00% covered (danger)
0.00%
0 / 1
0.00% covered (danger)
0.00%
0 / 1
2
 lintHandler
0.00% covered (danger)
0.00%
0 / 1
0.00% covered (danger)
0.00%
0 / 1
2
 domToWikitext
0.00% covered (danger)
0.00%
0 / 1
0.00% covered (danger)
0.00%
0 / 1
2
 diffHandler
0.00% covered (danger)
0.00%
0 / 1
0.00% covered (danger)
0.00%
0 / 1
2
1<?php
2declare( strict_types = 1 );
3// @phan-file-suppress PhanEmptyPublicMethod
4
5namespace Wikimedia\Parsoid\Ext;
6
7use Closure;
8use Wikimedia\Parsoid\DOM\DocumentFragment;
9use Wikimedia\Parsoid\DOM\Element;
10
11/**
12 * A Parsoid extension module may register handlers for one or more
13 * extension tags. The only method which is generally
14 * required by all extension tags is `sourceToDom` (but Translate
15 * doesn't even implement that).  All other methods have default do-nothing
16 * implementations; override them iff you wish to implement those
17 * features.  Default implementations consistently return `false`
18 * to indicate not-implemented (in some cases `null` would be a
19 * valid return value, and in other cases `null` would be a likely
20 * "accidental" return value which we'd like to catch and flag).
21 */
22abstract class ExtensionTagHandler {
23
24    /**
25     * Convert an extension tag's content to "prepared and loaded" DOM.
26     *
27     * @param ParsoidExtensionAPI $extApi
28     * @param string $content Extension tag content
29     * @param array $args Extension tag arguments
30     *   The extension tag arguments should be treated as opaque objects
31     *   and any necessary inspection should be handled through the API.
32     * @return DocumentFragment|false|null
33     *   `DocumentFragment` if returning some parsed content
34     *   `false` to fallback to the default handler for the content
35     *   `null` to drop the instance completely
36     */
37    public function sourceToDom(
38        ParsoidExtensionAPI $extApi, string $content, array $args
39    ) {
40        return false; /* Use default wrapper */
41    }
42
43    /**
44     * Extensions might embed HTML in attributes in their own custom
45     * representation (whether in data-mw or elsewhere).
46     *
47     * Core Parsoid will need a way to traverse such content. This method
48     * is a way for extension tag handlers to provide this functionality.
49     * Parsoid will only call this method if the tag's config sets the
50     * options['wt2html']['embedsHTMLInAttributes'] property to true.
51     *
52     * Override this method if your element embeds content as an HTML string;
53     * however it is recommended to embed content directly as a
54     * DocumentFragment and override ::processAttributeEmbeddedDom() instead.
55     *
56     * @param ParsoidExtensionAPI $extApi
57     * @param Element $elt The node whose data attributes need to be examined
58     * @param Closure $proc The processor that will process the embedded HTML
59     *        Signature: (string) -> string
60     *        This processor will be provided the HTML string as input
61     *        and is expected to return a possibly modified string.
62     */
63    public function processAttributeEmbeddedHTML(
64        ParsoidExtensionAPI $extApi, Element $elt, Closure $proc
65    ): void {
66        // Nothing to do by default
67    }
68
69    /**
70     * Extensions might embed HTML in attributes in their own custom
71     * representation (whether in data-mw or elsewhere).
72     *
73     * Core Parsoid will need a way to traverse such content. This method
74     * is a way for extension tag handlers to provide this functionality.
75     * Parsoid will only call this method if the tag's config sets the
76     * options['wt2html']['embedsDomInAttributes'] property to true.
77     *
78     * Override this method if your element embeds
79     * content directly as a DocumentFragment, which is recommended.
80     * If your element embeds content as a serialized HTML string,
81     * then ::processAttributeEmbeddedHTML() may be more convenient.
82     *
83     * @param ParsoidExtensionAPI $extApi
84     * @param Element $elt The node whose data attributes need to be examined
85     * @param callable(DocumentFragment):bool $proc
86     *        The processor that will process the embedded HTML.
87     *        This processor will be provided a DocumentFragment
88     *        and is expected to return true if that fragment was modified.
89     */
90    public function processAttributeEmbeddedDom(
91        ParsoidExtensionAPI $extApi, Element $elt, callable $proc
92    ): void {
93        // Nothing to do by default
94    }
95
96    /**
97     * Lint handler for this extension.
98     *
99     * If the extension has lints it wants to expose, it should use $extApi
100     * to register those lints. Alternatively, the extension might simply
101     * inspect its DOM and invoke the default lint handler on a DOM tree
102     * that it wants inspected. For example, <ref> nodes often only have
103     * a pointer (the id attribute) to its content, and its lint handler would
104     * look up the DOM tree and invoke the default lint handler on that tree.
105     *
106     * @param ParsoidExtensionAPI $extApi
107     * @param Element $rootNode Extension content's root node
108     * @param callable $defaultHandler Default lint handler
109     *    - Default lint handler has signature $defaultHandler( Element $elt ): void
110     * @return bool Return `false` to indicate that this
111     *   extension has no special lint handler (the default lint handler will
112     *   be used.  Return `true` to indicate linting should proceed with the
113     *   next sibling.
114     */
115    public function lintHandler(
116        ParsoidExtensionAPI $extApi, Element $rootNode, callable $defaultHandler
117    ): bool {
118        /* Use default linter */
119        return false;
120    }
121
122    /**
123     * Serialize a DOM node created by this extension to wikitext.
124     *
125     * @param ParsoidExtensionAPI $extApi
126     * @param Element $node A node in a "prepared and loaded" document.
127     * @param bool $wrapperUnmodified
128     * @return string|false Return false to use the default serialization.
129     */
130    public function domToWikitext(
131        ParsoidExtensionAPI $extApi, Element $node, bool $wrapperUnmodified
132    ) {
133        /* Use default serialization */
134        return false;
135    }
136
137    /**
138     * XXX: Experimental
139     *
140     * Call $domDiff on corresponding subtrees of $origNode and $editedNode
141     *
142     * @param ParsoidExtensionAPI $extApi
143     * @param callable $domDiff
144     * @param Element $origNode
145     * @param Element $editedNode
146     * @return bool
147     */
148    public function diffHandler(
149        ParsoidExtensionAPI $extApi, callable $domDiff, Element $origNode,
150        Element $editedNode
151    ): bool {
152        return false;
153    }
154}