CIOC Community Information Feed Plug-in Reference

Installing the Plug-in

It is strongly recommended that these plugins be installed through a search of plugins available from WordPress.org. To find the plugins, simply click "Add New" plugin and then search for "CIOC". The WordPress Plug-ins are available as a manual install by downloading the appropriate zip file(s) from the project repository, but this makes updates more challenging and is not recommended. To manually install, use the Upload Plugin option from within WordPress to install the zip file, then Activate the plug-in to begin using it. Information on manual plug-in installation is available from codex.wordpress.org/Managing_Plugins

Obtaining an API Key

To use the plug-in, you must have an active API Key from the target database. A Super User in the target Online Resources database can configure a new API Key by going to:

Best Practices for configuring API Keys:

• When configured, API Keys should be named in a way that clearly indicates their purpose.
• Remember to indicate which module(s) will be used. Keys may be configured for the Community Information Module, the Volunteer Opportunities Module, or both.
• In general, Keys should be for one purpose and not shared; in that way, a key can be deactivated due to problem use without impacting others. There is no limit on the number of KKeys that can be generated.
• When no longer in use, API Keys should be deactivated.
• It is possible to access data from multiple target databases from the same page or post in WordPress. For example, you may want to source data from different regional databases for presentation on the same page. This is possible because the token is set in the shortcode, rather than being configured globally for the plug-in.

Shortcode Reference

The following section outlines the options available for customizing the shortcodes for this plug-in. However, the easiest way to accurately configure a shortcode is by using the shortcode generator available from the target Online Resources database. You must already have an API Key to use the shortcode generator tool.

Make life easier for partners you are sending an API Key to with a link that already includes their Key:

The Basic Shortcode

Once the plug-in has been installed and you have been given an API Key, you can get started displaying data in your WordPress site. Below is an example of the basic shortcode that you can place on any Page or Post in your site; subsitute your own API Key (e.g. key="01234567-89AB-CDEF-0123-456789ABCDEF") and the URL of the target CIOC Online Resources database (e.g. url="https://test.cioc.ca"). The order in which the shortcode options occur does not matter.

If no other settings are provided, "Newest Records" is chosen as the default listing type (see Listing Type information below).

Changing the View or Language

The language of records requested will default to whatever is the default for the site URL you provided. To explicitly change to another language, use ln="en-CA" (English), ln="fr-CA (French), etc.

Whenever possible, use a URL for the target database that already goes to the View (Portal) for records that you want to use. If a special URL is not available, you can switch to a different View # using viewtype="123" where 123 is the View ID number. You cannot switch to Views that are not public.

Choosing the Listing Type

Newest Records

This is the default listing type. You can choose it explicitly using type="newest", but it is not necessary. By default, the newest 15 records are shown and include the name of the record, the update or creation date, and link to the record in the source database is provided.

Specific Taxonomy Code (Service Category)

Select a group of up to 50 records based on the type of service they provide using type="taxonomy" and code="BD-1800" where the code is a valid Taxonomy Code from 211taxonomy.org. Any level of the Taxonomy may be used, but there must be a record at or below this branch of the Taxonomy to return results. Availability of this feature depends on the target database being configured to use this Taxonomy. This query does not current support linked Terms or multiple Terms.

Specific Publication Code

In databases using Publication Codes to create lists of records, listings of up to 50 records by Publication Code are made using type="pub" and code="MY-CODE" (substituting the appropriate Publication Code). There is no way to search by a Publication's General Headings at this time.

Adding a Community Search

Communities can't be searched on their own, but can be added to Taxonomy Code or Publication Code Listing Types using location="Community Name" or servicearea="Community Name". You cannot use both Location and Service Area criteria in the same request.

You must know the exact name of the Community in the target database to create a working search. Where there are multiple Communities with the same name in the database, you can add the Province/State/Country Code for clarity; for example location="Burlington|ON" would allow you to distinguish it from location="Burlington|VT"

Choosing the Fields to Display

You can add additional fields to your list display by adding any or all of the following shortcode options:

• Shortened Description: desciption="on"
• Site Address (or Community name, if no Site Address): address="on"
• Office Phone: office_phone="on"
• Email: email="on"
• Website: web="on"
• Hours of Operation: hours="on"

Styling the List

There are several options available to help you style your list. You can use any combination of these options, or none.

Don't know anything about HTML or CSS? Add the style_me="on" option to benefit from some pre-defined styles.

Do you want to be very specific about how the list is styled, to match your existing site? Trying using one of the following...

• Give the list an id for applying styles in your CSS using list_id="name-of-your-id". This allows you to change the style of one specific instance of the list.
• Give the list a class for applying styles in your CSS using list_class="name-of-your-class". This allows you to change the style of all instances of similar lists, for consistent formatting.

Enabling Icons

If your WordPress site includes the FontAwesome Icon Library, you can further style your list through the use of icons that will appear next to each included field. Turn on icons using has_fa="on".

Icons used include:

• Site Address / Community name
• Office Phone
• Email
• Website
• Hours of Operation

Debug Mode (for Website Developers)

If you are testing out your Plug-in, you can use debug="on" to be provided with a direct link to the JSON data provided by the API using the current settings. This will also allow you to view any error messages coming from the API.