RFC - BugHerd Configuration API

bugherd-config-api-rfc.md

This is a request for comment - this is a proposed configuration API for the BugHerd Public Feedback and Sidebar

The BugHerd sidebar can be configured to override some of its default behaviour as well as display extra information in any tasks that you pass in from a configuration object called BugHerdConfig.

When setting up BugHerd for the first time, you probably already know you need to add the following code to your site:

  <script type="text/javascript">
    (function (d, t) {
      var bh = d.createElement(t), s = d.getElementsByTagName(t)[0];
      bh.type = 'text/javascript';
      bh.src = '//www.bugherd.com/sidebarv2.js?apikey=YOUR-API-KEY-HERE';
      s.parentNode.insertBefore(bh, s);
      })(document, 'script');
  </script>

The BugHerdConfig object is added to the initilisation script as shown below:

  <script type="text/javascript">
    var BugHerdConfig = {
      // REPORTER
      reporter: {
        email: "[email protected]",
        name: "Foobar McFoobarson",
        hide: false
      },
      // META DATA
      metadata: {
        username: "foobar",
        version: "1.0",
        foo: "bar",
        logged_in: "true"
      },
      // PUBLIC FEEDBACK
      feedback: {
        tab_text: "Feedback"
      },
      // TAGS
      tags: [ "feedback", "external" ]
    };

    // BUGHERD INITIALISATION
    (function (d, t) {
      var bh = d.createElement(t), s = d.getElementsByTagName(t)[0];
      bh.type = 'text/javascript';
      bh.src = '//www.bugherd.com/sidebarv2.js?apikey=YOUR-API-KEY-HERE';
      s.parentNode.insertBefore(bh, s);
      })(document, 'script');
  </script>

Config options

metadata: object

Adding custom meta data to the "Additional Info" area for tasks created on your site is just a matter of adding an object called metadata to the BugHerdConfig object within the initialisation script.

The metadata object is comprised of simple key/value pairs.

  var BugHerdConfig = {
    // META DATA
    metadata: {
      username: "foobar",
      version: "1.0",
      foo: "bar",
      logged_in: "true"
    }
  };

Note: the values are strings. If you want to pass in true as above, send it as the string "true".

reporter: object

You can override the "Reported By" field for tasks created by passing in a reporter object.

By default the reporter is either the current logged in user/guest, or the email address entered in the feedback dialog.

  var BugHerdConfig = {
    // REPORTER
    reporter: {
      email: "[email protected]",
      name: "Foobar McFoobarson",
      hide: false
    }
  };

email: string

Email address of the reporter. If reporter is not a logged in BugHerd user/guest, the task/feedback dialog will have a field for editing this.

name: string

Name of the reporter. If reporter is not a logged in BugHerd user/guest, this is normally empty. Adding a value to this will change the mailto link on the reporter's email address to display the name instead.

hide: boolean

By default, if reporter is not a logged in BugHerd user/guest, the task/feedback dialog displays a field for entering the reporter's email address. Setting this to true causes the email address input on the task/feedback dialog to be hidden. Defaults to false.

feedback: object

The Public Feedback feature by default creates a tab at the bottom right corner of your site with the text "Send Feedback"

  var BugHerdConfig = {
    // PUBLIC FEEDBACK
    feedback: {
      tab_text: "Comentarios",
      hide: false
    }
  };

tab_text: string

Change the text on the tab.

  var BugHerdConfig = {
    // PUBLIC FEEDBACK
    feedback: {
      tab_text: "Comentarios"
    }
  };

hide: boolean

You can choose to hide the feedback tab entirely (either so you can trigger it from your own element or hide it only in some instances like on mobile phones).

  var BugHerdConfig = {
    // PUBLIC FEEDBACK
    feedback: {
      hide: true
    }
  };

tags: array

Tasks can have a pre-configured array of tags added using the tags object. This can even be done for Public Feedback that normally does not have tags associated with it until edited in the admin.

  var BugHerdConfig = {
    // TAGS
    tags: [ "feedback", "external" ]
  };

email_required: boolean

By default the email field is optional. Setting this to true will make the email field required.

  var BugHerdConfig = {
    // TAGS
    email_required: true
  };

@Haraldson and @oyvindlh - .feedbackTab is correct, just make sure you are setting the context to the iframe.

Below is an example in jQuery:

$(".feedbackTab",window.frames[ "_BH_frame" ].document).trigger('click',function(event){
  // stuff
});

I would prefer a way to do this without polluting the global namespace. Maybe allow initialization inside the IIFE?

However, this kind of config is great!

@ultimatedelman - I agree. What I posted was just a temporary work around. I would also like to work out a clean way to add this to the config above.