Toggl Button integrations

Toggl Button is progressing fast. It is doing so largely because the active help of the community. Actually the majority of integrations available in Toggl Button are community contributions. This blog post is a step by step type of guide on how to add integration of a new tool to Toggl Button extension.

As an example I’m going to go through the process of adding an integration named SuperCoolTool (with url https://www.supercooltool.com) to Toggl Button extension.

Clone the Toggl Button repo

git clone git@github.com:toggl/toggl-button.git

Add your new tool information to manifest.json

Add url permission:

"permissions": [ 
  "tabs", 
  "*://*.toggl.com/*", 
  "*://*.teamweek.com/*", 
  "*://*.supercooltool.com/*", 
  ...

Add common content script matching:

"content_scripts": [ 
  { 
     "matches": [ 
       "*://*.teamweek.com/*", 
       ..., 
       "*://*.supercooltool.com/*" 
     ] 
  },

Add service specific content script matching:

{ 
  "matches": ["*://*.supercooltool.com/*",], 
  "js": ["scripts/content/supercooltool.js"] 
},

Create contents script for adding button to the service’s web page

Create the file that you referenced in the manifest file. In our case it is named `supercooltool.js` We create it into the path: src/scripts/content/supercooltool.js This is the script that determines where the Toggl button is displayed on the page and how it functions. The script should look something like this:

/*jslint indent: 2 */ 
/*global $: false, document: false, togglbutton: false*/ 
'use strict'; 
togglbutton.render('#task:not(.toggl)', {observe: true}, function (elem) { 
  var link, 
    description = $('.title', elem).textContent, 
    project = $('.project', elem).textContent; 
  link = togglbutton.createTimerLink({ 
    className: 'supercooltool', 
    description: description, 
    projectName: project 
  }); 

  $('.link-list').appendChild(link); 
});
Let’s go through it step by step:
Header

This is needed for out javascript linting check. This can be just copied without modifications.

/*jslint indent: 2 */ 
/*global $: false, document: false, togglbutton: false*/ 
'use strict';
Render

#task:not(.toggl) – This is the selector of the container that must be visible when adding toggl button link. Note the :not(.toggl), this prevents extension adding toggl button multiple times to the page. If Toggl Button is shown inside of a popup view this should be the selector of this popupview. From this part of the page all the relevant information is fetched. $(‘.title’, elem).textContent – We get the description of the time entry from element with a selector .title that is inside the before set elem variable (in our case it is #task:not(.toggl)) $(‘.project’, elem).textContent – We get the project name of the time entry from element with a selector .project that is inside the before set elem variable (in our case elem is element with selector #task:not(.toggl))

togglbutton.render('#task:not(.toggl)', {observe: true}, function (elem) { 
  var link, 
    description = $('.title', elem).textContent, 
    project = $('.project', elem).textContent;
Link

className – this should be same as the name of the tool
description – this is the description value that was set in the previous section
project – this is the project value that was set in the previous section

link = togglbutton.createTimerLink({ 
  className: 'supercooltool', 
  description: description, 
  projectName: project 
});
Toggl button location

The .link-listclass is a container to which we append the Toggl Button link.

$('.link-list').appendChild(link);


(optional)

After completing the script it is advised you run make lint command in the root directory of the Toggl Button project. This shows all the linting errors that appear in the script. If any errors are shown it is advised you fix them accordingly.

Update README.md with your tool information

There’s three places you have to add your tool here. Right at the bottom there is list of url-s. Add you tool url after the last tool. If the last tool is:

 [27]: https://www.toodledo.com/

add your tool to the next line

 [28]: https://www.supercooltool.com/

Now there are two more places where all the tools are listed add your tool name there like this:

- [SuperCoolTool][27]

If you have done all that you are ready to submit a pull request. Toggl Button developers will review what you have done and if all is good, it will be merged shortly.

Some user created service integration examples