Using Javascript/JSONP

The Universalis server provides some of its content in JSONP format.

The way JSONP works is this:

  1. In your web page, you include a call to our JSONP server (in the form of a <script> tag).
  2. In your web page, you define a Javascript function which receives the data from our server and puts text in the appropriate parts of your page. This function is usually called universalisCallback, but you can use a different name if you want.
  3. Your page ends up displaying the data from our server.

Don't worry about having to learn Javascript if you haven't used it before. In most cases you can make an exact copy of the Javascript you see on our example page, deleting one or two lines following the instructions in that page.

The example page

Here is an example of a page which incorporates Universalis content. (It is on a separate site from Universalis because your own web pages are on a separate site from Universalis, and we wanted to show you that the mechanism works even in that case).

There is a real-life example on the First Sunday Plus site.

Once you have looked at our example page, you can view its source code and copy it into your own pages. The source code contains many comments, labelled "CUSTOMISATION", which explain what changes you may want to make to our example code.

Availability of Javascript

All browsers support Javascript.

Some people turn Javascript off in their browsers. Very few of them do it, but it is best to have a link to the Mass Readings page so that they are not completely lost. The example page shows one way of doing this.

As for creating your web page, you have to be able to include a couple of <script> tags into the HTML code, and also (for the simplest case) to set the id value for some of your page elements. All HTML editors let you do this easily, but you may run into trouble if you are using something like Wordpress because (depending on its settings) it can restrict the tags you are allowed to use.

Technical details

What happens when the user views the web page is this:

  1. The browser asks our JSONP server to send it the script mentioned in the <script> tag, so that it can execute it.
  2. Our JSONP server sends back a script with a single Javascript statement which calls your universalisCallback function. The call passes your function a JSON object which contains the data from Universalis.
  3. The browser executes that Javascript statement, thus calling your universalisCallback function.
  4. Your universalisCallback function extracts the items it wants from the JSON object it has been given, and puts them into the appropriate parts of your web page.

More advanced applications

The example page handles the simplest case, when you want the Gospel for today, according to a fixed calendar and time zone.

With a rudimentary knowledge of Javascript

You should remove the line of Javascript which puts the technical data into the web page. The comments in the Javascript tell you which line to remove.

You can change the jsonpmass.js request to include next Sunday's date in the URL (for instance, /20130609/ for Sunday 9 June 2013). However, you would have to edit your web page each week to change the requested date.

You can include both today's and next Sunday's Gospel on the same page by having two jsonpmass.js requests on the page, referring to two differently-named universalisCallback functions and two different sets of id tags.

With a more advanced knowledge of Javascript

Instead of using a built-in <script> tag to request jsonpmass.js, you can synthesize a <script> tag dynamically. Because the synthesis happens in the user's browser, this frees you from having to worry about time zones: your Javascript can just get the date from the browser and put it explicitly into the jsonpmass.js URL. In the same way, your Javascript can calculate the date of next Sunday and use it to retrieve next Sunday's Gospel, so that you don't have to keep editing your web page.

With JQuery

Yes, it is possible, though the documentation appears sparse. Stack Overflow has an example which might serve as a starting-point.