Search and Highlight Words on a Page

This tutorial shows you how to build with PixieBrix and will help you level up your development skills. We'll build a mod that notifies you if specific words are found on a page.

You'll learn how to:

• Create mods with options that can be customized by the activating user

• Work with JavaScript in PixieBrix

• Display alerts during mod runs

• Interact with elements on a page, like highlighting text

• Set logic and control flow paths within your mod

• Use loops to iterate through items

This tutorial should take about 15 minutes. If you have any questions, click the purple live chat button in the bottom left corner or reach out to support.

If you get stuck and cannot move forward, activate this mod to see the final solution. Follow these docs if you need help Activating Mods.

PreReqs

Before starting this tutorial, please make sure you have:

• a PixieBrix account (create a free one)

• the Page Editor open (how?)

• completed the Basic Translation Tutorial

At the end of each step, you'll see a 🏁 Checkpoint to know if you're ready to move to the next step. A screenshot will indicate how you should have configured the brick for that step.

You're ready to start when you have the Page Editor open, and your screen looks something like this:

Prefer to watch?

This video walks through the steps on this page to give you a visual walkthrough of completing this tutorial.

If you prefer the text over the video, keep reading!

Step 1: Configure the Trigger starter brick

Every mod starts with a starter brick, which determines how and when the mod is launched or initiated. For this tutorial, we'll use the Trigger brick because we want to take action every time a page loads.

1.1 Click the New Mod button in the top left corner of the Page Editor and choose Trigger

To find starter bricks, you'll click the New Mod button in the top left corner, next to the purple Home icon.

Choose Trigger, and you'll see your Page Editor fill a new mod in the first panel (Mod Listing Panel), a brick in the second panel ( Brick Actions Panel), and configuration options for the selected brick in the third panel (Brick Configuration Panel).

1.2 Configure the Trigger brick with a name and set it to run on any page.

We'll want to make a few changes to the Trigger brick to be clear about what's happening and run most optimally.

Follow this table to see the fields we're updating and why:

Field name	Value	🤔 Why?
Name	Search for words on a page	This name is what appears in the Mod Listing Panel, helping you identify which mod you're working on.
Sites	Click All URLs and Remove the standalone site by clicking ABC then X Remove	This allows the mod to run on every site. If you only want a mod to run on specific sites or domains, you can set those values here.

🏁 Checkpoint

You're ready to move forward when your Trigger brick looks like this:

Step 2: Get text from the page

Next, we'll want to get the text from the page to run against our search words.

2.1 Add the Extract from Page brick

Click the + button below the Trigger brick and search for Extract from Page in the modal that appears.

Hover over the brick and click the blue Add button. You'll see the brick appear in your Brick Actions Panel.

2.2 Set the property to `text` and use the `body` selector

To scrape all the text from a given page, we'll rename the property to text and set the Selector field to body.

You will notice the browser becomes highlighted with a light purple when you type body in the Selector field. This lets you preview what the Selector finds.

2.3 Run the mod by clicking Run Trigger to check your output in the Data Panel

Click the Run Trigger button in the top right corner of the Page Editor. Your mod will run the bricks, showing a green check mark on each brick with a successful run.

You'll also notice that a new variable appears in the Output tab of the last panel, the Data Panel. Click the caret in front of the object to expand and preview the scraped text from the page.

🏁 Checkpoint

You're ready to move to the next step when your Extract from Page brick produces output with the text on the page, like in the above screenshot.

Step 3: Add to a mod package and create a config option

Next, we'll want to specify the keywords or phrases we want PixieBrix to search for on the given page. We could hard code those words, but to make this mod dynamic for each user, we'll create configuration options that each user can set when they activate the mod.

This means that when I activate the mod, I can set terms like pixiebrix,tutorials and you can set something like learning,games and the mod will work for both of us without requiring any changes in the Page Editor!

3.1 Click the three dots on a mod listing and choose Add to mod

Technically what we're working on thus far is a mod component. You can have multiple mod components work together and put them in a mod package.

To add a mod to a package, click the three dots on the Search for words on a page mod in the Mod Listing Panel.

3.2 Choose Create new mod from the dropdown, and click Move.

In the modal that appears, select the Create new mod... option from the dropdown, then click the blue Move button.

3.3 Set an alias if you haven't already, adjust the description, and click Create.

If this is your first time packaging a mod, you might be asked to set an alias. You can think of this as a username. It's what will appear at the beginning of your mod ID.

Once you've set an alias, you'll see a Create new mod modal. Feel free to adjust these fields, or leave them as is.

You can't change a mod's ID after it's been created, but you can change the Name and Description and increment the version later.

Once you're happy with the settings, click the blue Create button.

3.4 Click the top-level Mod Package and choose Input Form in the middle panel

Once you clicked Create, you might have noticed that you now have a folder in your Mod Listing Panel, with a mod nested underneath it.

To configure settings and details for the mod package, you'll need to select the top-level mod (look for the folder icon!).

Once selected, you can use the tabs in the middle panel to make edits to the mod metadata, or set configuration options by going to Input Form.

3.5 Create a field to capture a string of words and phrases

The Input Form section allows you to set configuration data that must be set when someone activates the mod. This allows you to do anything from specify a Google Sheet to fetch data from, choose a database to store information in, or in this case, set a string of text that will be used throughout the mod.

You can think of these as constants that are set for each user who will be using the mod, and the user only has to set the option when they first activate the mod.

We want to add a field to capture a comma-separated string of any words or phrases a user may want to search on a page.

Click the + Add new field button and set the following values:

Field	Value	🤔 Why?
Name	words	This is how you'll refer to the value inside the mod. For instance, using @options.words will return the value of whatever the current user has set in this field when they activated the mod.
Label	Keywords	A user-friendly description of what this option is used for. It will appear above the field.
Field Description	Add keywords and phrases separated by commas, no spaces needed.	More details about what to put in this field. Can be helpful to give more details to users, and accepts Markdown if you want to link to additional documentation or examples.
Input Type	Single line text (default)	You can choose from a variety of inputs, including dates, dates with time, and even files and Google Sheets. Check the dropdown to explore the options.
Default Value	pixiebrix,PixieBrix	Setting a default value can help users quickly activate a mod and see how it works if they don't understand a field. The user can always re-activate a mod and replace the default to their own text.

🏁 Checkpoint

You're ready to move to the next step when your Input Form looks like this:

Step 4: Set your current inputs and save the mod

Before we go back into the mod component, we want to set our current input of text so we have something to work with inside the mod.

4.1 Click the Current Inputs tab in the middle panel

Make sure you still have the top-level mod selected (confirm this in the Mod Listing Panel), and choose the Current Inputs tab in the middle panel.

4.2 Type some words or phrases in the Keywords field

Click the Keywords field and it will suddenly populate with the default values we set (pixiebrix,PixieBrix).

You can leave this as is or type something else.

4.3 Click the save icon in the Mod Listing Panel to save the mod

Click the Save icon on the Mod Package in the first panel to save the mod changes, including the Current Inputs.

You'll see a modal asking you to confirm. Click Save.

🏁 Checkpoint

You're ready to move to the next step when you go to your Current Inputs tab and see text in the Keywords field.

Step 5: Create an array of the string from words in config

Now it's time to ask JavaScript to help us transform some data. Specifically, we'll want to take the string from the configuration options we set and create an array of the words and terms that were provided between commas.

5.1 Add the Run JavaScript Function brick

Go back into the Search for words on a page mod inside the mod package. (You'll know you're back in the mod when the selected mod is the one with a lightning bolt, which is the icon for the Trigger brick.)

Click the + button under the Extract from Page brick, and search for JavaScript then choose the Run JavaScript Function brick.

5.2 Adjust the Function field with a function for transforming the data

Replace the text inside the function field with the following:

function (args) {
  const { words } = args;
   return words.split(',').map(function(item) {
        return item.trim();
    });

}

This is a function that will take a string (words) and split it based on the comma, and create an array of strings, removing any whitespace.

For example, if wordsis "pixiebrix,PixieBrix" this function will return ["pixiebrix","PixieBrix"], which will allow us to iterate over each word in future steps.

5.3 Create the words argument and set the value to @options.words

Below the function, you'll pass arguments that you access inside the function. In this example, we need to pass the words argument.

Replace the default argument x with words and set the value to @options.words. This will reference the configuration setting that a user has set when activating the mod.

(Scroll to the screenshot in the 🏁 checkpoint section below if you need a visual of what this will look like.)

5.4 Change the Output value to words instead of output

To make it easier to reference this array in other bricks, update the Output field at the top of the JavaScript brick to words instead of output.

5.5 Run the mod to confirm your function works as expected

Click the Run Trigger button in the top right of the Page Editor to run the mod and confirm the output of your function is an array of the strings.

🏁 Checkpoint

You're ready to move to the next step when your Run JavaScript Function brick looks like this:

Step 6: Search text on the page

Now we'll use the Search Text brick to check the extracted body of text again the array with words.

6.1 Add the Search Text brick

Click the + button below the Run JavaScript Function and search for the Search Text brick. Hover over the brick and click the Add button to add it to your pipeline.

6.2 Set the Text value to @data.text

The Text field is where you specify what text is to be searched. In this case, we want to share the scraped body text.

Update the Text field to @data.text, which will reference the text PixieBrix scraped from the page body in the Extract from Page brick.

6.3 Set the Query value to @words

The Query field specifies what is being searched. In this case, we want to search multiple words or phrases, which we processed in Step 5 with the JavaScript brick.

Update the Query field with @words

6.4 Run the mod to confirm the output is expected

Once more, click the Run Trigger button at the top right corner of the Page Editor, and look in the Output tab. You should see an object called @matches and inside of that is an array with an object for each match.

Your @matches.matches array may be empty if your terms were not actually found on the page. If no items are in the array, confirm they do not appear on the page.

🏁 Checkpoint

You're ready to move to the next step when your Search Text brick looks like this:

Step 7: Display different alerts if its found or not

Now we will use Control Flow to perform different actions whether there is a match or not.

7.1 Add the If/Else brick

Click the + button below the Search Text brick and add the If-Else brick.

7.2 Update the Step Name to "Alert if matches found"

Although not required, setting the Step Name can clarify the action for future developers who may edit this mod.

We'll update the Step Name to Alert if matches found.

7.2 Set the condition to {{ true if @matches.matches | length > 0 }}

You might have noticed when you added the If-Else brick, subsections were added to your Brick Actions Panel. (We call these subsections pipelines.)

The Condition field evaluates a true or false statement. If the value returns true, any bricks added to the if pipeline will run.

When the condition is not met and is not true, any bricks added to the else pipeline.

Update the Condition field to {{ true if @matches.matches | length > 0 }}, which will check if any items are in the matches array, meaning one of the words or phrases was found on the page. It will then execute any bricks in the if pipeline.

If the array is empty (has a length of 0), then this will evaluate false and execute any bricks added in the else pipeline.

7.3 Add the Window Alert brick in the if pipeline

Click the + button just below the if and above the else in the Brick Actions Panel.

Search for the Window Alert brick, and add it.

Update the Alert message to say Matches found.

Optional: Change the alert type to successto change the styling of the alert.

7.4 Copy the Window Alert brick and paste it in the else pipeline

While the Window Alert brick is selected, click the copy button at the top of the Brick Actions Panel.

You'll see the Brick Actions Panel add paste buttons between the existing bricks. Click the paste button inside the else pipeline to paste the brick in there.

7.5 Adjust the alert message to say No matches were found

Since this brick is in the else pipeline, this message will be displayed when no matches are found.

Adjust the text in the Alert message to No matches found.

Optional: change the Alert type to warning.

7.6 Run the mod to view the alerts

Whether your terms show up on the page or not, you should see an alert indicating whether they exist.

Click the Run Trigger button in the top right of the Page Editor, and confirm the browser displays an alert.

🏁 Checkpoint

You're ready to move to the next step when your Brick Actions Pipeline contains bricks in the if and else pipelines.

Step 8: Use a for loop to highlight each word on a page

For the last building step, we'll add a brick that interacts with the page to highlight the specified words if they appear on the page.

8.1 Add the For-Each Loop brick

Click the + button below the If-Else brick.

Search for the For-Each Loop brick, hover over it, and click Add.

8.2 Update the Step Name for clarity

Since we updated the If-Else brick's name to explain what was happening, let's do that for this brick as well.

Replace the Step Name field at the top of the brick with For each word in the list, highlight all instances on a page

8.3 Set the Elements variable to @words

The Elements field determines the number of times you iterate. This brick will run as many times as items are in the array. (If there are 3 items, the brick will run 3 times.)

Click the a,b,c at the end of the Elements field and choose @

Set the value to @words

8.4 Change the Elements Key to word

The key is what you'll use to reference the specific item in the array, in this case, the word.

Set it to word so it's clear.

8.5 Add the highlight text brick inside the body pipeline

When adding a For Each Loop brick, you'll see another pipeline appear in your Brick Actions Panel, this one called body. Any bricks added to the body will execute for each item in the provided array.

Click the + button inside this pipeline and add the Highlight Text brick.

Set the Pattern field to @word which is the current string in the iteration.

Optional: change the color to another option in the dropdown list.

8.6 Run the mod and confirm your words are highlighted on the page

Run the mod once more by clicking the Run Trigger button in the top right corner.

You should see your words highlighted on the page!

Step 9: Save the mod and share

Time to save the mod, and share with a friend.

9.1 Save the mod

Click the save icon in the Mod Listings Panel, and close the Page Editor.

You can now use your mod on any webpage and view alerts and highlighted text based on your configured words.

9.2 Open the Extension Console

You'll need to go to the Extension Console to share the mod.

Click the PixieBrix icon in your URL bar and then click the gear icon in the top right of the sidebar.

9.3 View your active mods and click the three dots on the Search for words on a page mod

You'll arrive at the Mods page when you go to the Extension Console.

Select the Active filter if it's not already set, and you should see a list of any mods you have activated, such as the one you just built.

Click the three dots at the end of the row to open an action menu. Choose the Share with Teams action.

9.4 Create or select a team, copy the link below, then Save and Close

In the modal that appears, select a team from the dropdown, or create a team if you haven't already.

Copy the link at the bottom of the modal, which you'll send to your team to activate and set their configuration options.

Finally, click the purple Save and Close button.

When you send that activation link to your team, they'll activate and set their keywords when activating the mod.

Once they've set keywords, they'll click Activate, and be able to use this mod without ever opening the Page Editor.

🏁 Checkpoint

You did it! You've completed the tutorial if you see your keywords highlighted on a page and a window alert letting you know if those words are found on the page.

If it's not working, you can activate this template to see how it should be structured, and compare your build to the template mod. You can also reach out to our support team or click the live chat button in the bottom left corner of this page.