pageActions vs browserActions

I have been working with WebExtensions for a while now and came across two action handlers for a browser add-on namely browserActions and pageActions. So I thought to clear out few dev-doubts in using these action handlers.

browserActions are the events that are performed when we click our add-on button from the add-on toolbar. when you click on the button in the toolbar a browserAction event is triggered. If a popup is defined in the manifest.json file then it is opened else you can listen to the event using ‘browserAction.onClicked’.(will discuss more on this)

browser-action

Similarly pageActions are similar to browserActions but the only difference is they appear inside the url input box. basically you can define page actions on whatever tab you would like the button to be shown.

page

Firstly, If you are building an add-on and the action is applicable across all tabs on the browser( Eg: adblock ) then you should use browser actions but if your add-on works only on a particular website then you should use pageAction instead of a browserAction.

Using browserActions:

You have to do two things to include a browserAction in your add-on

  • Include the required info about browser actions in the manifest.json file.
"browser_action": {
  "browser_style": true,
  "default_icon": {
    "16": "button/geo-16.png",
    "32": "button/geo-32.png"
  },
  "default_title": "Whereami?",
  "default_popup": "popup/geo.html"
}

browser_style is used if you want to include a css style for the browser action popup. You will have default_icon which gets displayed in the browser toolbar. default_title is the tooltip you will see when you hover over the icon in the toolbar and finally default_popup is the html of the popup that is displayed when the icon is cliked from the toolbar.

  • write the javascript code in your background.js file. more info about the API is here.

If you are not using any popup just like I did in my previous blogpost then you can listen to click event using ‘onClicked’ listener.

browser.browserAction.onClicked.addListener(callback);

Using pageActions:

The declaration in manifest and listener is almost same for both page action and browser action except that you need to enable pageaction for a particular tab using  pageAction.show().

  • Add this to your manifest
"page_action": {
  "browser_style": true,
  "default_icon": {
    "19": "button/geo-19.png",
    "38": "button/geo-38.png"
  },
  "default_title": "Whereami?",
  "default_popup": "popup/geo.html"
}
  • write the js code in your background.js file. more info on API is here.

first you need to show pageAction to a particular tab

browser.pageAction.show(tab.id);

and then add an event listener to pageaction

browser.pageAction.onClicked.addListener(callback);

I created my first add-on using browserAction here and pageAction here. You can have a look at it for reference/difference.

Happy Coding!

Publishing your browser add-on to Firefox Add-on Marketplace

You might have probably developed your first add-on and searched for ‘Publishing your add-on to Firefox marketplace’ and finally landed up here. In this post I will be discussing about How to publish your Browser add-on to Firefox Add-on Marketplace.

Firefox Add-on Marketplace (https://addons.mozilla.org) known as AMO is a home for thousands of add-ons. If you have developed a Firefox browser add-on and want to make it available to global audience then AMO is the right place to publish your add-on.

Step 1:

Open AMO’s website ( https://addons.mozilla.org ). If you already have a Firefox account created(which you generally do to sync up your browser preferences) then you can directly Log in to the website. Else register yourself and create your account.

step1

Step 2:

Under tools, click on ‘Submit a New Add-on’ to submit your new Add-on for publishing in AMO. You can update your developer profile by clicking on your username and selecting appropriate option from the dropdown.

step2

Step 3:

Once you click on ‘Submit a New Add-on’ in Step 2, you will be proceeded to the below screen. I want my add-on to be available for Global Audience, Hence I choose the first option. If you want your add-on to be available on your own website like Makkhichoose then you can choose 2nd option and click on ‘Continue’.

step3

Step 4:

You will get  the below screen after ‘Step 3’ where you have to upload the add-on zip file. If you get the below error then that means your ‘manifest.json’ is not found in the root of the zip file. To fix this, create a zip file with all the contents in the root folder instead of creating the folder into a zip file. This means if you double click your ‘zip’ file then you should be able to see the ‘manifest.json’ along with other contents of your add-on.

step4

Step 5:

When you click on ‘Continue’ in ‘Step 4’, the page is redirected to the below page. Simple metadata like the name of your add-on, description of your add-on is already extracted from your manifest.json file. However you can still edit it in this page before submitting for review. Also select the category best suited for your add-on on Firefox Desktop and Firefox for android in this screen.

step5

You can also mention the support email-id and a support website but these are not mandatory. Choose the best licence that suits for your add-on. If you are accessing any of the user’s data or sending it to your servers then you might have to click the checkbox related to Privacy policy(Click on the little question mark for more info).

If you have any notes to the reviewer( eg: test account details required to test your add-on )  you can mention it in the space provided below. Finally click on ‘Submit Version for Review’.

step6

Step 6:

Finally you submitted your add-on for review. The Add-on will be published once it is reviewed. You might already got a mail regarding your subscription once you get the below screen.

step7

Step 7:

Lets add the icons and few screenshots for our add-on. click on ‘Manage Listing’ and select your add-on. You can either add a new logo or choose from existing logos and then upload the screenshots, provide little description for your screenshot. Screenshots are the best way to advertise how useful your add-on is to the user before he installs your add-on. Finally click on ‘Save Changes’ for the changes to get saved.

step8

Step 8:

Now you can find your add-on listed along with the status when you click on ‘ Add-on Developer Hub’ on left top corner after ‘Step 7’.

step9

 

Hope this gives you a clear clarity on publishing your add-on to the Add-ons Marketplace.

Building your first browser addon for Firefox using WebExtension

Firefox Browser has been an incredible browser with thousands of add-ons in its marketplace. Performance of the browser has been greatly improved with e10s. With WebExtensions support from the recent releases it was made possible to develop cross platform add-ons and run across Firefox, Chrome, IE etc. with just a few tweaks.

I joined as a AMO’s ( addons.mozilla.org ) Feature Board member in November-2016 where I would help the Add-ons’ team in selecting the best add-ons to feature every month on the AMO website ( https://addons.mozilla.org/en-US/firefox/ ). I then came to know about WebExtensions. WebExtensions enable you to develop Cross-browser supporting add-ons which works on most of the latest browsers including Firefox, Chrome, IE etc. I thought to explore around a bit about WebExtensions and in the process I developed my first Browser add-on. \o/ You can find my extension here.

I love inShorts. It helps you to with the news around the world and puts it in 60 words. But it doesn’t have a dark theme and I don’t want the light to flash on my face every night. Add-ons are meant to improve your browsing experience and change how a particular website should work for you. Hence I thought to build an add-on which adds a dark theme to the inShorts website. I spent a weekend and finished my add-on. It is very easy to develop a WebExtension and you fill find a lot of amazing resources to learn. You can find it here.

I thought to share my experience of building my first Browser addon in this post.

{
 "manifest_version": 2,
 "name": "inShorts in dark",
 "version": "2.0.0",
 "homepage_url": "https://github.com/viswanathamsantosh/inshorts",
 "description": "Read your favourite news on inShorts by dimming the light right away on your browser.",

 "icons": {
 "48": "icons/icon-48.png",
 "96": "icons/icon-96.png"
 },
 "permissions": [
 "activeTab",
 "tabs"
 ],
 "browser_action": {
 "browser_style": true,
 "default_icon": {
 "19": "icons/icon-19.png",
 "38": "icons/icon-38.png"
 },
 "default_title": "Turn on or off"
 },
 "background": {
 "scripts": ["background.js"]
 }
}

Most of the contents in the manifest file are optional. depending on the usage you should include them in your manifest. For example, I need an icon on the browser toolbar for my addon, Hence I included the ‘browser_action’ in my manifest file. If you don’t need it then you can remove the section. More info on manifest.json is here.

Here I included a name, description, url of the github repo I’m using for the addon, browser action, default icons and a background script in this manifest.json file.

  • Next I have to write my javascript code. Depending on the usage you can either choose between content script or backgroup script. Since I m using browser actions in my addon, I use background scripts. Create a file named ‘background.js’ in the same folder as manifest.json file and included it in my manifest.json.
  • I studied the DOM structure of inShorts and wrote the required CSS to enable night mode where I would change the color of the background from white to black, change the text color of news from grey to white and the ‘Load More’ button color from white to Red.
var CSS='body{background-color: black;}span[itemprop="headline"]{color:white;}div[itemprop="articleBody"]{color:white;} #load-more-btn{background-color:red;color:white;}'

If I have to  include this style in the beginning and make no changes later on then I can use content script to make it possible. However  I will display an icon on the toolbar to enable and disable the night mode on the website.

  • I wrote my jscode to insert and remove the CSS in the present tab selected.
//method to enable nightmode
function enableNightMode() {
 browser.tabs.insertCSS({code: CSS});
}

//method to disable nightmode
function disableNightMode(){
 browser.tabs.removeCSS({code: CSS});
}
  • Then a toggle function and browser action to toggle the dark theme when you click on the button in the toolbar.

toolbar

//method to toggle mode
function toggleNightMode(tab){
 if(tab.url.indexOf("www.inshorts.com/en/read")!=-1){
 if(enable){
 enableNightMode();
 }else{
 disableNightMode();
 }
 }
}

//event handler when you click the button in the toolbar
browser.browserAction.onClicked.addListener(toggleNightMode);
  • And finally another event handler to reset the mode when the tab is refreshed.
//when the browser tab is refreshed
browser.tabs.onUpdated.addListener((id, changeInfo, tab) => {
 if(tab.url.indexOf("www.inshorts.com/en/read")!=-1){
 disableNightMode();
 }
});
  • Finally this is how my ‘background.js’ looks like after adding few flags

https://github.com/viswanathamsantosh/inshorts/blob/2.0.1/background.js

  • At last add the icons required for your addon and browser action button and mention the related paths in the ‘manifest.json’ file.
  • You can find information about Installing and debugging your addon here.

Hope this helps in getting started with the development of your first add-on! Happy Coding.

Using CSS Preprocessors

I have been writing a lot of CSS these days, when it comes to a project with 20+ responsive components it is obvious to write tons of CSS code. I started to use CSS preprocessors for a while now and it reduced my css code and the time I spend with css a lot than before. So I thought to share few basic tips in getting started with SASS preprocessor.

Here you will write your css in .scss(stands for sassy CSS) files and then use sass (Syntactically Awesome Stylesheets) to generate your css file (say main.css?)

sass

First you need to install sass on your machine. You can find the installation steps here.  I use a mac machine and since Ruby is already installed, I simply run the following command to install it

$sudo gem install sass

Now create a component.scss file in your ‘ProjectFolder/styles/’.

Note: Make sure you save the file as ‘.scss’ instead of ‘.scss.txt’ file.

You can convert this preprocessed file to the final ‘css’ file to use in a website using sass command.

$sass component.scss main.css
  • Lets write our component.scss file now
//component.scss
.main{
  h1{
    color: red;
  }
  h2{
    color: yellow;
    &.heading2{
      background-color: black;
    } 
  }
}

when you run ‘sass component.scss main.css’ your file is processed and the generated ‘main.css’ looks like

//main.css
.main h1{
  color: red;
}
.main h2{
  color: yellow;
}
.main h2.heading2{
  background-color: black;
}
  • You can also use variables if you want a value to be used across the page.
//component.scss
$primary-color: #ff0000;
$secondary-color: #00ff00;
$default-color: #0000ff;

button{
  &.primary{
    background-color: $primary-color;
  }
  &.secondary{
    background-color: $secondary-color;
  }
  &.default{
    background-color: $default-color;
  }
}

when you sass the above code, you will get

//main.css
button.primary{
  background-color: #ff0000;
}
button.secondary{
  background-color: #00ff00;
}
button.default{
  background-color: #0000ff;
}
  • You can also include one scss file into another scss.
//variable.scss

$primary-color: #ff0000;
$secondary-color: #00ff00;
$default-color: #0000ff;
//component.scss

@import 'variable';

button{
  &.primary{
    background-color: $primary-color;
  }
  &.secondary{
    background-color: $secondary-color;
  }
  &.default{
    background-color: $default-color;
  }
}

when you sass it, you will get

//main.css
button.primary{
  background-color: #ff0000;
}
button.secondary{
  background-color: #00ff00;
}
button.default{
  background-color: #0000ff;
}
  • When you are developing a web application to use across different platforms then you will have to use prefixes such as ‘-webkit’ , ‘-moz’ , ‘-ms’. You can simply use mixins to make it easy.
//component.scss
@mixin border-radius($radius) {
  -webkit-border-radius: $radius;
     -moz-border-radius: $radius;
      -ms-border-radius: $radius;
          border-radius: $radius;
}

.box { @include border-radius(10px); }

When you sass it, the below css code is generated

//main.css
.box {
 -webkit-border-radius: 10px;
 -moz-border-radius: 10px;
 -ms-border-radius: 10px;
 border-radius: 10px; }

If you are writing multiple components with multiple ‘.scss’ files then you can create a master ‘.scss’ file( say main.scss) and import all other ‘.scss’ file into it and sass it to generate your final ‘main.css’ file which you could include in your html page.

I gave only few examples about how you can use CSS preprocessors such as SASS to make it simple working on CSS. You can read more about SASS here.

Thank you for reading.