Custom Report Formatters

Custom Report Formatters

Feature available in v0.4.0 and later

• Introduction
• Writing a Formatter
• Registering your formatters
• Rails example

Introduction

Rescuetime ships with two report formats: CSV and Array. If you would like your report in a different format, don't worry–it's easy to add a custom formatter.

Three things are required to add a custom formatter:

1. Write a class within the module Rescuetime::Formatters that inherits from Rescuetime::Formatters::BaseFormatter or one of its descendants
2. Define the class methods .name and .format
3. Register your formatters using Rescuetime.configure

Writing a Formatter

First, the formatters themselves. Here is a basic formatter:

# config/formatters/nil_formatter.rb
module Rescuetime::Formatters
  # Turns a productivity report into nothing useful.
  class NilFormatter < BaseFormatter
    # @return [String]  name of this report format
    def self.name
      'nil'
    end

    # @param  [CSV] _report  the raw CSV report from Rescuetime
    # @return [nil]          the formatted output (in this case, nil)
    def self.format(_report)
      nil
    end
  end
end

You can even inherit from an existing formatter:

# config/formatters/shouty_array_formatter.rb
module Rescuetime::Formatters
  # Formats a rescuetime report as an array of hashes, except shouting.
  class ShoutyArrayFormatter < ArrayFormatter
    # @return [String]  name of this report format
    def self.name
      'shouty_array'
    end

    # @param  [CSV]         report  the raw CSV report from Rescuetime
    # @return [Array<Hash>]         the formatted output (in this case, a shouty
    #                               array of hashes)
    def self.format(report)
      array = super(report)
      array.map do |hash|
        terms = hash.map { |key, value| [key.to_s.upcase, value.to_s.upcase] }
        Hash[terms]
      end
    end
  end
end

Registering your Formatters

Before setting your report format, add the path to your formatter(s) to the Rescuetime configuration using the Rescuetime.configure method. You will be able to set, append to, or manipulate the formatter_paths setting.

Rescuetime.configure do |config|
  path = File.expand_path('../my_custom_formatter.rb', __FILE__)
  config.formatter_paths = [path]
end

Now Rescuetime will look for the my_custom_formatter.rb file. Multiple paths may be added as well.

Rescuetime.configure do |config|
  config.formatter_paths = [
    'config/formatters/*_formatter.rb',
    'lib/formatters/**/*_formatter.rb',
  ]
end

Rails Example

For example, in a Rails app, you could add the configuration file to config/initializers:

# config/initializers/rescuetime.rb
Rescuetime.configure do |config|
  path = File.expand_path('../../formatters/*_formatter.rb', __FILE__)
  config.formatter_paths += [path]
end

Rails can now find any formatters ending in _formatter.rb in the folder config/formatters. For example, for a JSONFormatter:

# config/formatters/json_formatter.rb
module Rescuetime::Formatters
  class JSONFormatter < BaseFormatter
    def self.name
      'json'
    end

    def self.format(report)
      report.to_json
    end
  end
end