text-annotator

# text-annotator ## News We released a new version of text-annotator: [text-annotator-v2](https://www.npmjs.com/package/text-annotator-v2), with some improvements and breaking changes. We will still maintain this library here and it still works in our product stably. But you are welcome to try text-annotator-v2 which is supposed to be [more robust and lightweight](https://www.npmjs.com/package/text-annotator-v2#comparing-text-annotator-v2-and-text-annotator). ## Introduction text-annotator is a JavaScript library for annotating plain text in the HTML. The annotation process is: 1. **Search**: Search for a piece of plain text in the HTML; if finding it, store its location identified by an index and then return the index for later annotation 2. **Annotate**: Annotate the found text given its index It can be seen that in order to annotate a piece of text, two steps, **search** and **annotate**, are taken. The idea of decomposing the annotation process into the two steps is to allow more flexibility, e.g., the user can search for all pieces of text first, and then annotate them later when required (e.g., when clicking a button). There is also a function combining the two steps, as can be seen in the **An example of the usage** section. *text-annotator* can be used in the browser or the Node.js server. ## Import ### install it via npm `npm install --save text-annotator` ```javascript import TextAnnotator from 'text-annotator' ``` ### include it into the head tag ``` <script src="public/js/text-annotator.min.js"></script> ``` ## An example of the usage ```javascript // below is the HTML /* <div id="content"> Europe PMC is an open science platform that enables access to a worldwide collection of life science publications and preprints from trusted sources around the globe. Europe PMC is developed by EMBL-EBI. It is a partner of PubMed Central and a repository of choice for many international science funders. </div> */ // create an instance of TextAnnotator // content is the HTML string within which a piece of text can be annotated var annotator = new TextAnnotator({content: document.getElementById('content').innerHTML}) // search for 'EMBL-EBI' in the HTML // if found, store the location of 'EMBL-EBI' and then return the index; otherwise return -1 var highlightIndex = annotator.search('EMBL-EBI') // highlightIndex = 0 // annotate 'EMBL-EBI' in the HTML if (highlightIndex !== -1) { document.getElementById('content').innerHTML = annotator.highlight(highlightIndex) // is used to annotate 'EMBL-EBI', see below /* <div id="content"> Europe PMC is an open science platform that enables access to a worldwide collection of life science publications and preprints from trusted sources around the globe. Europe PMC is developed by EMBL-EBI. It is a partner of PubMed Central and a repository of choice for many international science funders. </div> */ } // search for all occurances of 'Europe PMC' in the HTML var highlightIndexes = annotator.searchAll('Europe PMC') // highlightIndexes = [1, 2] // annotate all the found occurances of 'Europe PMC' given their indexes if (highlightIndexes.length) { document.getElementById('content').innerHTML = annotator.highlightAll(highlightIndexes) // and are used to annotate 'Europe PMC', see below /* <div id="content"> Europe PMC is an open science platform that enables access to a worldwide collection of life science publications and preprints from trusted sources around the globe. Europe PMC is developed by EMBL-EBI. It is a partner of PubMed Central and a repository of choice for many international science funders. </div> */ } // search for and then annotate 'a partner of PubMed Central' document.getElementById('content').innerHTML = annotator.searchAndHighlight('a partner of PubMed Central') // searchAndHighlight returns { content, highlightIndex } // is used to annotate 'a partner of PubMed Central', see below /* <div id="content"> Europe PMC is an open science platform that enables access to a worldwide collection of life science publications and preprints from trusted sources around the globe. Europe PMC is developed by EMBL-EBI. It is a partner of PubMed Central and a repository of choice for many international science funders. </div> */ // remove annotation 'EMBL-EBI' given its index // the index is 0 as shown above document.getElementById('content').innerHTML = annotator.unhighlight(highlightIndex) // annotation is removed, see below /* <div id="content"> Europe PMC is an open science platform that enables access to a worldwide collection of life science publications and preprints from trusted sources around the globe. Europe PMC is developed by EMBL-EBI. It is a partner of PubMed Central and a repository of choice for many international science funders. </div> */ // help annotate one occurance of 'science' - the one within 'international science funders', by providing the prefix and postfix of 'Europe PMC' var highlightIndex = annotator.search('science', { prefix: 'international ', postfix: ' funders' }) if (highlightIndex !== -1) { document.getElementById('content').innerHTML = annotator.highlight(highlightIndex) } // is used to annotate 'science' within 'international science funders', see below /* <div id="content"> Europe PMC is an open science platform that enables access to a worldwide collection of life science publications and preprints from trusted sources around the globe. Europe PMC is developed by EMBL-EBI. It is a partner of PubMed Central and a repository of choice for many international science funders. </div> */ ``` ## Constructor #### new TextAnnotator(*options = {content}*) | Prop | Type | Description | | ---- | ---- | ---- | | content | string | The HTML string within which a piece of text can be annotated. | ## Search APIs #### search(str, *options = {trim, caseSensitive, prefix, postfix}*) #### searchAll(str, *options = {trim, caseSensitive, prefix, postfix}*) | Prop | Type | Description | | ---- | ---- | ---- | | trim | boolean | Whether to trim the piece of text to be annotated. Default is *true*. | | caseSensitive | boolean | Whether to consider case in search. Default is *false*. | | prefix | string | A string BEFORE the piece of text to be annotated. Default is ''. | | postfix | string | A string AFTER the piece of text to be annotated. Default is ''. | ## Annotation APIs #### highlight(highlightIndex, *options = {highlightTagName, highlightClass, highlightIdPattern}*) #### highlightAll(highlightIndexes, *options = {highlightTagName, highlightClass, highlightIdPattern}*) #### unhighlight(highlightIndex, *options = {highlightTagName, highlightClass, highlightIdPattern}*) | Prop | Type | Description | | ---- | ---- | ---- | | highlightTagName | string | The name of the annotation tag. Default is *span* so that the tag is **. | | highlightClass | string | The class name of the annotation tag. Default is *highlight* so that the tag is **. | | highlightIdPattern | string | The ID pattern of the annotation tag. Default is *highlight-* so that the tag is **. | ## searchAndHighlight API *searchAndHighlight(str, **options**)*, where *options = { searchOptions, highlightOptions }*, *searchOptions* and *highlightOptions* are described above in the Annotation options table. ## Examples from Europe PMC text-annotator has been widely used in [Europe PMC](https://europepmc.org "Europe PMC"), an open science platform that enables access to a worldwide collection of life science publications. Here is a list of examples: 1. Article title highlighting: https://europepmc.org/search?query=cancer !["Article title highlighting" "Article title highlighting"](https://raw.githubusercontent.com/zhan-huang/assets/master/text-annotator/example.JPG) 2. Snippets: https://europepmc.org/article/PPR/PPR158972 (Visit from https://europepmc.org/search?query=cancer) !["Snippets" "Snippets"](https://raw.githubusercontent.com/zhan-huang/assets/master/text-annotator/example2.JPG) 3. SciLite: https://europepmc.org/article/PPR/PPR158972 (Click the Annotations link in the right panel) !["SciLite" "SciLite"](https://raw.githubusercontent.com/zhan-huang/assets/master/text-annotator/example3.JPG) 4. Linkback: https://europepmc.org/article/PPR/PPR158972#europepmc-6e6312219dcad15c9a7dda8f71dce9af (In the popup shown in Example 3, click "Share" to get this linkback URL) !["Linkback" "Linkback"](https://raw.githubusercontent.com/zhan-huang/assets/master/text-annotator/example4.JPG) ## Contact [Zhan Huang](mailto:z2hm@outlook.com "Zhan Huang")