Text Decorator

This project was created using the TypeScript Library Starter project, whose local README provides additional information about the configuration of the project.

$3

- HTML Demo
- DOM Demo
- React Demo

$3

https://concord-consortium.github.io/text-decorator/docs/

API

$3

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 "$1" would be replaced with "word".
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.
- The individual array elements are passed to 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.
- Word-matching is case-insensitive.
- The words can include limited RegExp functionality:
- '.' - represents a wildcard character ('*' is not supported)
- '?' - makes the previous character optional
- '[', ']' - represents a set of possible characters, e.g. [aeiou] for a vowel
- replace: string - the replacement string.
- Can include '$1' representing the matched word.
- wordClass: string - the class used for the enclosing tag (e.g. 'cc-glossary-word')
- listeners: IEventListeners - one or more { type, listener } tuples
- container: Element | Document - the scope within which to search for elements (defaults to the entire document)

$3

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 $1 would be replaced with word.

- input: the HTML to be decorated as a string
- options:
- words: string[] - a list of words to be decorated.
- Word-matching is case-insensitive.
- The words can include limited RegExp functionality:
- '.' - represents a wildcard character ('*' is not supported)
- '?' - makes the previous character optional
- '[', ']' - represents a set of possible characters, e.g. [aeiou] for a vowel
- replace: string - the replacement string.
- Can include '$1' representing the matched word.

$3

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 decorated
- options:
- words: string[] - a list of words to be decorated.
- Word-matching is case-insensitive.
- The words can include limited RegExp functionality:
- '.' - represents a wildcard character ('*' is not supported)
- '?' - makes the previous character optional
- '[', ']' - represents a set of possible characters, e.g. [aeiou] for a vowel
- replace: the string or virtual DOM element with which to replace each matched word.
- The replace element can be coded in JSX/TSX.
- The replacement can include '$1' representing the matched word.
- If the replacement is a single empty element without a '$1', the '$1' is inferred,
i.e. is treated like $1.

Event listeners can be included in the replace argument in typical React fashion, so
the addEventListeners() and removeEventListeners() functions need/should not be called.

$3

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 } tuples
- container: Element | Document - the scope within which to search for elements (defaults to the entire document)

$3

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:
``javascript
class MyClass {
render() { ... }
}
export default decorateReactHOC(options)(MyClass);
`


$3


{...children...} `

React component which decorates any text among its children.
- decorateOptions must be passed in props.
- See Appendix B for discussion of parent component versus higher-order component wrapper.