Adding new integrations

This is a by example type of tutorial about how to add integration of a new tool to Toggl Button Chrome 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.

Clone the Toggl Button repo

git clone [email protected]:toggl/toggl-button.git

Add reference of the new tool

Add reference to origins.json file located in src/scripts.

Add new line to the list. Try to keep the alphabetical order. The line should look something like this.

"supercooltool.com": {"url": "*://*.supercooltool.com/*", "name": "Supercooltool"},

If your tool does not have public url that people use it with leave the url parameter empty.

Note that the name in this line is used to fetch the file we will create in next step.

If name is "Super Cool Tool" it will translate to super-cool-tool.js. If name is "SuperCoolTool" it will translate to supercooltool.js. and so on ...

Create content script for adding button to the service's web page

Create the file to 'src/scripts/content'. In our case it is named 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:

'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

Make sure to add:

'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} - This can be one of two values {} or {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);

Custom styles

If you want to add some custom styles to your Start timer link you can add it to style.css. Just create new style rule with selector:

/********* SUPERCOOLTOOL *********/
.toggl-button.supercooltool {

}   

and add all needed styles in it.

Update README.md

Add your integration to the list of compatible services.

- [SuperCoolTool](https://www.supercooltool.com/)

Opening the pull request

If you have done all that you are ready to submit a pull request. It would be great if you would add a screenshot and description of where in the tool the toggl button link should be visible. This simplifies the checking progress for Toggl Button developers. If all is good, it will be merged shortly.

Please use git squash and merge all your commits into one commit. This keeps the git log more compact and clear.