Show Slur Metadata Feature

Show Slur Metadata on hover

Details about the feature - https://github.com/tattle-made/Uli/issues/544

The broader goal of the feature is to show relevant metadata associated with a slur word, when the user hovers on a slur.

The main logic and code of this feature can be found in browser-extension/plugin/src/transform-general.js and browser-extension/plugin/src/slur-metadata.js

Detailed Documentation for processNewlyAddedNodesGeneral2 and Associated Functions

The main objective is to detect slurs on a webpage, inject Uli icons next to them, and display relevant metadata on hover, sourced from a slur_metadata.json file.

Here’s a breakdown of the code and how each part works:

---

Main Function: processNewlyAddedNodesGeneral2

Purpose: This is the primary function that processes newly added nodes when the user enables the "Enable Slur Metadata" functionality from the frontend. The function identifies and processes text nodes in the firstBody of the document and injects icons and metadata next to any detected slurs.

Workflow:

1. Target Words List:
   • targetWords is an array of slurs to be identified on the webpage. You can either hardcode the list (as shown) or import it from an external source (like slurList).
2. uliStore:
   • An array to store all valid text nodes from the document. These nodes will later be checked for slurs.
3. Get All Text Nodes:
   • The function getAllTextNodes is called with the body of the document (firstBody). It collects all text nodes (i.e., content within HTML elements) and pushes them into uliStore.
4. Locate and Highlight Slurs:
   • The locateSlur function is then called, which scans the text nodes in uliStore for any slur from the targetWords list. If found, it injects a span element with a Uli icon next to the slur and updates the text node with this new HTML structure.
5. Metadata Injection:
   • The addMetaData function is invoked, which searches for the injected span elements and adds hoverable metadata (sourced from slur_metadata.json) next to each slur.

Function Breakdown:

1. getAllTextNodes(node, uliStore)

Purpose: Recursively collects all text nodes (non-empty) under a specified HTML node.

• Node Traversal:
  • The function recursively goes through every child node of the provided parent node (firstBody in this case).
  • If a text node (nodeType === 3) is found, it checks if it contains only whitespace characters. If valid, the node and its parent are stored in uliStore.
• Check for Empty/Whitespace Text:
  • checkFalseTextNode ensures that text nodes with only whitespace (\n, , or \t) are excluded.

2. locateSlur(uliStore, targetWords)

Purpose: Searches through the text nodes in uliStore to identify slur words. If a slur is found, the text is modified to include a span with a Uli icon and metadata.

• Find Slur Locations:
  • findPositions function checks if the slur (from targetWords) is present in the text. If found, it stores the positions of the slur in the text node.
• Inject Icons:
  • If a slur is found in the text node, the function creates a span element and injects it next to the slur.
  • The slur and the span are wrapped inside a tempParent (a span element), so it doesn’t affect the layout or styling of the webpage.
• Replace the Text Node:
  • After injecting the Uli icon, the original text node is replaced with the new span that includes the slur and its corresponding Uli icon.

3. addMetaData(targetWords)

Purpose: Once the slurs are highlighted, this function adds metadata to the slur words, which appears on hover over the Uli icon.

• Find and Iterate Over Injected Elements:
  • It selects all the span elements injected by the locateSlur function using the class name format icon-container-{targetWord}.
• Create and Style Metadata:
  • For each detected slur, the function creates a sup element containing an image (the Uli icon) and a hidden span for the metadata.
  • The metadata span contains information such as Level of Severity, Categories, and reasons why the slur is problematic, which is fetched from the slur_metadata.json.
• Show/Hide Metadata on Hover:
  • Event listeners are attached to the Uli icons. When the user hovers over the icon (mouseover), the hidden metadata span is shown. When the hover ends (mouseout), the metadata is hidden again.

4. findPositions(word, text)

Purpose: Finds the positions of a specific word (slur) within a given text.

• Functionality:
  • It uses indexOf to search for the slur in the text and returns an object that holds the slur word and its location in the text.
  • The function keeps searching for multiple instances of the word and stores all the positions in an array.

---

Summary of Operations:

1. Text Node Collection: The entire webpage is scanned, and text nodes are gathered and stored in uliStore.
2. Slur Detection: The function checks each text node for any slur words present in the targetWords list.
3. Icon Insertion: For each slur found, a span element containing the slur and a Uli icon is injected into the HTML.
4. Metadata Attachment: Metadata related to each slur (retrieved from slur_metadata.json) is added, and this metadata is shown when the user hovers over the Uli icon.

This code efficiently modifies the webpage content, injecting icons and metadata dynamically without affecting the overall layout.

Running Tests for for Enable Slur Metadata functions

cd browser-extension/plugin
npm run test:api \-t 'enable'