README

PHP Classes and resources supporting dataset site creation, to create something like this example (or any of the other examples listed here).

This package intends to simplify creation of OpenActive Dataset Sites using templates.

For comparison, see the .NET and Ruby implementations.

Please find full documentation that covers creation of the accompanying GitHub issues board at https://developer.openactive.io/publishing-data/dataset-sites.

Table Of Contents

• Requirements
• Usage
  • API
    • renderSimpleDatasetSite($settings, $supportedFeedTypes, $staticAssetsPathUrl = null)
    • renderSimpleDatasetSiteFromDataDownloads($settings, $dataDownloads, $dataFeedDescriptions, $staticAssetsPathUrl = null)
    • renderDatasetSite($dataset, $staticAssetsPathUrl = null)
    • FeedType
• Contribution
  • Installation
  • Example
  • Running Tests
  • Release

Requirements

This project requires PHP >=5.6. While most of the functionality should work down to PHP 5.4, some functionality (especially around parsing of offset for DateTimeZone) will not work with that version of PHP (see the DateTimeZone PHP docs for more info).

Composer is also required for dependency management.

This project also makes use of Mustache for rendering the template (installed via Composer).

Usage

Please Note: This instruction are temporary and based on the current development status.

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

To install from terminal, run:

composer require openactive/dataset-site

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

use OpenActive\DatasetSiteTemplate\TemplateRenderer;

// Render compiled template with data
echo (new TemplateRenderer())->renderSimpleDatasetSite($settings, $supportedFeedTypes);

Or to render a CSP-compatible template, first ensure that you are serving the CSP compatible static assets from this version of the PHP package at a URL, and then include the following:

use OpenActive\DatasetSiteTemplate\TemplateRenderer;

// Render compiled template with data
echo (new TemplateRenderer())->renderSimpleDatasetSite($settings, $supportedFeedTypes, $staticAssetsPathUrl);

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

$settings = array(
    "openDataFeedBaseUrl" => "https://customer.example.com/feed/",
    "datasetSiteUrl" => "https://halo-odi.legendonlineservices.co.uk/openactive/",
    "datasetDiscussionUrl" => "https://github.com/gll-better/opendata",
    "datasetDocumentationUrl" => "https://docs.acmebooker.example.com/",
    "datasetLanguages" => array("en-GB"),
    "organisationName" => "Better",
    "organisationUrl" => "https://www.better.org.uk/",
    "organisationLegalEntity" => "GLL",
    "organisationPlainTextDescription" => "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.",
    "organisationLogoUrl" => "http://data.better.org.uk/images/logo.png",
    "organisationEmail" => "info@better.org.uk",
    "platformName" => "AcmeBooker",
    "platformUrl" => "https://acmebooker.example.com/",
    "platformSoftwareVersion" => "2.0",
    "backgroundImageUrl" => "https://data.better.org.uk/images/bg.jpg",
    "dateFirstPublished" => "2019-10-28",
    "openBookingAPIBaseUrl" => "https://reference-implementation.openactive.io/api/openbooking",
    "openBookingAPIAuthenticationAuthorityUrl" => "https://auth.reference-implementation.openactive.io",
    "openBookingAPIDocumentationUrl" => "https://permalink.openactive.io/dataset-site/open-booking-api-documentation",
    "openBookingAPITermsOfServiceUrl" => "https://example.com/api-terms-page",
    "openBookingAPIRegistrationUrl" => "https://example.com/api-landing-page",
    "testSuiteCertificateUrl" => "https://certificates.reference-implementation.openactive.io/examples/all-features/controlled/",
);

And $supportedFeedTypes could be defined as:

use OpenActive\DatasetSiteTemplate\FeedType;

$supportedFeedTypes = array(
    FeedType::FACILITY_USE,
    FeedType::SCHEDULED_SESSION,
    FeedType::SESSION_SERIES,
    FeedType::SLOT,
);

And $staticAssetsPathUrl (if required) should be set to the URL path of the directory containing the CSP static asset files (contents of the CSP compatible static assets archive, using the assets archive in this version of the PHP package).

API

renderSimpleDatasetSite($settings, $supportedFeedTypes, $staticAssetsPathUrl = null)

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

If $staticAssetsPathUrl is provided, the CSP-compatible template is rendered. In this case you must ensure that you are serving the contents of the CSP compatible static assets archive at this location, using the assets archive in this version of the PHP package.

$settings must contain the following keys:

Settings

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

renderSimpleDatasetSiteFromDataDownloads($settings, $dataDownloads, $dataFeedDescriptions, $staticAssetsPathUrl = null)

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

If $staticAssetsPathUrl is provided, the CSP-compatible template is rendered. In this case you must ensure that you are serving the contents of the CSP compatible static assets archive at this location, using the assets archive in this version of the PHP package.

The $dataDownloads argument must be an array of \OpenActive\Models\OA\DataDownload objects, which each describe an available open data feed.

The $dataFeedDescriptions must be an array of strings that describe the dataset, e.g:

$dataFeedDescriptions = array(
    "Sessions",
    "Facilities"
);

renderDatasetSite($dataset, $staticAssetsPathUrl = null)

Returns a string corresponding to the compiled HTML, based on the datasetsite.mustache, and the provided $dataset.

If $staticAssetsPathUrl is provided, the CSP-compatible template is rendered. In this case you must ensure that you are serving the contents of the CSP compatible static assets archive at this location, using the assets archive in this version of the PHP package.

The $dataset argument must be an object of type \OpenActive\Models\OA\Dataset, and must contain the properties required to render the dataset site.

FeedType

A class containing the supported distribution types:

You can use any of the above like this:

use OpenActive\DatasetSiteTemplate\FeedType;

echo FeedType::COURSE_INSTANCE;

Which will output:

CourseInstance

Contribution

Installation

git clone https://github.com/openactive/dataset-site-template-php.git
cd dataset-site-template-php
composer install

Example

To run the examples using PHP's built in server:

composer start

or

composer start-csp

Once running navigate to localhost:8080 in your browser to view the templates populated with JSON-LD data.

The default mustache templates (datasetsite.mustache and datasetsite-csp.mustache) are included under the src folder.

In index.php you can find an example of the associative array that's going to get parsed by TemplateRenderer.

Running Tests

PHPUnit is used to run tests.

To run the whole suite:

composer test

If you want to run the whole suite in verbose mode:

composer test -- --verbose

You can also run a section of the suite by specifying the class's relative path on which you want to perform tests:

composer test -- --verbose tests/Unit/TemplateRendererTest.php

For additional information on the commands available for PHPUnit, consult their documentation

Release

Major version numbers of this library should match those of the dataset-site-template on which this library depends. Any updates to the dataset site template files or assets should always be a major version update in both libraries.