Adding new integrations

This is a by example type of tutorial about 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 [email protected]: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 popup view. From this part of the page all the relevant information is fetched.

{observe: true} - Observe true means that the extension observes the page for dynamic data loading. This means that if the tool loads some parts of the page with ajax or generates dynamically the Toggl Button extension waits until all loading is done and then adds Toggl Button link to the page.

$('.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-list__ class 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

• Toodledo
• Zendesk
• YouTrack