CIOC CIOC Remote Search and Details Joomla Extension Reference

Installing the Joomla Package

Currently, the Joomla Extension Package is available only through manual install by downloading the appropriate zip file(s) from the project repository. Use the Extensions > Manage > Install option from within Joomla to install the zip file.

CIOC API Reference and Configuration

This plug-in works against the CIOC Remote Search and Details API. Many settings, including the fields and data avaialble, are determined by the API setup and not the WordPress plugin. Please access the documentation for the CIOC Remote Search and Details API for information on customizing data sets, fields, record details pages, and so on.

Obtaining an API ID and Password

To use the plug-in, you must have an active API ID from the target database connected to an account with permissions to access the "CIOC Remote Search and Details API" (this setting is part of the User Type in CIOC). The CIOC User account with permissions for the API can sign into CIOC to generate an API ID/Password pair for each site. Click on your user name in the top site-bar menu to access the My Account page.

Best Practices for configuring API IDs:

• When configured, API IDs should be named in a way that clearly indicates their purpose.
• API Passwords are only available at the time they are generated and cannot be recovered. If you lose your password, you must generate a new ID/Password combination.
• In general, IDs should be for one purpose and not shared; in that way, an ID can be deactivated due to problem use without impacting others. There is no limit on the number of IDs that can be generated.
• When no longer in use, API IDs should be deleted.

Component / Module Setup Reference

Once the Extension Package has been installed and the API setup completed within the CIOC database, you can begin to configure the Joomla Component and Modules. Note that the main Joomla Component is required to drive the companion Modules; to ensure succesfull operation, please ensure that you install the entire package, and do not delete or inactivate individual parts of the package.

Global Component Setup

After installing the extension package, you should access the CIOC API Settings withing Joomla to configure the database URL, API ID and Password.

The only mandatory settings (under the "Authentican" tab) are:

• the URL of the target CIOC database (e.g. https://test.cioc.ca)
• the API ID
• the API Password

Additional display-related settings can be found under the "Display" tab:

• The component requires access to the FontAwesome font library and a small portion of the BootStrap library. If you already include these libraries, you may choose to block the component from adding them.
• For the record details display, you may choose whether to show the headings grouping similar fields together into sets
• You can choose to "Add icons automatically whenever possible" to have the system select icons to display next to fields on search results and record details
• If you wish to be able to display a Google Map of record address on your record details pages, you must register for a Google Maps API Key for your site and add it to the Settings. Information about obtaining a key can be found here.

How it Works - The Basics

The ability to generate search results, record details, and some type of search form or category list first relies on the setup of a Joomla Menu Item. This setup adds one type of search form (including "browse by category" option) as well as creating a search results page and a record details page. Additional menu items may be configured with different settings (different type of search, different "View" of records, different language, etc). Once at least one Menu Item is configured, it is also possible to add search form or category modules to other content pages that use an existing Menu Item setup to display search results and record details.

Create a Menu Item

At least one menu item configuration is required to drive all aspects of the Joomla extension. To configure a Menu Item, Select Menus > [Name of Menu to Add To] > Add New Menu Item.

On the Details Tab:

• Provide a Menu Title and optionally an Alias (for the URL of the generated page)
• Select from the Menu Item Type Drop-down the value CIOC RSD > CIOC Remote Search and Details API
• If you need to switch to another View (e.g. you want display information from a portal / data set other than the default one you were assigned to) you may enter a View Type number here. If you were not provided with a list of View Numbers and their function, assume that this should be left blank.
• If you need to switch to another Language, you may enter the language code here (e.g. en-CA, fr-CA). The language you select must be configured and available to you in the CIOC setup.
• Decide whether you would like the search page to be a full Search Form (keywords, community, categories, age groups, etc.) or a Browse by Category listing.

On the Search Form Options tab (if you selected the Search Form option):

• You may elect to have the search results list be displayed in the CIOC Results Page. Use this option if you want to draw traffic to the full CIOC database website, you would like to access the search results mapping tool, or you prefer the high-performance of using the database directly.
• You may choose which search options you wish to display on your Search Form, including Keyword Search Box, Age Group Drop-down, Quicklist Drop-down (see category configuration options below), and select whether you want to limit to records "Located In" or "Serving" a particular Community.
• Search forms for this extension pre-load search criteria when the criteria are part of the URL. Optionally, provide a "Clear Form" button to allow the user to blank out all values on the Search Form; otherwise, a Reset button is provided which will reset to the state of the form when the page was loaded. This is not needed in most cases.
• If you have a situation where multiple search forms can appear on the same page, providing a Multiple Form ID can help all the search forms to function properly. This can be simple, such as a unique digit. This is not needed in most cases.

On the Browse Options tab (if you selected the Browse option):

• You may elect to have the search results list be displayed in the CIOC Results Page. Use this option if you want to draw traffic to the full CIOC database website, you would like to access the search results mapping tool, or you prefer the high-performance of using the database directly.
• You may enter a value into the Quicklist Type (see category configuration options below) to choose the list of categories to display (in most cases, leave this as DEFAULT).
• You may optionally show a Count of the number of records beside each category.

A few notes about configuring Categories / Quicklist:

• On the Search Form, leave this option blank to have no Quicklist / Category drop-down
• Entering the code DEFAULT will choose the list of categories pre-configured for this View in the CIOC database. This is usually the correct choice
• In some cases, a supplementary or specialized list of categories other than the default is desired. In this case, the CIOC database administrators will provide a Publication Code to enter as the Quicklist Type.

On the Search Results Options tab:

• You may elect to have the full record details be displayed in the CIOC Record Details Page. Use this option if you want to draw traffic to the full CIOC database website, or you prefer the high-performance of using the database directly.
• If you are creating a very simple list with basic contact information, you may choose to exclude linking to any Record Details page at all. In most cases, this is not recommended since only 2-4 fields should be included in search results for performance reasons, so linking to the full details is usually necessary for completeness. An exception may be made for very small/limited sets of records where showing more details for multiple records is not a performance or display problem.
• Optionally, you may include a count of the number of records returned at the top of the Search Results page.

Under some circumstance, you may want to hide the main search form (because you are using Supplementary Search forms in other pages, as described below). To create the Menu Item and gain the functionality of the component, but not explicitly have the link to the search page show up in your menu, choose the Link Type tab and turn off Display in Menu.

Create a Supplementary Search

Supplementary Search forms or lists of categories may be included next to other content using the CIOC RSD Modules. Modules must be tied to an already-configured Menu Item, and many settings are taken from the connected Menu Item.

To configure a Module or add a new one, choose Extensions > Modules. If you do not see the CIOC Modules in your list and there are many Modules listed, use the Search Tools to search by Type and located the ones beginning with "CIOC". To create a new Module, select New + from the main Module management page and select either a CIOC RSD (Search form) or CIOC Remote Browse (Category list) Module Type. It is possible to configure Multiple Modules, which may be tied to the same or different Menu Items. This is useful if you are displaying content from different Views, or different lists of categories.

• Select either the Browse or Search Form Module to work with (you may add both)
• Give the Module a Title; this can be hidden from display on the Module tab.
• From the Module tab: Select your already-configured CIOC RSD Menu Item and configure your Search or Browse form as you would for the settings described in the Menu Item setup. Using the Position drop-down, choose a position slot in your Joomla Template (or inside an article) where the Module contents should appear. Ensure the Status is set to Published.
• From the Menu Assignment tab: choose the page(s) on which to display your Module.