Important

This documentation is deprecated, and only kept here to support users of browser extension APIs. If you are using Trigger.io for iOS or Android, see https://trigger.io/docs/.

Forge and Browser Add-ons

The Forge platform enables you to easily and quickly write add-ons that run on Chrome, Firefox, Internet Explorer and Safari. We'll take you through how to Get Started below, but first lets cover some concepts:

Concepts

Add-ons built on the Forge platform have two main aspects:

1. code to run when the browser is started
2. code to run when a page loads
3. code to run when a toolbar button is clicked

Code run at startup: "background code"

If your add-on relies on long-running code which is not attached or associated with any particular web page, you should use background code.

This code is loaded once when the browser is open or add-on is loaded/reloaded. It runs until the browser is closed or the add-on is removed. It is good practice to put page independent logic/functionality in the background.

To use background files, you need to use the background module.

Code run at page load: "content scripts"

If your add-on works with the individual web pages a user sees, you should use content scripts.

For example, an add-on which changes a web page so that any long words are replaced with links to that word in an online dictionary.

To use content scripts, you need to use the activations module.

Code run when a button is clicked: "popup code"

You can use the button module to add an icon to the brower toolbar.

The HTML page which may be displayed when a user clicks on this icon can include JavaScript. This JavaScript is executed each time the popup is opened, and is destroyed when the popup is closed; therefore, it is closer conceptually to content scripts than background code.

Getting Started

Hello Chrome

• After going through the Getting Started with Forge section you should see a src directory created. This is where all of your add-on files will be placed.

• There will be several files and folders in the src directory: this is a basic "Hello World" app.

• Inside the folder you should see config.json which is automatically generated. This file holds configuration settings for your add-on. You can edit this from inside the Toolkit by click on your app from the Your Apps page, then the 'Local config' link in the top-right

• Create a file called background.js inside the src/js directory with this code:

  forge.logging.info("This is executed once per add-on/browser launch");
  

• We'll configure this to run in the background context, by referencing it in the configuration file.

• Open config.json: note how we use the background module to use our background.js file:

  "background": {
      "files": [
          "js/background.js"
      ]
  },
  

The next sections will explain how to build and load the add-on.

Note

Google calls add-ons on Chrome 'extensions'. Add-ons and extensions are conceptually the same thing and different platforms have different conventions on naming. When talking about Chrome specifically, we'll use 'extensions'.

Building and testing Chrome extensions using Forge

To build your Chrome extension using the Toolkit, simple click on the app you wish to build from the Your Apps screen, and then the 'Chrome' link. You will see the full traceback in the console as the commands are run so you can see progress and any warnings.

If you make subsequent code changes that you want to build and test on the same platform, just click 'Run again' at the bottom of the console view in the app run page.

Using the command-line tools, use the forge build chrome command. When the build finishes take a look inside the development directory and you should see your generated Chrome extension.

To test the Chrome extensions:

• Open the Chrome browser and go to chrome:extensions.
• If Developer mode isn't already enabled click the [+] button at the top right.
• Click Load unpacked extension.
• Navigate to the development directory which contains the generated extension.
• Select the chrome folder and click OK.
• Expand section for your Chrome extension by clicking the ?
• Click forge.html
• A Chrome debugging window will appear: this is where you can debug your background scripts.
• In the console, you should see your message: .. image:: /_static/images/developer-tools.png

It's not working!

You can always contact us at support@trigger.io, or ask a question on StackOverflow.

What next?

Now that you're familiar with some basics try going through the Weather App tutorial.