Walkthrough: How to Build a Custom Sidebar Mod with PixieBrix

Sidebar extensions are becoming very popular: let's build one together. This extension fetches data on any soccer player from a public sports API and visualizes it in the sidebar.

Walkthrough: How to Build a Custom Sidebar Mod with PixieBrix

When you’re in the zone, productively working away at your next task or project, the last thing you want to do is break your rhythm by jumping into a new tab or Google search. Wouldn’t it be nice if the information you needed came right to you instead? That’s the idea behind sidebar mods.

A sidebar mod brings information onto whatever page you’re currently looking at. You can stay put while the mod pulls data from an API and displays it on the side of your window.

There are an infinite number of ways to use a sidebar mod—both work and non-work related. And while there are many great pre-built mods out there, PixieBrix allows you to build a sidebar mod to meet your specific use case.

We’ve put together a walkthrough that breaks down exactly how to build a sidebar mod. In our example, we build a mod that pulls in information about professional soccer players, including statistics and photograph, visualizing it in your sidebar. This video shows the example mod in action:

The walkthrough will cover the following elements:

  • Setting up the mod so it is triggered when you highlight a player’s name with your mouse
  • Setting up an HTTP GET request, which will pull all the data relevant to the player
  • Modifying that data with a jq filter expression
  • Storing the player data into the PixieBrix page state, before retrieving it again and displaying it on the sidebar.

Let’s dive in:

Sign up for PixieBrix

Much like you need to plug in your computer before turning it on, you need to create your PixieBrix account before building a mod. Don’t worry, it’s not hard to do! Authenticate your account through Google or Microsoft and pick the plan that works for you (there is a free plan if you want to jump right in).

Once you’re signed up, you’ll want to install the PixieBrix browser extension. Then you can start building.

Step 1: Add a new "Quick Bar" brick

From any website, right click and select “inspect” from the menu that appears. Scroll through the inspect menu options until you see the PixieBrix Page Editor and open it up.


To build this sidebar mod, you'll actually need to build two PixieBrix mods. As with most awesome PixieBrix mods, you’ll need to start by adding a new Quickbar brick. This brick allows you to trigger your mod using a keyboard shortcut that you define.

Check this documentation page to understand how you can configure the quickbar on your own browser

After adding the quickbar brick from the Add menu, configure it like this:

  • Mod Name: Football Player Search
  • Action Title: Find this Football player
  • Sites: click on All URLs

Then under Advanced:

  • Icon: globe

Step 2: Add a new "Hide Sidebar" brick

Now add a brick called Hide Sidebar so that you can reset the sidebar mod if it's already open.

Luckily this brick has no configurations, so you can move right onto the next brick.

Step 3: Add a new "HTTP request" brick

This brick allows you to perform an HTTP request (of any kind) to an endpoint to get some information.

Once you’ve added it, change the output key variable to @response.

You’re also going to need to configure the rest of the brick as follows:

  • url: Enter whatever API you want to use for your mod. In the case of our soccer example, the url was  https://www.thesportsdb.com/api/v1/json/2/searchplayers.php?p={{@input.selectionText}}
  • method: get

This passes the variable @input.selectionText as a parameter to the url.

The reason you need to do this is because in this GET request the endpoint expects the name of the player to be passed on as a parameter p—that’s the p?={{@input.selectionText}} part.

Step 4: Add the "JQ - JSON processor" brick

Go ahead and add the jq - JSON processor brick.

Rename the output variable to be @expr. Then configure the rest of the brick like this:

  • filter: **. | . + {socials:[.strTwitter, .strFacebook, .strInstagram]} | del(.strTwitter, .strInstagram, .strFacebook) | [.]**
  • data: **@response.player[0]**

You might be wondering—what does this filter do?

First it takes the data from @response.player[0] and appends an object that is composed of all the social media profiles for the player that you’re querying.

The social media links are stored as an array. This is a requirement to display these links in your mod.

Finally, the filter deletes the social media links from the main object using the del() function in jq so that you don’t have duplicate/confusing entries in the data object.

jq expression

Step 5: Add the "Set shared page state" brick

This fifth brick allows the mod to store player data inside the state so you can use it in the sidebar.

Once you'd added this brick, configure it by changing just one input:

  • data: @expr[0]

This passes the @ variable from the previous block to this brick so you can store it in the page’s state—until the page is refreshed the value stored in @expr[0] will be available to you in any mod running on the page.

Step 6: Add a "Show sidebar" brick

To close out this first mod, add the Show sidebar brick which does exactly what the name says and pops open the sidebar.

Now it's time to build the sidebar panel mod and customize it to display the data retrieved by what you've just built.

Step 7: Add a new "Sidebar Panel" mod

Starting back at the Page Editor, add a brand new Sidebar Panel mod.

Configure it as follows:

  • Mod Name: Player SidePanel
  • Heading: Player Data

Then under advanced:

  • Sites: All URLs

This will make sure you can open the named side panel on any and every website.

Step 8: Add a new "Get shared page state" brick

If you remember, in step 5 you stored the state of the execution in the page’s state.

This allows you to run a mod on a certain page and store the output of any specified brick so that this output can be used by other mods. This is useful for example when you are pulling data by querying an API endpoint with a parameter, which then gives you back some new data  like in our case.

This way we can store the data in the page’s memory - now however we have to retrieve this stored data.

This is where the Get shared page state  brick comes into play. Let’s add it - then change its output variable name to **@state**

Additionally, this brick does not require any additional configuration changes.

— Interlude —

If you test what you've built so far by highlighting a soccer player name online, you'll see PixieBrix doing some things in the background:

  1. Reading your highlighted player name from the page
  2. Querying an API
  3. Modifying the API response
  4. Storing it in the page’s state
  5. Opening the sidebar

In the next part you’re going to customize the sidebar to make it look useful!

Step 9: Add a new "Parse date" brick

You'll want to parse some of the data returned by the API (the data that we have in our state). To do so add the Parse date brick.

For the Date input field we’re going to give it **@state.dateBorn** as its input.

The value of this variable contains a date. Using the Parse date brick you can alter this date to match your local date format. In the following steps you’re going to use this parsed date in the rendered sidebar.

Step 10: Add a new "JQ - JSON processor" brick

To process your state data a little go ahead and add the JQ - JSON processor brick again.

With this jq brick you want to wrap the state from step 8 into an array so that you can use this array in the next step.

To achieve this you’re going to configure this brick like so:

  • filter: [.]
  • data: @state

Now onto the last step!

Step 11: Add a new "Render Document" brick

This is a long step, but it's an impactful one!

First of all add the brick named Render Document to your mod

Once you add this brick you'll be able to see in the Preview Data panel (on the top right of the Page Editor, under the Render Panel button).

render document brick

Now highlight the penultimate box as shown in the picture below.


Once you see this, click on the red border and it'll become blue. Then you'll see a button called Remove Element appear in the Page Editor.

Click it to remove all the scaffolding that comes by default with the page editor.

Now the Page Editor will show you only having a body container.

Add a Header 1

Click on the three dot menu and select Header 1.

customization of the sidebar

You will see a big block of text in bold called Header appear**.**

Click it to activate it.

Change the title of the header to **{{@state.strPlayer}}**

This will create a header containing the name of the player as its value.

customize the title

Add a Header 2

Click the three dot menu again and this time select Header 2.

Then after clicking it to activate it, configure it as follows:

  • title: **đź‘• {{@state.strNumber}}**

The emoji is used to indicate the jersey of the player and the variable retrieves the jersey number of the player in question that was stored in the page’s state. Obviously you can customize this for your own mod.

customize the h2 title

Add a paragraph of text

From the three dot menu, select Text.

This adds a paragraph of text that you can customize. Click to activate it.

Then configure it:

  • Text: A soccer player born in {{@state.strBirthLocation}} on {{@parsedDate.local.date}}

Here, you’re using variables to create a dynamic paragraph of text that pulls some dynamic data such as the location of birth of the player and the parsed date data that we have pulled earlier in step 9.

customize the text

Add a block

Back to the three dot menu, now add a Block.

A block in the Render Document brick allows you to compose more sophisticated sidebars by adding other Pixiebrix bricks within it.

Hit the “Select a Brick” button and select Customizable Table.

Once you’ve added the brick you can see the fields open up for customization in the page editor.

Configure them in the following way:

  • data: @state2
  • columns: We’re going to add 4 items by clicking the blue “Add Item” button and configure them like this
  • label: **Nationality**
  • property: strNationality
  • label: Current Team
  • property: strTeam
  • label: Height
  • property: strHeight
  • label: Weight
  • property: strWeight

Doing this tells PixieBrix that you want to use the data stored in the variable @state2 and displaying the values, strNationality, strTeam, strHeight, strWeight as values of a table whose header labels are the the respective ones labelled above.

customize the table data

Add a List

Next up you’re going to use a list brick. This brick is composed of two sections.

The brick part at the top is the configuration: here you can specify what data to show in a list and how it will be referenced.

In the case of the soccer mod, it was configured as:

Array: @state.socials

What this does is reference the array called socials in the variable called state, for each of the items inside the socials array, one item will be displayed in this list.

Element key: socialplatform

This allows you to reference an item of the previous array by the name specified. This way as the list of items gets rendered into the sidebar you can customize it one by one.

Item Type: Button

Here you can decide which kind of item you want to render in the item list.

customize render document

Once that's done, click on the bottom part of this brick’s area to configure the item type — in this case, a button.

This is the button is configured in our soccer example:

  • Title: @socialplatform
  • Variant: info
  • Size: sm
  • CSS Class: mx-3 my-2
  • Select a brick: Open tab: This makes it so that when you’re clicking on this button, the brick invoked on click will do an action. In this case this action will be opening a new tab. Doing so adds a couple of extra configuration fields to this brick. In the soccer example, we’ve configured the one needed as follows:
  • url: https://{{@socialplatform}}
customize the array

Add a paragraph of text

From the three dot menu, select Text.

This adds a paragraph of text that you can customize.

Click it to activate it and configure it like this:

  • Text: @state.strDescriptionEN

This will allow you to display a short piece of text stored in the state, with information about the user.

pixiebrix change the text

Add a block

From the three dot menu, add another Block.

This block contains a brick that displays an HTML brick in the sidebar.

You can use this HTML brick to display arbitrary HTML. In the soccer example, we make it contain an image of the player we’re looking up information on.

To achieve this, press the "Select a brick" button and look for the HTML Renderer brick.

Once this is done, configure the brick as follows:

  • HTML:
<img src="{{@state2[0].strThumb}}" style="width: 380px;
  height: 300px;
  object-fit: cover;">
add and customize a brick

Ready to build your sidebar mod?

If you've made it to this point, you probably really want to build your own custom sidebar mod.

This walkthrough illustrates just how deep you can go with PixieBrix, nesting and customizing things to meet your specific need. But if you're left with questions or want a second set of eyes on your brand new mod, pop into the PixieBrix Slack community! You'll find plenty of people willing to help you get set up.