Code Coverage
 
Lines
Functions and Methods
Classes and Traits
Total
0.00% covered (danger)
0.00%
0 / 5
0.00% covered (danger)
0.00%
0 / 5
 CRAP
0.00% covered (danger)
0.00%
0 / 1
ExtensionTagHandler
0.00% covered (danger)
0.00%
0 / 5
0.00% covered (danger)
0.00%
0 / 5
 30
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
 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
4namespace Wikimedia\Parsoid\Ext;
5
6use Closure;
7use Wikimedia\Parsoid\DOM\DocumentFragment;
8use Wikimedia\Parsoid\DOM\Element;
9use Wikimedia\Parsoid\DOM\Node;
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 DOM
26     * @param ParsoidExtensionAPI $extApi
27     * @param string $src Extension tag content
28     * @param array $extArgs Extension tag arguments
29     *   The extension tag arguments should be treated as opaque objects
30     *   and any necessary inspection should be handled through the API.
31     * @return DocumentFragment|false|null
32     *   `DocumentFragment` if returning some parsed content
33     *   `false` to fallback to the default handler for the content
34     *   `null` to drop the instance completely
35     */
36    public function sourceToDom(
37        ParsoidExtensionAPI $extApi, string $src, array $extArgs
38    ) {
39        return false; /* Use default wrapper */
40    }
41
42    /**
43     * Extensions might embed HTML in attributes in their own custom
44     * representation (whether in data-mw or elsewhere).
45     *
46     * Core Parsoid will need a way to traverse such content. This method
47     * is a way for extension tag handlers to provide this functionality.
48     * Parsoid will only call this method if the tag's config sets the
49     * options['wt2html']['embedsHTMLInAttributes'] property to true.
50     *
51     * @param ParsoidExtensionAPI $extApi
52     * @param Element $elt The node whose data attributes need to be examined
53     * @param Closure $proc The processor that will process the embedded HTML
54     *        Signature: (string) -> string
55     *        This processor will be provided the HTML string as input
56     *        and is expected to return a possibly modified string.
57     */
58    public function processAttributeEmbeddedHTML(
59        ParsoidExtensionAPI $extApi, Element $elt, Closure $proc
60    ): void {
61        // Nothing to do by default
62    }
63
64    /**
65     * Lint handler for this extension.
66     *
67     * If the extension has lints it wants to expose, it should use $extApi
68     * to register those lints. Alternatively, the extension might simply
69     * inspect its DOM and invoke the default lint handler on a DOM tree
70     * that it wants inspected. For example, <ref> nodes often only have
71     * a pointer (the id attribute) to its content, and is lint handler would
72     * look up the DOM tree and invoke the default lint handler on that tree.
73     *
74     * FIXME: There is probably no reason for the lint handler to return anything.
75     * The caller should simply proceed with the next sibling of $rootNode
76     * after the lint handler returns.
77     *
78     * @param ParsoidExtensionAPI $extApi
79     * @param Element $rootNode Extension content's root node
80     * @param callable $defaultHandler Default lint handler
81     *    - Default lint handler has signature $defaultHandler( Element $elt ): void
82     * @return Node|null|false Return `false` to indicate that this
83     *   extension has no special lint handler (the default lint handler will
84     *   be used.  Return `null` to indicate linting should proceed with the
85     *   next sibling.  (Deprecated) A `Node` can be returned to indicate
86     *   the point in the tree where linting should resume.
87     */
88    public function lintHandler(
89        ParsoidExtensionAPI $extApi, Element $rootNode, callable $defaultHandler
90    ) {
91        /* Use default linter */
92        return false;
93    }
94
95    /**
96     * Serialize a DOM node created by this extension to wikitext.
97     * @param ParsoidExtensionAPI $extApi
98     * @param Element $node
99     * @param bool $wrapperUnmodified
100     * @return string|false Return false to use the default serialization.
101     */
102    public function domToWikitext(
103        ParsoidExtensionAPI $extApi, Element $node, bool $wrapperUnmodified
104    ) {
105        /* Use default serialization */
106        return false;
107    }
108
109    /**
110     * XXX: Experimental
111     *
112     * Call $domDiff on corresponding substrees of $origNode and $editedNode
113     *
114     * @param ParsoidExtensionAPI $extApi
115     * @param callable $domDiff
116     * @param Element $origNode
117     * @param Element $editedNode
118     * @return bool
119     */
120    public function diffHandler(
121        ParsoidExtensionAPI $extApi, callable $domDiff, Element $origNode,
122        Element $editedNode
123    ): bool {
124        return false;
125    }
126}