Toggl-button: Add option to control timer with message events

[mskrip]

Describe the new feature

It would be nice to have a possibility to control Toggl with message events through toggl-button.

How does this help you?

This would allow 3rd parties to create private custom integrations without the need to change the extension itself.

Secondary goal

Message events may enable automatic integration registration so the user doesn't have to go to the extension's settings and manually add it. Of course only on an explicit user's request.

[mskrip]

To make it clear. I'm ready to implement and open a PR for this. I'd just like your opinion and "go ahead".

[mskrip]

@shantanuraj Hi, would it be possible to have a word on this from maintainers?

[shantanuraj]

Sorry this got lost in the shuffle.
Having this as a custom preference is fine by us.
Though I'd prefer we discuss the architecture and desired workflow before you start working on the implementation.

PS. What do you think about using the Toggl API directly for the custom integrations?

[mskrip]

Do you mean using Toggle API in a way as proposed in #1474 ? That was closed with the reasoning that it would hinder the maintainer's ability to provide support. And IMO using message events would enable much broader usability (for example integration registration as I've mentioned).

What I have in mind for now is having two more cases in something like handleIncommingMessage that would control starting and stopping the timer with the provided name, description, and project. That way any website can have the timer control implemented by sending the message events to the extension.

[shantanuraj]

No the suggestion in the linked comment, is around creating a generic interface for easily writing and sharing custom integrations, declaratively, instead of writing imperative code as we currently do.

I'm guessing you'll a postMessage to your source website to trigger the extension to start/stop entries, correct?
I don't mind that, I just have a question that you directly invoke the Toggl API https://github.com/toggl/toggl_api_docs/blob/master/chapters/time_entries.md
as well

[mskrip]

Yes, that's right with the postMessage.

As for Toggl API, yeah sorry I blanked out. That approach is possible. But would require also implementing per-user authentification on the custom website. And that wouldn't be possible on static websites. Having access through the extension would solve that issue right away.

[shantanuraj]

Sure thing, feel free to add this feature, my only suggestion at this point is to make it an optional feature.
ie. Add a toggle in the settings to enable it.

[mskrip]

Hi @shantanuraj I just had another idea of how to solve this. Would it be OK to have a message event listener that injects a new timer link based on the data it receives? This would solve all issues for handling specific events around the timer itself (starting, pausing, editing) and use an already existing interface for that. What I mean is something like this:

function handleMessageEvent(event){
  if (
    event.source === window &&
    event.data &&
    event.data.type
  ) {
    switch (event.data.type) {
      case 'create-link': {
        const targetElem = document.getElementById(event.data.targetElem);

        const link = togglbutton.createTimerLink({
          className: event.data.className,
          description: event.data.description,
          projectId: event.data.projectId,
        });

        targetElem.appendChild(link);
        elem.prepend(targetElem);
      };
      default: console.log('Unsupported event', event);
    }
  }
}

Of course with this being an optional feature (toggle in settings to enable).

[shantanuraj]

@mskrip So I spent time on the idea,
I think regarding your use-case a better method to implement this would be to create a new generic integration (just like the other content scripts) using data- attributes

So in your DOM you can define an element like

<div
  class="toggl-root"
  data-type="minimal"
  data-description="Some description"
  data-project="Some project"
  data-tags="tags1,tags2"
/>

write a new content script generic-toggl.js that works for this DOM api
and enable it for your particular domain

in the settings

[mskrip]

Wouldn't that have the same issues as #1474 had?

[shantanuraj]

It would, at that point we were exploring #1141
but I am pretty sure that we aren't doing it in the foreseeable future (it has it its own problems)

It is inhertently similar in principle to what Meistertask is doing
https://github.com/toggl/toggl-button/blob/361d7eb682a0b7c82fbe59ac237d4972bfbe31e5/src/scripts/content/meistertask.js#L45-L53

So feel free to adopt this route

[mskrip]

Sure that's simple enough. Where would be a good place to document that? I see a docs folder but that seems like it's purely auto-generated stuff.

[shantanuraj]

You can add it as another section in the .github/CONTRIBUTING.md file we can take over once you are done with the PR and reference it from the README

[mskrip]

Hi @shantanuraj , I've made a PR for this. Can I get an estimate on when will someone be able to take a look at it?

[shantanuraj]

hey 👋
I'm on vacation this week, I'll push some changes here and merge it on Monday, if that works for you

[toggl-button-bot]

:tada: This issue has been resolved in version 1.51.0 :tada:

The release is available on GitHub release

Your semantic-release bot :package::rocket: