Web integration using a custom layout – full instructions

⚙️ Web integration
1

Web integration

If a radio station uses Spinitron then its listener can look on the web for

  • Now-playing song
  • Current and recent playlists
  • Upcoming shows
  • Schedule
  • DJ profiles
  • Show descriptions
  • Past playlists

That’s all automatically published on spinitron.com but it should really be on the station’s web site. Web integration is any kind of mash-up of live content from Spinitron into a station’s web site. Spinitron has long supported web integration using

  • JavaScript widgets that you can drop in the HTML of an existing page to put, for example, the now playing song or upcoming shows on the page.
  • <iframe> embedding, which allows navigation through Spinitron content within the frame.
  • An API with which a station can fetch live Spinitron data and place it on the page.

They each have their pros and cons but (short of an elaborate development using the API) none provides access to all the Spinitron content with seamless navigation through the station’s web content and Spinitron’s live content and back again.

Custom layout (new in Spinitron in Jan 2020) is fourth web integration technique that overcomes the navigation problem. It can be used alone or in combination with any/all of the other integration techniques.

Page layouts

Web sites with multiple pages typically have a layout that’s shared across pages. A layout includes things like headers and footers, branding and logos, site navigation links, a common CSS stylesheet. A layout is basically an HTML document with the stuff that’s on all the pages and a place somewhere in the middle where each page’s unique content is inserted.

If we extract such a layout from a Spinitron client station’s web site and save it in Spinitron settings then Spinitron can serve public pages that look like the station’s own web site. This is the central idea in web integration using a custom layout.

The custom layout will typically include the same main navigation components, e.g. a top-nav menu, that appear on the station’s web site. Visitors to the station site can therefore follow a link to a page of Spinitron content (that looks just like the station’s pages) and from their navigate either to another page of Spinitron content (using a link in the page content body) or back to a main station site page (using a link in the page layout).

Example

The fictional radio station TEST 90.3 FM, The Voice of Foo Community College, Barton PA, USA has its web site at www.testradio.org.

  • The “On air” and "Programs"links in the top nav go to Spinitron pages that use a custom layout.
  • The links in the drawer that opens with the hamburger ☰ button go to different Spinitron pages.
  • The links in the “On-air” and “Coming up” cards also go to Spinitron pages.

Click any of those links and you end up on a Spinitron page with a URL like this one to the calendar

programs.testradio.org is an alias (CNAME) for spinitron.com so that URL is equivalent to

The ?layout=1 query parameter activates the custom layout saved in Spinitron. Try deactivating the custom layout by changing the 1 at the end to 0 or removing the query param and Spinitron will use its default (white label) layout:

The custom layout saved in Spinitron includes all the top-nav and footer links to www.testradio.org that are on the station’s home page. So a visitor on any of the pages with Spinitron content can use those links to get back to the station’s web site.

Instructions

Instructions are broken into these 4 parts

  1. Design your custom layout – always required
  2. Custom server name – required when you don’t want spinitron.com in links to pages with live Spinitron content
  3. HTTPS – required when using a custom server name with secure HTTP
  4. Widgets – required when using a custom server name and Spinitron widgets in the station’s web pages

You may not need all of them. And don’t let the length of text in sections 2 and 3 put you off, they are actually very simple one-time configs you make in your DNS.

In the following

  • “We” and “us” means Spinitron and its staff.
  • “You” means the station staff together with its web team.
  • We use the fictional radio station TEST 90.3 FM introduced above in examples.

1. Design your custom layout

You can do everything in this section without involving us but, as always, feel free to ask questions on the forum or contact us for support.

  • Derive a custom layout from a page of the station’s web site and save it in Spinitron.

    As an example, let’s derive a custom layout from the home page of www.testradio.org.

    • Refer to the page’s HTML source here.
    • Copy-paste that source into a text editor. In practice you might view page source in a browser and copy-paste that.
    • Remove the second and third cards on the home page: i.e. delete lines 99 thru 138
    • Delete everything inside the first card, i.e. delete lines 72 thru 93 …
    • … and replace with the special marker text {{SPINITRON_CONTENT}}.
    • Save the result of these edits in file named custom-layout.html. The result of this example is shown here.

  • Copy paste your custom layout from your editor into Spinitron (Admin: Station settings: Web customization: Layout) and save changes.

  • View the result by adding ?layout=1 to a public Spinitron page for the station, e.g.

    https://spinitron.com/TEST/?layout=1.

    You always need ?layout=1 to activate the custom layout.

  • Design and save in Spinitron (Admin: Station settings: Web customization: Stylesheet) any custom CSS style rules required to make the page content look right using the custom layout. (See the CSS note below.)

  • Any changes you make to the station’s web site’s layout must be made also to the custom layout and saved again in Spinitron.

    For example, at some point you’ll want to add ?layout=1 Spinitron links to the station site. If they go in the page layout (like for example the On-air and Programs links in the top nav of www.testradio.org) then you need to make the same changes to the custom layout and save it again in Spinitron.

  • Repeat whatever combinations of the above steps you need until you’re satisfied. At this point, if you don’t need a custom server name for the Spinitron pages (see next section), you can finish up by publishing the new station web site with its links to Spinitron pages using the custom layout.

CSS note: If you extract a layout from a station site as described above then it will probably include the stylesheet links from that site. This is the easy way to get the custom layout looking the same when it’s served by Spinitron. Such station stylesheets apply to the whole page including the Spinitron content. However, Spinitron appends a link to its default (white-label) stylesheet, which is needed to properly display its content. If the style rules in the station’s stylesheet don’t collide with those in Spinitron’s then you can style the Spinitron content by editing the station’s stylesheets. Style rules saved in Spinitron (Admin: Station settings: Web customization: Stylesheet) are rendered in a <style> block at the end of the page <head> so they override any stylesheets linked in the <head> including Spinitron’s default. So you can save style rules there to fix problems that the station’s stylesheet might cause in Spinitron content.

2. Custom server name

Whether they have a custom layout or not, pages with live spinitron content such as playlists and the calendar are served by Spinitron’s web servers. Normally the URLs will all start with https://spinitron.com. If that’s unsatisfactory then we can host for you a virtual server with a custom server name of your choice. This hosting service has an extra fee of $5/month on top of your regular Spinitron service fees.

  • Choose a custom server name for the station. Usually it would be a subdomain of the same domain as the station’s web site.

    For example, TEST 90.3 FM has registered the domain name testradio.org. It’s main web site is www.testradio.org. It chooses programs.testradio.org as the custom server name for its Spinitron pages.

  • Set up a CNAME record in the DNS for the station’s domain. The record should make the custom server name an alias of spinitron.com. For example, in the DNS settings for testradio.org we set up the CNAME alias

      programs.testradio.org  ⇒  spinitron.com

    You would do something similar. Let us know when it’s done.

  • We then provision a virtual server for the custom server name on our servers.

  • Once this is working, you can use the custom station name instead of spinitron.com in links to your station’s Spinitron pages. They still need the /NAME/ part and ?layout=1 query parameter.

    For example, TEST 90.3 FM can use

    instead of

3. HTTPS

If you need HTTPS for the custom server name then we know two ways to go about it.

3.1 Use a proxy service that supports HTTPS

For example, if you use Cloudflare and set up the CNAME in Cloudflare using proxy mode then HTTPS will just work. Other proxy-type services can probably do the same.

This is the case with testradio.org. While www.testradio.org web pages are served by Github, the DNS for the testradio.org domain is provided by Cloudflare. So when we set up the CNAME record with the alias

programs.testradio.org  ⇒  spinitron.com

in Cloudflare and chose proxy mode, the proxy immediately supported HTTPS. In proxy mode, when you connect to https://programs.testradio.org, you’re really connecting to a Cloudflare web server and on the back end Cloudflare gets the page content from spinitron.com. It seems Cloudflare automatically issues and signs a TLS certificate for the CNAME.

3.2 We provide HTTPS

If needed, we can provide HTTPS in your virtual server on Spinitron’s web servers for another $5/month. In this case

  • You set up another CNAME record in the DNS for the station’s domain

    _acme-challenge.<custom server name>  ⇒  _acme-challenge.spinitron.com

    For example, TEST 90.3 FM has custom server name programs.testradio.org so it sets the CNAME alias

    _acme-challenge.programs.testradio.org  ⇒  _acme-challenge.spinitron.com

    Let us know when it’s done.

  • We obtain a Let’s Encrypt cert for your custom server name using DNS alias mode, provision it in the virtual server, and renew the cert every three months.

  • Now you can use links to live Spinitron pages using https:// and your custom domain name.

4. Widgets

Spinitron’s JavaScript widgets can include links to Spinitron pages. For example, the third “Coming up” card on the home page of www.testradio.org uses the upcoming shows JS widget and it includes links to show pages and to DJ pages.

If you are using a custom server name then you probably want these links to use that server name too. The links in widget content are generated dynamically by Spinitron and by default will have https://spinitron.com as their base URL. To use your custom server name instead

  • Tell us the custom base URL you want to use, e.g. the custom server name prefixed with either http:// or https://. If the station’s web site doesn’t support HTTPS then you’ll probably choose http:// otherwise you may as well use https://.

  • We configure your custom base URL in Spinitron and you can check it (Admin: Station settings: Web customization: Custom base URL).

  • Add data=layout="1" to your widget container elements. This tells Spinitron to use the custom base URL in links and to include the ?layout=1 query parameter that activates your custom layout.

You can safely include data=layout="1" in all your widgets, even those that don’t render links. Maybe one day a widget gains links in Spinitron feature update.