Code Coverage |
||||||||||
Lines |
Functions and Methods |
Classes and Traits |
||||||||
| Total | |
0.00% |
0 / 6 |
|
0.00% |
0 / 6 |
CRAP | |
0.00% |
0 / 1 |
| ExtensionTagHandler | |
0.00% |
0 / 6 |
|
0.00% |
0 / 6 |
42 | |
0.00% |
0 / 1 |
| sourceToDom | |
0.00% |
0 / 1 |
|
0.00% |
0 / 1 |
2 | |||
| processAttributeEmbeddedHTML | |
0.00% |
0 / 1 |
|
0.00% |
0 / 1 |
2 | |||
| processAttributeEmbeddedDom | |
0.00% |
0 / 1 |
|
0.00% |
0 / 1 |
2 | |||
| lintHandler | |
0.00% |
0 / 1 |
|
0.00% |
0 / 1 |
2 | |||
| domToWikitext | |
0.00% |
0 / 1 |
|
0.00% |
0 / 1 |
2 | |||
| diffHandler | |
0.00% |
0 / 1 |
|
0.00% |
0 / 1 |
2 | |||
| 1 | <?php |
| 2 | declare( strict_types = 1 ); |
| 3 | // @phan-file-suppress PhanEmptyPublicMethod |
| 4 | |
| 5 | namespace Wikimedia\Parsoid\Ext; |
| 6 | |
| 7 | use Closure; |
| 8 | use Wikimedia\Parsoid\DOM\DocumentFragment; |
| 9 | use 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 | */ |
| 22 | abstract 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 | } |