Translation strategy

This is the official documentation of the agent_ruby Ruby agent.

Steps

Creating a custom data source will require you to work on the 3 following steps:

1. Declare the structure of the data

2. Declare the API capabilities

3. Code a translation layer

Minimal example

require 'net/http'
require 'json'
require 'uri'

module App
  module Collections
    # Minimal implementation of a readonly data source
    class MyCollection < ForestAdminDatasourceToolkit::Collection
      include ForestAdminDatasourceToolkit::Schema
      # The real work is in writing this module
      # Expect a full featured query translation module to be over 1000 LOCs
      include QueryGenerator

      def initialize(datasource)
        # Set name of the collection once imported
        super(datasource, 'MyCollection')

        add_field('id', ColumnSchema.new(
          column_type: 'Number',
          filter_operators: [], # As we are using the query translation strategy => define capabilities
          is_primary_key: true,
          is_read_only: true, # field is readonly
          is_sortable: false # field is not sortable
        ))

        add_field('title', ColumnSchema.new(
          column_type: 'String',
          filter_operators: [],
          is_primary_key: false,
          is_read_only: true,
          is_sortable: false
        ))
      end

      def list(caller, filter, projection)
        params = QueryGenerator.generate_list_query_string(filter, projection)
        uri = URI.parse('http://my-api/my-collection')
        uri.query = URI.encode_www_form(params)

        response = Net::HTTP.get_response(uri)
        body = JSON.parse(response.body)

        body['items']
      end

      def aggregate(caller, filter, aggregation, limit = nil)
        params = QueryGenerator.generate_aggregate_query_string(filter, aggregation, limit)
        uri = URI.parse('http://my-api/my-collection')
        uri.query = URI.encode_www_form(params)

        response = Net::HTTP.get_response(uri)
        body = JSON.parse(response.body)

        body
      end
    end
  end
end

module App
  class MyDatasource < ForestAdminDatasourceToolkit::Datasource
    def initialize
      super
      add_collection(Collections::MyCollection.new(self)) # List of your collections
    end
  end
end

lambda do
    datasource = new MyDatasource;
    agent = new ForestAdminAgent::Builder::AgentFactory([]);
    agent.add_datasource(datasource);
end

Read more

Implementing a data source using the "query translation" strategy is an advanced concept: you will need to have a deep understanding of Forest Admin internals.

This strategy is a good match when writing data sources for full-featured databases.

Before starting, it is highly advised to read and understand the following sections:

• Data Model Typing

• Data Model Relationships

• Query interface

• Fields and projections

• Filters

• Aggregations