otrl-search-widgets

OTRL Search Widgets :mag: :train:

Embeddable search & season search widgets

Browsers support ^{_{made by godban}}

IE / Edge	Firefox	Chrome	Safari	iOS Safari	Chrome for Android
IE10, IE11, Edge	last 2 versions	last 2 versions	last 2 versions	last 2 versions	last 2 versions

Installation

This module is distributed via npm which is bundled with node and should be installed as one of your project's dependencies:

npm install --save otrl-search-widgets

Usage

Files

The widgets are distributed in 2 flavours

1. All dependencies included (./dist/widgets.js)
2. Without React (./dist/widgets-no-react.js)

If you are not using React or you are not sure if you are using React, then you probably want to use the first option. If you are already using React in your app, then you can use the 2nd option.

The default source file for otrl-search-widgets is dist/widgets.js, and this is what you will get if you require('otrl-search-widgets')

Note: This library depends on some modern JavaScript features. We include babel-polyfill in the main all-batteries-included widgets.js. But it is not included in ./dist/widgets-no-react.js. If you use that variant and wish to support older browsers, you will need to load this yourself. See our demo for an example of both cases.

Distribution

Our source code is distributed with a Universal Module Definition. This means that you can include our source in a number of different ways:

1. Via a <script> tag (exposes a global variable named OtrlWidgets)
2. Via an AMD loader such as RequireJS
3. Via CommonJS/ES6 modules (e.g. via Browserify/webpack)

E.g.

<!-- In your .html file-->
<script src="path/to/widgets.js"></script>
<script>
    console.log('Loaded', OtrlWidgets);
</script>

Or

// RequireJS
require(['otrl-search-widgets'], function (OtrlWidgets) {
    console.log('Loaded', OtrlWidgets)
})

// CommonJS
var OtrlWidgets = require('otrl-search-widgets');

// ES6
import * as OtrlWidgets from 'otrl-search-widgets';

Vanilla JS

// Assuming you have already loaded `otrl-search-widgets` as above

// Load the brand configuration
OtrlWidgets.configure('thameslink');

// Render the JourneyPlanner widget into the #main element
OtrlWidgets.render(
    document.getElementById('main'),
    OtrlWidgets.JourneyPlanner,
    { tabs: ['search', 'season'] }
);

As a react component:

This example uses JSX - syntactic sugar around React.createElement()

import React from 'react';
import ReactDOM from 'react-dom';

// Load the widgets without react
import * as OtrlWidgets from 'otrl-search-widgets/dist/widgets-no-react';

// Load the brand configuration
OtrlWidgets.configure('thameslink');

function App () {
    return (
       <div>
          <h1>Find trains</h1>
          <OtrlWidgets.JourneyPlanner tabs={ ['search', 'season'] } />
       </div>    
    )
}

ReactDOM.render(<App />, document.getElementById('main'));

OtrlWidgets.configure(brand)

Load the configuration for the ${brand}. This ensures that you'll show the correct results on the train operator's website.

Note: If you need to set the brand, you should do this before rendering a widget. Otherwise you might have to re-render the widget for it to pick up the config changes.

OtrlWidgets.render(container, widget, options)

This is a wrapper around ReactDOM.render, so is only necessary to use this if you are not using React in your application.

container should be the HTMLElement where you want your widget to be added. If the widget was already rendered in this container, it will be updated.

widget is an optional React component. It defaults to OtrlWidgets.JourneyPlanner

options is an optional Object containing "props" for the widget.

Examples:

// Renders the JourneyPlanner into the `#main` element
OtrlWidgets.render(document.getElementById('main'))

// Override some props on the component
OtrlWidgets.render(document.getElementById('main'), OtrlWidgets.JourneyPlanner, { tabs: ['search'] })

OtrlWidgets.JourneyPlanner

A React component which displays the chosen search forms in a tabbed interface. It has the following props:

className

Optional CSS class to add to the widget's root element.

layout = "horizontal" | "vertical"

Specify the widget layout. Default: horizontal

tabs = ['search', 'season']

Choose which search tabs to display, and the order in which they should appear. Available tabs: search, season

onSearch = function (searchType, resultsUrl) {}

Callback when the user presses the "Search" button and there is a valid URL to display the search results.

The callback is called with two arguments:

• searchType - search|season
• resultsUrl - URL to display the search results

If you do not specify an onSearch callback, the default is to navigate the browser to resultsUrl.

CSS

The styling for the widgets is provided in the form of less files.

src/main.less declares all the rules needed. We recommend using this as a starting point, or as a template for your own customisations.

Compilation of css works out of the box using webpack and less-loader. In order to use less you will need to configure it to use less-plugin-npm-import and a prefix of ~. This extends the Less syntax to allow us to load .less files from node_modules/.

Demo

• View demo app
• View source

License

Apache-2.0