This project was created using the TypeScript Library Starter project, whose local README provides additional information about the configuration of the project.
decorateDOMClasses(textClasses: string | string[], options: IDecorateHtmlOptions,
wordClass?: string, listeners?: IEventListeners,
container: Element | Document = document)
Parses the innerHTML of DOM elements with the specified classes, replacing instances of words
specified in the options.words argument with the replacement string specified in options.replace.
Handles HTML tags properly -- text will only be replaced in text, not in tags.
Allows '$1' in the replacement string so that 'word' with a replacement string
of <span>"$1"</span>
would be replaced with <span>"word"</span>
.
Adds the specified event handlers to all elements with the specified class, which will
correspond to each replaced word if the replacement string specifies an element with a class.
If this function is called multiple times on the same DOM node, it will create extraneous DOM element nesting and redundant addition of event listeners. It is best used in contexts where it can be called immediately after the HTML content is rendered.
textClasses
: string | string[] - a class or array of classes whose contents are to be decorated.getElementsByClassName()
, so multiple space-delimited classes are ANDed together, i.e. all classes must be present to match, while the array elements are ORed, i.e. matching any array element constitutes a match.options
:words
: string[] - a list of words to be decorated.replace
: string - the replacement string.wordClass
: string - the class used for the enclosing tag (e.g. 'cc-glossary-word')listeners
: IEventListeners - one or more { type, listener } tuplescontainer
: Element | Document - the scope within which to search for elements (defaults to the entire document)decorateHtml(input: string, options: IDecorateHtmlOptions)
Parses the specified HTML input, replacing instances of words specified in the
options.words argument with the replacement string specified in options.replace.
Handles HTML tags properly -- text will only be replaced in text, not in tags.
Allows '$1' in the replacement string so that 'word' with a replacement string
of <span>$1</span>
would be replaced with <span>word</span>
.
input
: the HTML to be decorated as a stringoptions
:words
: string[] - a list of words to be decorated.replace
: string - the replacement string.decorateReact(input: ReactNode, options: IDecorateReactOptions): ReactNode
Post-processes the specified React virtual DOM, replacing instances of words specified in the options.words argument with the replacement string specified in options.replace. Handles nested virtual DOM elements properly: text will only be replaced in text, not in tags.
While this function can be called directly, it is anticipated that for most clients either
decorateReactHOC()
, the higher-order component (HOC) wrapper, or DecorateChildren
, the
parent component that supports decorating its children, will be more convenient.
input
: the virtual DOM to be decoratedoptions
:words
: string[] - a list of words to be decorated.replace
: the string or virtual DOM element with which to replace each matched word.<span></span>
is treated like <span>$1</span>
.Event listeners can be included in the replace argument in typical React fashion, so the addEventListeners() and removeEventListeners() functions need/should not be called.
addEventListeners(className: string, listeners: IEventListeners, container: Element | Document = document)
removeEventListeners(className: string, listeners: IEventListeners,container: Element | Document = document)
Since decorateHtml()
is simply performing string replacement operations,
it cannot add or remove any event handlers. Once the resulting HTML
has been added to the DOM, addEventListeners()
can be called to
add handlers for 'click' or other events and the removeEventListeners()
function can be used to remove those same event handlers.
className
: string - the class used for the enclosing tag (e.g. 'cc-glossary-word')listeners
: IEventListeners - one or more { type, listener } tuplescontainer
: Element | Document - the scope within which to search for elements (defaults to the entire document)decorateReactHOC(options: IDecorateReactOptions)
Higher-order component which can be used to wrap another component, decorating text within the wrapped component.
Discussion of "render highjacking" in a higher-order component using the "inheritance inversion" technique used here.
Discussion of TypeScript types for higher-order components.
Usage:
class MyClass {
render() { ... }
}
export default decorateReactHOC(options)(MyClass);
<DecorateChildren decorateOptions={...}> {...children...} </DecorateChildren>
React component which decorates any text among its children.
Generated using TypeDoc