dataset-site-template-ruby

Ruby classes and resources supporting dataset site creation

Tools intended to simplify creation of dataset sites using templates.

For comparison, see the .NET and PHP implementations.

Installation

Add this line to your application's Gemfile:

gem 'openactive-dataset_site'

And then execute:

$ bundle

Or install it yourself as:

$ gem install openactive-dataset_site

Usage

If you are developing this package, go to the Contribution section.

Wherever you want to render your Dataset page, include the following instructions:


# Render compiled template with data
renderer = OpenActive::DatasetSite::TemplateRenderer.new(settings)
puts renderer.render

Where settings could be defined like the following (as an example):

settings = OpenActive::DatasetSite::Settings.new(
    open_data_feed_base_url: "https://customer.example.com/feed/",
    dataset_site_url: "https://halo-odi.legendonlineservices.co.uk/openactive/",
    dataset_discussion_url: "https://github.com/gll-better/opendata",
    dataset_documentation_url: "https://docs.acmebooker.example.com/",
    dataset_languages: ["en-GB"],
    organisation_name: "Better",
    organisation_url: "https://www.better.org.uk/",
    organisation_legal_entity: "GLL",
    organisation_plain_text_description: "Established in 1993, GLL is the largest UK-based charitable social enterprise delivering leisure, health and community services. Under the consumer facing brand Better, we operate 258 public Sports and Leisure facilities, 88 libraries, 10 children’s centres and 5 adventure playgrounds in partnership with 50 local councils, public agencies and sporting organisations. Better leisure facilities enjoy 46 million visitors a year and have more than 650,000 members.",
    organisation_logo_url: "http://data.better.org.uk/images/logo.png",
    organisation_email: "[email protected]",
    platform_name: "AcmeBooker",
    platform_url: "https://acmebooker.example.com/",
    platform_software_version: "2.0",
    background_image_url: "https://data.better.org.uk/images/bg.jpg",
    date_first_published: "2019-10-28",
    data_feed_types: [
      OpenActive::DatasetSite::FeedType::FACILITY_USE,
      OpenActive::DatasetSite::FeedType::SCHEDULED_SESSION,
      OpenActive::DatasetSite::FeedType::SESSION_SERIES,
      OpenActive::DatasetSite::FeedType::SLOT,
    ],
)

Feed-level customisation

If you need to do feed specific overrides, then you may do this by overriding the method.

settings = Class.new(OpenActive::DatasetSite::Settings) do
  def data_download(feed_type)
    val = super(feed_type)

    case feed_type
    when OpenActive::DatasetSite::FeedType::SESSION_SERIES
      val.content_url = open_data_feed_base_url + "session_series"
    end

    val
  end
end.new(
  data_feed_types: [
    OpenActive::DatasetSite::FeedType::FACILITY_USE,
    OpenActive::DatasetSite::FeedType::SCHEDULED_SESSION,
    OpenActive::DatasetSite::FeedType::SESSION_SERIES,
    OpenActive::DatasetSite::FeedType::SLOT,
  ],
  # rest of your settings here.
)

To match the PHP/.NET usage, you may alternatively use this approach, however it's less advised as there are more details to get right (and it risks a mismatch between the downloads and the advertised feed types):

settings = OpenActive::DatasetSite::Settings.new(
    # your settings here,
    data_feed_types: [
      OpenActive::DatasetSite::FeedType::SESSION_SERIES,
    ],
    data_downloads: [
        OpenActive::Models::DataDownload.new(
          name: "SessionSeries",
          additional_type: "https://openactive.io/SessionSeries",
          encoding_format:  OpenActive::DatasetSite::Meta.RPDE_MEDIA_TYPE,
          content_url: open_data_feed_base_url + "session-series",
        )
    ]
)

Dataset

dataset = OpenActive::Models::Dataset.new(
  id: "http://example.com/dataset/",
  description:
    "Near real-time availability and rich descriptions relating to the facilities and sessions available from Simpleweb",
  url: "http://example.com/dataset/",
  dateModified: "2019-12-09T15:36:15+00:00",
  keywords:
    ["Facilities",
     "Sessions",
     "Activities",
     "Sports",
     "Physical Activity",
     "OpenActive"],
  schemaVersion: "https://www.openactive.io/modelling-opportunity-data/2.0/",
  license: "https://creativecommons.org/licenses/by/4.0/",
  publisher:
    OpenActive::Models::Organization.new(
      name: "Simpleweb",
      description:
       "Simpleweb is a purpose driven software company that specialises in new technologies, product development, and human interaction.",
      url: "https://www.simpleweb.co.uk/",
      legalName: "Simpleweb Ltd",
      logo:
       OpenActive::Models::ImageObject.new(
         url:
           "https://simpleweb.co.uk/wp-content/uploads/2015/07/facebook-default.png",
       ),
      email: "[email protected]",
    ),
  discussionUrl: "https://github.com/simpleweb/sw-oa-php-test-site",
  datePublished: "2019-11-05T00:00:00+00:00",
  inLanguage: ["en-GB"],
  distribution:
    [OpenActive::Models::DataDownload.new(
      name: "FacilityUse",
      additionalType: "https://openactive.io/FacilityUse",
      encodingFormat: "application/vnd.openactive.rpde+json; version=1",
      contentUrl: "http://example.com/feed/facility-uses",
    ),
     OpenActive::Models::DataDownload.new(
       name: "ScheduledSession",
       additionalType: "https://openactive.io/ScheduledSession",
       encodingFormat: "application/vnd.openactive.rpde+json; version=1",
       contentUrl: "http://example.com/feed/scheduled-sessions",
     ),
     OpenActive::Models::DataDownload.new(
       name: "SessionSeries",
       additionalType: "https://openactive.io/SessionSeries",
       encodingFormat: "application/vnd.openactive.rpde+json; version=1",
       contentUrl: "http://example.com/feed/session_series",
     ),
     OpenActive::Models::DataDownload.new(
       name: "Slot",
       additionalType: "https://openactive.io/Slot",
       encodingFormat: "application/vnd.openactive.rpde+json; version=1",
       contentUrl: "http://example.com/feed/slots",
     )],
  backgroundImage:
    OpenActive::Models::ImageObject.new(
      url:
        "https://simpleweb.co.uk/wp-content/uploads/2017/06/IMG_8994-500x500-c-default.jpg",
    ),
  documentation: "https://developer.openactive.io/",
  name: "Simpleweb Facilities and Sessions",
)

renderer = OpenActive::DatasetSite::TemplateRenderer.new(dataset)

puts renderer.render

Dataset patching

The dataset generation should already be good for most purposes, if needing to change just a couple of fields then you may be better of patching just those fields.

settings = OpenActive::DatasetSite::Settings.new(
  # your settings here
)

dataset = settings.to_dataset

dataset.description = "Some better non-generated description here."

renderer = OpenActive::DatasetSite::TemplateRenderer.new(dataset)

puts renderer.render

API

OpenActive::DatasetSite::Settings

Accepts a config hash containing the following keys:

Settings

Key	Type	Description
`open_data_feed_base_url`	`string`	The the base URL for the open data feeds
`dataset_site_url`	`string`	The URL where this dataset site is displayed (the page's own URL)
`dataset_discussion_url`	`string`	The GitHub issues page for the dataset
`dataset_documentation_url`	`string`	Any documentation specific to the dataset. Defaults to https://developer.openactive.io/ if not provided, which should be used if no documentation is available.
`dataset_languages`	`string[]`	The languages available in the dataset, following the IETF BCP 47 standard. Defaults to `array("en-GB")`.
`organisation_name`	`string`	The publishing organisation's name
`organisation_url`	`string`	The publishing organisation's URL
`organisation_legal_entity`	`string`	The legal name of the publishing organisation of this dataset
`organisation_plain_text_description`	`string`	A plain text description of this organisation
`organisation_logo_url`	`string`	An image URL of the publishing organisation's logo, ideally in PNG format
`organisation_email`	`string`	The contact email of the publishing organisation of this dataset
`platform_name`	`string`	The software platform's name. Only set this if different from the publishing organisation, otherwise leave as null to exclude platform metadata.
`platform_url`	`string`	The software platform's website
`platform_software_version`	`string`	The software platform's software version
`background_image_url`	`string`	The background image to show on the Dataset Site page
`date_first_published`	`string`	The date the dataset was first published
`data_feed_types`	`FeedType[]`	A list of supported DataFeed types

And data_feed_types must be an array of FeedType constants, which auto-generates the metadata associated which each feed using best-practice values. See available types

OpenActive::DatasetSite::TemplateRenderer.new(settings)

Accepts a settings or a DataSet object. This is a Mustache engine.

.render

Returns a string corresponding to the compiled HTML, based on the datasetsite.mustache, the provided settings

`FeedType`

A class containing the supported distribution types:

Constant	Name
`COURSE`	`Course`
`COURSE_INSTANCE`	`CourseInstance`
`EVENT`	`Event`
`EVENT_SERIES`	`EventSeries`
`FACILITY_USE`	`FacilityUse`
`HEADLINE_EVENT`	`HeadlineEvent`
`INDIVIDUAL_FACILITY_USE`	`IndividualFacilityUse`
`SCHEDULED_SESSION`	`ScheduledSession`
`SESSION_SERIES`	`SessionSeries`
`SLOT`	`Slot`