How To: Add New Integration

Artem edited this page Jan 16, 2018 · 6 revisions

The article describes the procedure for adding a new timer integration to TMetric browser extension.

Objective

Add the Start Timer button to an issue page of the virtual Web app called BigIssueTrac.

The following picture is an example of how the Start Timer button looks in Trello.

Trello

Preparing for development

  1. Fork the tmetric-plugins repo. See Fork A Repo article if you've never done this before.
  2. Install Node.js
  3. Open the project's folder and build the project by running the following script.
$ npm install
$ npm -g install gulp-cli
$ npm -g install typescript@1.8.x
$ gulp build

If you are building on Windows you can simply run install.bat and then build.bat.

Writing code

TMetric browser extension as well as sample code is written in TypeScript.

1. Create an empty integration

The code inserting the timer button into a Web page runs as content script.

Create bigIssueTrac.ts file in src\in-page-scripts\integrations\ folder with a following content.

class BigIssueTrac implements WebToolIntegration {
  /**
   * The array of URLs (with wildcards) that are used to identify
   * pages as those that belong to the service.
   */
  matchUrl = [
  ];

  /**
   * If the service may be on a custom domain implement this method
   * to identify pages of the service by other features (e.g. meta-tags).
   */
  match = {
    return false;
  }

  /**
   * observeMutations = 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 TMetric extension waits
   * until all loading is done and then adds the button to the page.
   */
  observeMutations = true;

  /**
   * Extracts information about the issue (ticket or task) from a Web
   * page by querying the DOM model.
   */
  getIssue(issueElement: HTMLElement, source: Source): WebToolIssue {
    return null;  
  }

  /**
   * Inserts the timer button for the identified issue into a Web page.
   */
  render(issueElement: HTMLElement, linkElement: HTMLElement) {
  }
}

IntegrationService.register(new BigIssueTrac());

2. Include the integration file to the project

  1. Add bigIssueTrac.ts to the files section on the src\tsconfig.json file to compile it.
{
    "files": [
        "in-page-scripts/integrations/bigIssueTrac.ts",
    ]
}

The sample is not the full tsconfig.json.

  1. Add bigIssueTrac.js to the content_scripts -> js section on the src\manifest.json to include the script into the extension.
{
    "content_scripts": [
        {
            "js": [
                "in-page-scripts/integrations/bigIssueTrac.js",
            ]
        }
    ]
}

The sample is not the full manifest.json.

3. Implement integration's methods

When you implement the WebToolIntegration interface the final version of bigIssueTrac.ts may look like the following code.

class BigIssueTrac implements WebToolIntegration {
  /**
   * The array of URLs (with wildcards) that are used to identify
   * pages as those that belong to the service.
   */
  matchUrl = [
    '*://*.bigissuetrac.com/issues/*'
  ];

  /**
   * If the service may be on a custom domain implement this method
   * to identify pages of the service by other features (e.g. meta-tags).
   */
  match = {
    return $$.getAttribute('meta[name=application-name]', 'content') == 'BigIssueTrac';
  }

  /**
   * observeMutations = 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 TMetric extension waits
   * until all loading is done and then adds the button to the page.
   */
  observeMutations = true;


  /**
   * Extracts information about the issue (ticket or task) from a Web
   * page by querying the DOM model.
   */
  getIssue(issueElement: HTMLElement, source: Source): WebToolIssue {
    var issueId = $$.try('.ticket-id').textContent;
    var issueName = $$.try('.ticket-name').textContent;
    var serviceUrl = source.protocol + source.host;
    var issueUrl = source.path;
    var projectName = $$.try('.project-name').textContent;
    var tagNames = $$.all('.labels').map(label => label.textContent);

    return { 
      issueId,
      issueName,
      issueUrl,
      projectName,
      serviceUrl,
      serviceType: 'BigIssueTrac',
      tagNames
    };
  }

  /**
   * Inserts the timer button for the identified issue into a Web page.
   */
  render(issueElement: HTMLElement, linkElement: HTMLElement) {
    var host = $$('.link-list');
    if (host) {
      var container = $$.create('li');
      container.appendChild(linkElement);
      host.appendChild(container);
    }
  }
}

IntegrationService.register(new BigIssueTrac());

Submitting code to the main repo

  1. After you test the new integration and make sure it's working properly, list the supported system in the Supported services section on the README.md file.
  2. Please use git squash and merge all your commits into one. This helps keeping the Git log more compact and clear.
  3. Open a Pull Request
Clone this wiki locally
You can’t perform that action at this time.
You signed in with another tab or window. Reload to refresh your session. You signed out in another tab or window. Reload to refresh your session.
Press h to open a hovercard with more details.