Skip to content

Commit

Permalink
updates to include FullCalendar
Browse files Browse the repository at this point in the history
  • Loading branch information
@envycontent
envycontent committed Mar 20, 2015
1 parent f3111c7 commit 9b0c8ec
Show file tree
Hide file tree
Showing 3 changed files with 76 additions and 63 deletions.
10 changes: 10 additions & 0 deletions docs/source/index.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -5,11 +5,21 @@ Oxford Talks Embed Widget
Web Managers
============

An example widget to get you started with embedding talks in your own webpages can be found here:

`https://github.com/ox-it/talks.ox-js-widget <https://github.com/ox-it/talks.ox-js-widget>`_

The widget uses JavaScript to write a table, list or calendar view of selected talks to an HTML page. You can specify the criteria to select the talks you want.

This is a very basic guide for web managers and integrators, developers can probably skip to the Parameters Reference at the end. For the calendar view, the widget uses a JQuery plugin, FullCalendar; comprehensive documentation for that can be found on the FullCalendar website - http://fullcalendar.io .


.. toctree::
:maxdepth: 2

web-managers/example-embed.rst
web-managers/github-zip.rst
web-managers/parameters.rst
web-managers/find-ids.rst


Expand Down
79 changes: 16 additions & 63 deletions docs/source/web-managers/example-embed.rst
View file
Original file line number Diff line number Diff line change
@@ -1,27 +1,14 @@
Installing and Configuring the Widget
=====================================

The example widget to get you started with embedding talks in your own webpages can be found here:

`https://github.com/ox-it/talks.ox-js-widget <https://github.com/ox-it/talks.ox-js-widget>`_

The widget uses JavaScript to write a table or list of selected talks to an HTML page. You can specify the criteria to select the talks.

This is a very basic guide for web managers and integrators, developers can probably skip to the Parameters Reference at the end.

Installation
------------

1. `Download <https://github.com/ox-it/talks.ox-js-widget/archive/master.zip>`_ the latest files (:doc:`instructions on downloading from the github repository in this guide <github-zip>`)
2. You will only need the files in the widget folder - **embed_ox_talks.js** and **embed_example.html**.
3. Place these in a single directory on your computer or web server
4. Next open the **embed_ox-talks.js** in a text editor and check the configuration - the :code:`url_stem` should be set as follows (and should always be https)

.. parsed-literal::
var url_stem = '|oxtalks-url-ssl|/api/events/search?';
5. You are now ready to test the widget by opening and viewing **embed_example.html** in your browser
2. You will only need to tweak the files in the widget folder - **embed_ox_talks.js** and **embed_example.html** (**embed_ox_talks.min.js** is a *minified* version of the JavaScript).
3. However, to get things up and running quickly, place both the **widget** directory and the **libs** directory in a single directory on your computer or web server
4. You are now ready to test the widget by opening and viewing **embed_example.html** in your browser

Defining your selection of talks
--------------------------------
Expand All @@ -30,73 +17,39 @@ You do this in the HTML page

1. Open **embed_example.html** in a text editor
2. The main work is done in the *<script>* tag at the bottom of the page
3. To customise your selection of talks adjust the :code:`var params` section in the *<script>* tag. Full instructions on how to do this are given in the Parameters Reference section below
3. To customise your selection of talks adjust the :code:`var params` section in the *<script>* tag. Full instructions on how to do this are given in the :doc:`Parameters Reference section <parameters>`.
4. Remove the first set of '//' to activate a particular parameter

Changing how the talks are displayed
------------------------------------

1. In **embed_example.html** you will see two functions in the *<script>* tag at the bottom of the page. - one delivering a table, the other a plain listing of talks:
1. In **embed_example.html** you will see three functions in the *<script>* tag at the bottom of the page - delivering a table, a plain listing of talks and a calendar view:

.. code::
showTable( params ); //appends to body, since no selector specified
showList( params, "#embedded-talks" ); //appends to the specified element
oxtalks.showCalendar( params, "#embedded-calendar" ); //appends a calendar to the body
2. Both have the option to specify the id of the HTML element you would like to populate, and some example elements are provided in the middle of the page:
2. All have the option to specify the id of the HTML element you would like to populate, and some example elements are provided in the middle of the page:

.. code::
<h1>Example of embedding</h1>
<div id="embedded-talks"></div>
<div id="embedded-table"></div>
<div id="embedded-calendar" style="max-width:800px"></div>
3. Once you've finished testing, you can delete one or other of these as you probably won't want both
3. Once you've finished testing, you can delete the divs you don't want. Remember that, if you choose the **showTable** option you will probably want to specify the element you want the table to appear in.

4. If the actual output of the listing or the table is not to your liking you will need to investigate the JavaScript file **embed_ox_talks.js** in more detail and adjust the :code:`buildList` or :code:`buildTable` functions

Parameters Reference
--------------------

The web page **embed-example.html** uses information you provide to build your selection of talks.

.. Note:: Speakers, venues etc are searched via their ID - check the :doc:`instructions on how to find the IDs you need <find-ids>`.

from : date string ('dd/mm/yy'), **required**
* Start date for the list of talks.
* Format as :code:`'dd/mm/yy'`
* Or use the keyword :code:`'today'` to get upcoming talks

to : date string ('dd/mm/yy'), optional
* End date for the list of talks.
* Format :code:`'dd/mm/yy'`

speakers : array of speaker IDs as strings, optional
* For a list of talks by one or more specific speakers
* Format for one speaker :code:`['f8ecded3-d2af-4585-bd3b-5cd7440795b9']`
* Format for more than one :code:`['f8ecded3-d2af-4585-bd3b-5cd7440795b9','7d5e6f9a-d2d0-4185-9cf6-eaf0073cbf34']`

venues : array of oxpoints IDs as strings, optional
* For a list of talks in one or more specific venues
* Format for one venue :code:`['oxpoints:59444038']`
* Format for more than one venue :code:`['oxpoints:59444038','oxpoints:55095840']`

organising_departments : array of oxpoints IDs as strings, optional
* For a list of talks in one or more specific organising departments
* Format for one department :code:`['oxpoints:23232596']`
* Format for more than one department :code:`['oxpoints:23232596','oxpoints:23232740']`

topics : array of FAST topic URIs as strings, optional
* For a list of talks on one or more specific topics
* Format for one topic :code:`['http://id.worldcat.org/fast/1097048']`
* Format for more than one topic :code:`['http://id.worldcat.org/fast/1097048','http://id.worldcat.org/fast/864329']`

.. Note::

* individual parameters are joined by AND in the query whereas two or more values given in the arrays are joined by OR.
* an array comprises square brackets and a list of items separated by commas
* make sure each of the IDs, dates or keywords you provide is given as a string i.e. it is set in inverted commas
* if you aren't using one of the parameters, either remove the line completely or make sure it is set to :code:`null` (for a date) or an empty array :code:`[]`

Changing the calendar view
--------------------------

1. You can adjust the way the calendar displays in the :code:`var calParams` section in the *<script>* tag in **embed_example.html**

2. It is also possible to add more parameters, for a complete overview of the range of parameters go to http://fullcalendar.io/docs/


50 changes: 50 additions & 0 deletions docs/source/web-managers/parameters.rst
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,50 @@
Parameters Reference
====================

The web page **embed-example.html** uses information you provide to build your selection of talks.

.. Note:: Speakers, venues etc are searched via their ID - check the :doc:`instructions on how to find the IDs you need <find-ids>`.

from : date string ('dd/mm/yy'), **required**
* Start date for the list of talks.
* Format as :code:`'dd/mm/yy'`
* Or use the keyword :code:`'today'` to get upcoming talks

to : date string ('dd/mm/yy'), optional
* End date for the list of talks.
* Format :code:`'dd/mm/yy'`

speakers : array of speaker IDs as strings, optional
* For a list of talks by one or more specific speakers
* Format for one speaker :code:`['f8ecded3-d2af-4585-bd3b-5cd7440795b9']`
* Format for more than one :code:`['f8ecded3-d2af-4585-bd3b-5cd7440795b9','7d5e6f9a-d2d0-4185-9cf6-eaf0073cbf34']`

venues : array of oxpoints IDs as strings, optional
* For a list of talks in one or more specific venues
* Format for one venue :code:`['oxpoints:59444038']`
* Format for more than one venue :code:`['oxpoints:59444038','oxpoints:55095840']`

organising_departments : array of oxpoints IDs as strings, optional
* For a list of talks in one or more specific organising departments
* Format for one department :code:`['oxpoints:23232596']`
* Format for more than one department :code:`['oxpoints:23232596','oxpoints:23232740']`

topics : array of FAST topic URIs as strings, optional
* For a list of talks on one or more specific topics
* Format for one topic :code:`['http://id.worldcat.org/fast/1097048']`
* Format for more than one topic :code:`['http://id.worldcat.org/fast/1097048','http://id.worldcat.org/fast/864329']`

url : url string, optional
* For testing purposes, overrides the API url

page_size : integer, optional
* Specify the number of talks to appear per page
* Format :code:`4`

.. Note::

* individual parameters are joined by AND in the query whereas two or more values given in the arrays are joined by OR.
* an array comprises square brackets and a list of items separated by commas
* make sure each of the IDs, dates or keywords you provide is given as a string i.e. it is set in inverted commas
* if you aren't using one of the parameters, either remove the line completely, comment it out with '//', or make sure it is set to :code:`null` (for a date) or an empty array :code:`[]`

0 comments on commit 9b0c8ec

Please sign in to comment.