Customizing the Tooltips in the Query Builder

To help first-time users, we've integrated tooltips into the Query Builder. Click on Learn More below the filter elements to display the tooltip message in a popup window:

tooltips-scaled-to-700px

The Query Builder fetches the tooltip messages through a JSONP service call. By default, tooltips are served from DataSift's documentation site, but it is possible to customize the content of the tooltips. To do so you'll need to set up a JSONP service to serve your customized content.

By default, the tooltips follow the title conventions of target, operator, and argument lists on the DataSift documentation site, with periods replaced by dashes. The tooltip service URLs are of the following format:

http://dev.datasift.com/tooltip-endpoint/tooltip/retrieve?callback=jcsdlJSONP&id=twitter-mentions

DataSift uses Drupal for its documentation site. We serve the JSONP with the Field resource module, an extension for the Drupal service module that makes it possible to reuse (part of) the content in a documentation node to build a tooltip system. You could use a similar setup or make your own tooltip service in the technology of your choice. When you have a working web service, you can modify the definition options when initializing the Query Builder to use your own tooltip resource URLs.

If you just want to modify the base service URL, you can overwrite the targetHelpJsonpSource variable in the definition file.

<script type="text/javascript">
  var editor = new JCSDLGui($("#jcsdl"), {

    definition : {
      operators : {
        substr : {
        label : 'Substring',
        description : 'Filter for a sequence of characters that form a word or part of a word.',
        code : 'substr',
        jsonp : 'http://yoursite.com/jsonp/feed.php?operator=substr',
        url : 'http://your-docs-site.com/docs/operators/substr'
      },
      targetHelpJsonpSource : 'http://your-docs-site.com/tooltip-endpoint/tooltip/retrieve?callback=jcsdlJSONP&id={target}',
    }

  });
</script>

You can also use the targetHelpUrl function in the definition file, which takes two arguments:

  • target name (e.g. facebook.to.ids)
  • the specific field info (whatever is under this specific target in the definition object)

This has a default behavior (described below), but can also be overwritten. The default behavior for this function is to insert replace the {target} part of the above URL into the target name (with "." changed to "-"). It also checks for a hardcoded url in the target's definition which takes precedence over the dynamic ones.

The default function looks like this:

targetHelpUrl : function(target, fieldInfo) {
  if (fieldInfo.helpUrl) {
    return fieldInfo.helpUrl;
  }

  target = target.replace(/\./g, '-');
  return this.definition.targetHelpJsonpSource.replace(/\{target\}/g, target);
}