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 Add button in the top left corner of the Page Editor and choose Trigger
To find starter bricks, you'll click the Add 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:
🏁 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:
🏁 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:
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 words
is "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 success
to 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.
Last updated