{"_id":"heti-findandreplacedomtext","_rev":"2900807","name":"heti-findandreplacedomtext","description":"findAndReplaceDOMText: DOM find/replace utility","dist-tags":{"latest":"0.5.0"},"maintainers":[{"name":"sivan","email":"sun.sivan@qq.com"}],"time":{"modified":"2022-12-08T07:42:02.000Z","created":"2020-03-15T12:47:05.234Z","0.5.0":"2020-03-15T12:47:05.234Z"},"users":{},"repository":{"type":"git","url":"git+https://github.com/sivan/findAndReplaceDOMText.git"},"versions":{"0.5.0":{"name":"heti-findandreplacedomtext","version":"0.5.0","main":"./src/findAndReplaceDOMText.js","description":"findAndReplaceDOMText: DOM find/replace utility","repository":{"type":"git","url":"git+https://github.com/sivan/findAndReplaceDOMText.git"},"license":"unlicense","bugs":{"url":"https://github.com/sivan/findAndReplaceDOMText/issues"},"homepage":"https://github.com/sivan/findAndReplaceDOMText","gitHead":"8b558269ea4587ee69f4520af4d71219735738f4","_id":"heti-findandreplacedomtext@0.5.0","_nodeVersion":"10.15.3","_npmVersion":"6.9.0","dist":{"shasum":"a69dd028ac3d37c73a33173e376f2c3366cdd46f","size":27942,"noattachment":false,"key":"/heti-findandreplacedomtext/-/heti-findandreplacedomtext-0.5.0.tgz","tarball":"http://registry.cnpm.dingdandao.com/heti-findandreplacedomtext/download/heti-findandreplacedomtext-0.5.0.tgz"},"maintainers":[{"name":"sivan","email":"sun.sivan@qq.com"}],"_npmUser":{"name":"sivan","email":"sunxingfan@xiaomi.com"},"directories":{},"_npmOperationalInternal":{"host":"s3://npm-registry-packages","tmp":"tmp/heti-findandreplacedomtext_0.5.0_1584276425081_0.5967581499197376"},"_hasShrinkwrap":false,"_cnpmcore_publish_time":"2021-12-24T17:23:03.114Z","publish_time":1584276425234,"_cnpm_publish_time":1584276425234}},"readme":"# findAndReplaceDOMText\n\nForked from [padolsey/findAndReplaceDOMText](https://github.com/padolsey/findAndReplaceDOMText), add offset option to fix browsers which don't support regex lookbehind.\n\n**[See the demo](http://padolsey.github.com/findAndReplaceDOMText/demo.html)**\n\n`findAndReplaceDOMText` searches for regular expression matches in a given DOM node and replaces or wraps each match with a node or piece of text that you can specify.\n\nFor example:\n\n```html\n<p id=\"t\">\n  123 456 Hello\n</p>\n```\n\n```js\nfindAndReplaceDOMText(document.getElementById('t'), {\n  find: /Hello/,\n  wrap: 'em'\n});\n```\n\nThis would result in:\n\n```html\n<p id=\"t\">\n  123 456 <em>Hello</em>\n</p>\n```\n\nAnd it also works when matches are spread **across multiple nodes**! E.g.\n\n```html\n<p id=\"t\">\n  123 456 Hell<span>o Goodbye</span>\n</p>\n```\n\n```js\nfindAndReplaceDOMText(document.getElementById('t'), {\n  find: /Hello/,\n  wrap: 'em'\n});\n```\n\nThis would result in:\n\n```html\n<p id=\"t\">\n  123 456 <em>Hell</em><span><em>o</em> Goodbye</span>\n</p>\n```\n\nThe `EM` element has been added twice, to cover both portions of the match.\n\n## Installation\n\nGrab the latest [findAndReplaceDOMText.js](https://github.com/padolsey/findAndReplaceDOMText/blob/master/src/findAndReplaceDOMText.js) (or `npm install findandreplacedomtext`) and include it as a `<script>` on your page.\n\n## API / Usage\n\n`findAndReplaceDOMText` has the following argument signature:\n\n```js\nfindAndReplaceDOMText(\n  element, // (Element) The element or text-node to search within\n  options  // (Object) Explained below\n);\n```\n\n### API\n\n#### Options\n\nThe `options` object includes:\n\n * **find** (`RegExp | String`): Something to search for. A string will perform a global search by default (looking for all matches), but a RegExp will only do so if you include the global (`/.../g`) flag.\n * **replace** *optional* (`String | Function`): A String of text to replace matches with, or a Function which should return replacement Node or String. If you use a string, it can contain various tokens:\n  * `$n` to represent the *n*th captured group of a regular expression (i.e. `$1`, `$2`, ...)\n  * `$0` or `$&` to represent the entire match\n  * <code>$`</code> to represent everything to the left of the match.\n  * `$'` to represent everything to the right of the match.\n * **wrap** *optional* (`String | Node`): A string representing the node-name of an element that will be wrapped around matches (e.g. `span` or `em`). Or a Node (i.e. a stencil node) that we will clone for each match portion.\n * **wrapClass** *optional* (`String`): A string representing the class name to be assigned to the wrapping element (e.g. `<span class=\"myClass\">found text</span>`).  If the `wrap` option is not specified, then this option is ignored.\n * **portionMode** *optional* (`String`, one of `\"retain\"` or `\"first\"`): Indicates whether to re-use existing node boundaries when replacing a match with text (i.e. the default, `\"retain\"`), or whether to instead place the entire replacement in the first-found match portion's node. *Most of the time you'll want the default*.\n * **filterElements** *optional* (`Function`): A function to be called on every element encountered by `findAndReplaceDOMText`. If the function returns false the element will be altogether ignored.\n * **forceContext** *optional* (`Function | Boolean`): A boolean or a boolean-returning function that'll be called on every element to determine if it should be considered as its own matching context. See below under [*Contexts*](#user-content-contexts) for more info.\n * **preset** *optional* (`String`): Currently there's only one preset: `prose`. See below.\n\n#### `preset:prose`\n\nThe most common usage of `findAndReplaceDOMText` is to replace text found in regular prose, not all DOM nodes. To make this easier there is a preset that you can use to instruct it to:\n\n * Ignore non-textual elements (E.g. `<script>`, `<svg>`, `<optgroup>`, `<textarea>`, etc.)\n * Force [bordered contexts](#user-content-contexts) on block-elements like `<p>` and `<div>` so that matches cannot cross element borders.\n * Note: matches will still be able to cross textual-inline element borders (`<em>`, `<span>`, etc.)\n\nTo enable this preset:\n\n```js\nfindAndReplaceDOMText(element, {\n  preset: 'prose',\n  find: 'something',\n  replace: 'something else'\n})\n```\n\n#### What is a portion?\n\nA portion or \"match portion\" is a part of a match that is delimited by node boundaries. Not all matches occur within a single text-node, so `findAndReplaceDOMText` has to be able to deal with cross-boundary matches (e.g. when matching `/foo/` in `\"<em>f</em>oo\"`).\n\nA portion object has the following properties:\n\n * `node`: The DOM node pertaining to the portion. Note that this node might not fully encapsulate part of a match, e.g. the node might contain additional text.\n * `index`: The index of the portion (`0` is the first portion of the match, etc.)\n * `text`: The text of the portion relevant to the match\n * `indexInMatch`: The index of the portion within the match\n * `indexInNode`: The index of the portion text within the node\n\n\n#### The `replace` Function\n\nIf you pass a function to the `replace` option your function will be called on every portion of every match and is expected to return a DOM Node (a Text or Element node). Your function will be passed both the portion and the encapsulating match of that portion.\n\nE.g.\n\n*Input HTML*\n\n```html\n<div id=\"container\">\n  Explaining how to write a replace <em>fun</em>ction\n</div>\n```\n\n*JS*\n\n```js\nfindAndReplaceDOMText(document.getElementById('container'), {\n  find: 'function',\n  replace: function(portion, match) {\n    return '[[' + portion.index + ']]';\n  }\n});\n```\n\n*Output HTML*\n\n```html\n<div id=\"container\">\n  Explaining how to write a replace <em>[[0]]</em>[[1]]\n</div>\n```\n\n#### The `wrap` Option\n\nIf you pass a string to the `wrap` option, every matching text segment will be wrapped in that element.  If you also specify the `wrapClass` option, the wrapping element will be assigned that class after it is created.  This is useful for attaching various styles from your css.\n\nE.g.\n\n*Input HTML*\n\n```html\n<div id=\"container\">\n  Explaining how to wrap text in elements with and without classes assigned.\n</div>\n```\n\n*JS*\n\n```js\nfindAndReplaceDOMText(document.getElementById('container'), {\n find: 'without',\n wrap: 'em'\n});\nfindAndReplaceDOMText(document.getElementById('container'), {\n find: 'with ',\n wrap: 'em',\n wrapClass: 'shiny'\n});\n```\n\n*CSS*\n\n```css\n.shiny {\n background-color: yellow;\n}\n```\n\n*Output HTML*\n\n```html\n<div id=\"container\">\n  Explaining how to wrap text in elements <em class=\"shiny\">with </em>and <em>without</em> classes assigned.\n</div>\n```\n\n#### The instance\n\nCalling `findAndReplaceDOMText` returns an instance of an internal Finder constructor -- the API on the object is limited, at the moment, to reverting:\n\n```js\nvar finder = findAndReplaceDOMText(...);\n\n// Later:\nfinder.revert();\n```\n\n**Note:** Reversion will only work if the nodes have not been tampered with after the initial replacement -- if there have been removals, movements or normalisations then the reversion is not guarenteed to work. In this case it's best to retain your own clone of the target node(s) in order to run your own reversion.\n\n### Contexts\n\nMatching, by default, will occur on all elements and across all element borders. E.g.\n\nBefore:\n\n```html\n<div id=\"test\">\n  <p>ama</p><p>zing</p>\n</div>\n```\n\n```js\nfindAndReplaceDOMText(document.getElementById('test'), {\n  find: 'amazing',\n  wrap: 'em'\n});\n```\n\nAfter:\n\n```html\n<div id=\"test\">\n  <p><em>ama</em></p><p><em>zing</em></p>\n</div>\n```\n\nThis is a useful feature for inline elements, but is undesirable in many other cases, so to stop it from happening you can choose to \"force a context\" on those particular elements. In this case we want to force a context on `<p>` elements:\n\n```js\nfindAndReplaceDOMText(document.getElementById('test'), {\n  find: 'amazing',\n  wrap: 'em',\n  forceContext: function(el) {\n    // Using https://developer.mozilla.org/en-US/docs/Web/API/Element/matches\n    return el.matches('p');\n  }\n});\n```\n\nInternally, the `prose` preset uses this feature:\n\n```js\nexposed.PRESETS = {\n  prose: {\n    forceContext: exposed.NON_INLINE_PROSE,\n    filterElements: function(el) {\n      return !hasOwn.call(exposed.NON_PROSE_ELEMENTS, el.nodeName.toLowerCase());\n    }\n  }\n};\n```\n\n### Changelog\n\n * 0.4.6 (5 Dec 2017): Fix indexInMatch ([See #60](https://github.com/padolsey/findAndReplaceDOMText/issues/60)). Fix undefined being echoed in optional+empty capture groups ([See #70](https://github.com/padolsey/findAndReplaceDOMText/issues/70)).\n * 0.4.4 (4 May 2015): Remove duplicate key from `NON_CONTIGUOUS_PROSE_ELEMENTS`. Expose library via UMD ([See #32](https://github.com/padolsey/findAndReplaceDOMText/issues/32)).\n * 0.4.3 (28 Apr 2015): Add `preset:prose` and `forceContext` features. [See #29](https://github.com/padolsey/findAndReplaceDOMText/issues/29).\n * 0.4.2 (30 Mar 2014): Fix IE to avoid incorrectly-closed-tags issue ([see #20](https://github.com/padolsey/findAndReplaceDOMText/issues/20)). Thanks to [shauryamal](https://github.com/shauryamal)!\n * 0.4.1 (11 Mar 2014): Fix portionMode:first phantom nodes (see [issue #19](https://github.com/padolsey/findAndReplaceDOMText/issues/19))\n * 0.4.0 (6 Oct 2013): Major API overhaul, including a new arg signature (`findAndReplaceDOMText(node, options)`, plus the ability to replace a match with text or wrap it with a DOM Node.\n * 0.3.0: Switch to semver, add node-filtering feature (as requested in [Issue #11](https://github.com/padolsey/findAndReplaceDOMText/issues/11)\n * 0.2: Fix case where regular expression contains word bounderies and add support for specifying a capture group to replace as the fourth argument to `findAndReplaceDOMText()` (see [issue #5](https://github.com/padolsey/findAndReplaceDOMText/issues/5))\n * 0.11: Minor fix: Make sure replacement node function is called in order of matches (see [issue #4](https://github.com/padolsey/findAndReplaceDOMText/issues/4))\n * 0.1: Initial commit + Fix for IE's broken HTML5 cloneNode ([pull request](https://github.com/padolsey/findAndReplaceDOMText/pull/3))\n\n### License\n\n```\nThis is free and unencumbered software released into the public domain.\n\nAnyone is free to copy, modify, publish, use, compile, sell, or\ndistribute this software, either in source code form or as a compiled\nbinary, for any purpose, commercial or non-commercial, and by any\nmeans.\n\nIn jurisdictions that recognize copyright laws, the author or authors\nof this software dedicate any and all copyright interest in the\nsoftware to the public domain. We make this dedication for the benefit\nof the public at large and to the detriment of our heirs and\nsuccessors. We intend this dedication to be an overt act of\nrelinquishment in perpetuity of all present and future rights to this\nsoftware under copyright law.\n\nTHE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND,\nEXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF\nMERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.\nIN NO EVENT SHALL THE AUTHORS BE LIABLE FOR ANY CLAIM, DAMAGES OR\nOTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE,\nARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR\nOTHER DEALINGS IN THE SOFTWARE.\n\nFor more information, please refer to <http://unlicense.org/>\n```\n","_attachments":{},"homepage":"https://github.com/sivan/findAndReplaceDOMText","bugs":{"url":"https://github.com/sivan/findAndReplaceDOMText/issues"},"license":"unlicense"}