If a radio station uses Spinitron then its listener can look on the web for
- Now-playing song
- Current and recent playlists
- Upcoming shows
- 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
<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.
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 mains station site page (using a link in the page layout).
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 “Coming up” card 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
In this example,
programs.testradio.org is an alias (CNAME) for
spinitron.com so that URL is equivalent to
?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 are broken into these 4 parts
- Design your custom layout – always required
- Custom server name – required when you don’t want
spinitron.comin links to pages with live Spinitron content
- HTTPS – required when using a custom server name with secure HTTP
- 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 – it just text a few more words to explain exactly what’s going on.
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
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
- 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
- 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=1to a public Spinitron page for the station, e.g.
You always need
?layout=1to 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=1Spinitron 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 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.orgas 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 is an alias of
spinitron.com. For example, in the DNS settings for
testradio.orgwe set up the CNAME alias
programs.testradio.org ⇒ spinitron.com
You would some 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.comin links to your station’s Spinitron pages. They still need the
For example, TEST 90.3 FM can use
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
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.orgso it sets the CNAME alias
_acme-challenge.programs.testradio.org ⇒ _acme-challenge.spinitron.com
Let us know when it’s done.
Now you can use links to live Spinitron pages using
https://and your custom domain name.
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
https://. If the station’s web site doesn’t support HTTPS then you’ll probably choose
http://otherwise you may as well use
We configure your custom base URL in Spinitron and you can check it (Admin: Station settings: Web customization: Custom base URL).
data=layout="1"to your widget container elements. This tells Spinitron to use the custom base URL in links and to include the
?layout=1query 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.