FETCH Widget

Embedding the Widget

The target webpage requires 2 lines of code to be added to it. The first is a <script> tag that references the widget code and passes set-up parameters. The second is a <div> placeholder that represents where on the page the widget will actually appear.

The <script> tag

The script tag references the actual JavaScript application and passes along set-up parameters to it.

Script Tag Attributes

As well as using the src attribute to reference the widget, the script tag can pass configuration information to the widget by using data attributes.

data-style values

Below is a complete list of valid values:

data-flags values

Below is a complete list of valid flags:

The <div> Placeholder

The <div> placeholder represents where on the webpage the widget will be rendered. It has a fixed format.

Format

<div id="sfcw" class ="sfcw"></div>

Linking to the widget

Although the widget can operate in isolation it can also be linked to from other pages or from inside the same page.

One example is a link that refers to a specific course. Another example is a link or form items that refer to specific search filters.

sfcw-courseId parameter

When the widget initializes, if the sfcw-courseId parameter is passed with a course id number value, the widget will automatically display the details of that course.

Examples

Search Filter Parameters

Examples

Widget Methods

The widget comes with some helper functions that can be called from within javascript. The widget is embodied in an object called sfcw.widget.

showCourse

showCourse instructs the widget to display the details of a course by using the parameter sent to it as the course Id.

Examples:

showResults

showResults instructs the widget to close any course details that are displayed and shows the search results screen.

There are no parameters.

See the Search method for an example on usage.

search

search instructs the widget to perform a search using the first parameter as a search object containing search filters.

Examples:

searchParameters

Returns the current searchParameters object containing the active search filters. See the search method for the structure of the searchParameters object.

There are no parameters.

setFilters

Takes a searchParameters object and sets the filter controls of the widget.

getCourseObject

Returns the current active Course Object. The widget Course Object is populated when a user clicks on a single course.

There are no parameters.

setCourseObject

Sets the widget's active Course Object and populates HTML elements with sfcw-data-* class names with corresponding course information. See Populating Course Data for more information.

enableLogging

Enables or disables console logging by the Widget. Used for debugging purposes.

Widget Events

The javascript programmer can hook in to certain Widget events with custom functions. When an event is triggered the widget calls the custom function.

Simply assign a function reference to one of the following variables.

event_searchComplete

This event is triggered every time a search is completed.

event_addFavouriteCourse

This event is triggered every time the user adds a course to their favourites.

event_removeFavouriteCourse

This event is triggered every time the user removes a course from their favourites.

event_courseView

This event is triggered every time the user views a course.

event_resultView

This event is triggered every time the user views the search results.

Event Example:

Log the course id every time a course is viewed by the widget user

Widget Customization

The widget can be styled and customized to suit the host website. There are 3 areas of customization:

HTML Customization

The widget normally uses internal HTML to layout the course search results and details. There are 3 HTML sections. The implementer may choose to override one or more of these.

• Section 1 - Search Courses section
• Section 2 - Search Results section
• Section 3 - Course Details section

Customizing Section 1 - Search Courses

To custom build the course results section follow these steps:

• Instruct widget to not render section – nosection1 in data-flag attribute
• Create custom section with id as sfcw_section_search.
• Optionally create custom overlay mask (see below)
• Design the HTML using class names and ids as described in the following tables

Search Controls

The user can search for courses using a keyword and/or selecting criteria from drop down boxes. To facilitate controls for each criteria you want to use is required. For example keyword text box, area drop down control and a search button.

The following table is a list of input form control ids the widget uses.

Advanced Search Controls

You can put some of the controls in a separate div that is normally hidden but is shown when the user opts for ‘advanced search’ or ‘more search options’. Use the following classes to achieve this.

Overlay Mask

There is an additional section with id sfcw_section_overlay. This section is normally included with the search courses section. It is hidden by default and is only shown during a search to indicate activity. The overlay can be dismissed at any time by the user by pressing the ESC key.

If the nosection1 data-flag is used this overlay feature will be excluded.

Example HTML

<!--
///////////////////////////
Section 1 - Search Courses
Widget was passed nosection1; flag so we can
customize our own here. section 1 contains
sfcw_section_search and optionally sfcw_section_overlay.
////////////////////
-->

<!-- This section is only displayed during a search -->
<section id="sfcw_section_overlay" style="display: none;">
<h1>Searching...</h1>
</section>

<!-- Custom search section -->
<section id="sfcw_section_search">
<!-- 3 search controls -->
<input id="sfcw_input_keyword" />
<select id="sfcw_select_area"> </select>
<select id="sfcw_select_sublocation"> </select>
<button id="sfcw_button_search" class="btn">Search</button>

<!-- Advanced search toggle control -->
<a href="#" class="sfcw-el-showHideAdvanceSearch"> </a>

<!-- Advanced search options - initially hidden -->
<div class="sfcw-subsection-advancedSearch" style= "display: none;">
<!-- advanced search controls -->
<select id= "sfcw_select_awardingBody"> </select>
<select id= "sfcw_select_award"> </select>
<select id= "sfcw_select_provider"> </select>
<select id= "sfcw_select_programme"> </select>
<select id= "sfcw_select_delivery"> </select>
</div>

</section>

Customizing Section 2 - Search Results

To custom build the course results section follow these steps:

• Instruct widget to not render section – nosection2 in data-flag attribute
• Create custom section with id as sfcw_section_results. The widget will show and hide the section as necessary.
• Design the HTML using class names and ids as described in the following tables

Inline Search Result Data

The following classes are used to populate html controls such as p, div, span, h2 etc.

Search Results in Tables

The following classes are used to populate html tables

Results Pagination

Search results are displayed in pages of 10, 25 or 50 courses at a time. Controls are provided to navigate from page to page and to change the number of courses displayed at a time.

Example HTML

<!--
///////////////////////////
Section 2 - Search Results
Widget was passed nosection2; flag so we can customize
our own here. section 2 contains sfcw_section_results
used for displaying the search result including result
totals, a table for the list of courses, a container for
pagination buttons and a container for page-size buttons.
////////////////////
-->
<section id="sfcw_section_results" style="display: none;">
<!-- legend -->
<div class="sfcw-div-legend">
<table class="sfcw-table-legend">
<tr>
<td class="legend_f fulltime_bck">F = Fulltime</td>
<td class="legend_p parttime_bck">P = Parttime</td>
<td class="legend_o online_bck">O = Online</td>
<td class="legend_e evening_bck">E = Evening</td>
</tr>
</table>
</div>
<!-- search result totals -->
<h2 class="sfcw-data-resultTotals"></h2>
<!-- table for the search results -->
<table class="sfcw-table-results">
<!-- the th elements define which data to show -->
<thead>
<tr>
<th class="sfcw-data-referenceCol"></th>
<th class="sfcw-data-titleCol"></th>
<th class="sfcw-data-providerCol"></th>
<th class="sfcw-data-locationCol"></th>
<th class="sfcw-data-dateCol"></th>
<th class="sfcw-data-categoryCol"></th>
<th class="sfcw-data-typeCol"></th>
</tr>

</thead>
<!-- required by widget -->
<tbody></tbody>
</table>

<!-- container for pagination buttons -->
<div id="sfcw_div_pages"></div>
<!-- container for page-size buttons -->
<div id="sfcw_div_perpage"></div>
</section>

Customizing Section 3 - Course Details

To custom build the course details section follow these steps:

• Instruct widget to not render section – nosection3 in data-flag attribute
• Create custom section with id as sfcw_section_details. The widget will show and hide the section as necessary. Recommended to include style="display: none;" to hide the section initially.
• Design the HTML using class names and ids as described in the following tables

Course Navigation

If the course details section is being used in conjunction with search results then it is possible to have forward, back and close navigation links.

Populating Controls with Course Data

The following classes are used to populate html controls such as p, div, span, h2 etc.

Course Data in Tables

The following classes are used to populate html tables.

Course Data in Lists

The following classes are used to populate ul controls with li items.

Show / Hide Triggers

Some controls can be shown and hidden depending on the specific course data.

Example HTML

<!--
///////////////////////////
Section 3 - Course Details
Widget was passed nosection3; flag so we can customize our
own here. Section 3 contains sfcw_section_details used for
displaying the details of the selected course. It also
contains navigation controls for walking up and down the
search results list.
////////////////////
-->
<section id="sfcw_section_details" style="display: none;">
<!-- 3 navigation controls -->
<div>
<span style="margin-right: 20px;" class="sfcw-btn-prev">previous</span>
<span style="margin-right: 20px;" class="sfcw-btn-close">close</span>
<span style="margin-right: 20px;" class="sfcw-btn-next">next</span>
</div>

<!-- placeholder for course details -->
<div>
<h2 class="sfcw-data-courseTitle"></h2>
<p class="sfcw-data-courseDescription"></p>
<p class="sfcw-data-accessAndProgression"></p>
<p class="sfcw-data-capacity"></p>
<p class="sfcw-data-courseCode"></p>
<p class="sfcw-data-courseFee"></p>
<p class="sfcw-data-deliveryMode"></p>
<p class="sfcw-data-delivertType"></p>
<p class="sfcw-data-regFee"></p>
<p class="sfcw-data-hoursPerWeek"></p>
<p class="sfcw-data-tuitionType"></p>
<p class="sfcw-data-workPlacementDays"></p>
<p class="sfcw-data-workPlacementHours"></p>
<p class="sfcw-data-learnerEducation"></p>
<p class="sfcw-data-learnerAptitude"></p>
<p class="sfcw-data-learnerPreviousExperience"></p>
<p class="sfcw-data-learningOutcomes"></p>
<p class="sfcw-data-furtherDetails"></p>
<p class="sfcw-data-targetAwardTitle"></p>
<p class="sfcw-data-providerName"></p>
<p class="sfcw-data-address1"></p>
<p class="sfcw-data-address2"></p>
<p class="sfcw-data-address3"></p>
<p class="sfcw-data-address4"></p>
<p class="sfcw-data-address5"></p>
<p class="sfcw-data-address6"></p>
<p class="sfcw-data-providerGps"></p>
<p class="sfcw-data-contactName"></p>

<div>
<p class="sfcw-el-providerPhone">Phone Number</p>
<p class="sfcw-data-contactPhone"></p>
</div>
<div>
<p class="sfcw-el-providerEmail">Email Address</p>
<p class="sfcw-data-contactEmail"></p>
</div>
<div>
<p class="sfcw-el-providerWeb">Website</p>
<p class="sfcw-data-contactWeb"></p>
</div>

<p>Modules</p>
<table class="sfcw-table-courseModules">
<tbody></tbody>
</table>

<p>Dates</p>
<table class="sfcw-table-dates"></table>

<div class="sfcw-el-timeTable">
<p>Timetable</p>
<table class="sfcw-table-timeTable">
<tbody></tbody>
</table>
</div>

<p>Facilities</p>
<ul class="sfcw-ul-providerFacilities"></ul>

<div id="sfcw_div_fees">
<p>Fees</p>
<p>Fees may apply!</p>
</div>

</div>

<div>
<span style="margin-right: 20px;" class="sfcw-btn-prev">previous</span>
<span style="margin-right: 20px;" class="sfcw-btn-close">close</span>
<span style="margin-right: 20px;" class="sfcw-btn-next">next</span>
</div>
</section>

CSS Style Sheet Customization

The widget HTML is organized under the widget placeholder with a class name of sfcw.

The html sections are each assigned a class and id as follows:

Each table has been given their own unique id to aid in CSS precedence.

Example: Changing Background and Text Colour

To change the background and foreground colours, the top-level class and some tables need to be altered.

/* Change the top level widget style */
.sfcw { background-color: #0070ba !important; color: #fff; }

/* change the results table content including a elements */
#sfcw_table_results th, #sfcw_table_results td,
#sfcw_table_results td a,
#sfcw_table_results td a:visited,
#sfcw_table_results td a:hover {
color: #fff;
border: none;
}
/* Change the courseModules table content */
#sfcw_table_courseModules th, #sfcw_table_courseModules td {
color: #fff;
border: none;
}

/* Change the navigation links on the course details screen */
.sfcw-div-detailsNav a,
.sfcw-div-detailsNav a:visited,
.sfcw-div-detailsNav a:active,
.sfcw-div-detailsNav a:focus {
color: #fff;
text-decoration: underline;
}

Course Colours

There are pre-defined course colour codes that are picked by delivery type i.e. fulltime, parttime, evening and online. These colours appear in the search results section and the course details section.

Each colour can be used as the foreground text colour or the background colour. The following classes are used

The widget will assign the appropriate foreground colour to any element with class sfcw-course-colour.

The widget will assign the appropriate background colour to any element with class sfcw-course-colour-bck.

Example: Changing the fulltime course colour to purple

/*
Change the fulltime course colour to purple
*/

/* the general style */
.sfcw .fulltime {
color: purple;
}

/* the more specific styles attached to headings */
.sfcw h1.fulltime, .sfcw h2.fulltime, .sfcw h3.fulltime {
color: purple;
}

/* the general background style */
.sfcw .fulltime_bck {
color: #fff;
background-color: purple;
}

/* the more specific background styles attached to headings */
.sfcw h1.fulltime_bck, .sfcw h2.fulltime_bck, .sfcw h3.fulltime_bck {
color: #fff;
background-color: purple;
}

Implementing the Customization

To instruct the widget to use your css style sheet, pass a url reference to the widget using the data-style-url attribute.

<script src= "https://widget.fetchcourses.ie/sfcw_init" data-providerid ="" data-style-url= "https://www.yourdomain.ie/mystyles.css"> </script>

Image and Video Course Media Customization

Custom images and videos can be embedded in the course details screen.

To include media with your course data follow these steps:

• If using custom HTML, ensure any the html includes media placeholders with associated classes
• Create a custom js file with media data
• Include the URL to the js file in the data-media-url widget attribute

Media Placeholders

The widget HTML contains 6 elements each with a media class reference from the table below.

The widget provides all 6 of these media locations in the course details section. If the HTML of the course details section is being customized then these elements will have to be placed manually (see HTML Customization).

Example

<div class=”sfcw-data-mediaP1”></div>

Custom JS File

In order to instruct the widget about which images to associate with which courses, custom javascript code is required.

The widget is contained in an object called sfcw.widget. The widget contains a public array called Course_Media that can be populated with references to images. The details required for each object entry are:

The javascript code used to add an entry to the Course_Media array is in the following format:

sfcw.widget.Course_Media.push({ courseId: "", type: 0, url: '', position: 1});

The widget also provides public constant value types that can be used

• sfcw.widget.MEDIATYPE_IMAGE = 0
• sfcw.widget.MEDIATYPE_VIDEO = 1
• sfcw.widget.MEDIALOCATION_P1 = 1
  ...
  sfcw.widget.MEDIALOCATION_P6 = 6

Example

Supposing the image happy_student.jpg, hosted at www.solas.ie, was to be associated with course id 1000 and to be displayed using media placeholder 1.

The information required is

Create a blank javascript file and enter the following line of code

sfcw.widget.Course_Media.push({ courseId: '1000', type: sfcw.widget.MEDIATYPE_IMAGE, url: 'https://www.solas.ie /happy_student.jpg', position: sfcw.widget.MEDIALOCATION_P1 });

A separate line can be added for each image and video to be included.

Instruction to Widget

The link to the widget should include the data-media-url attribute with the url to the customer js file.

Example:

<script src ="https://widget.fetchcourses.ie/sfcw_init" data-media-url = "https://www.yourdomain.ie/media.js"> </script>

Using Google Maps

The widget can be integrated with Google maps to map course locations. The maps can be integrated with the widget and/or can sit independently on the page.

Course locations are indicated with a Google Pin/Marker. The user can click on the Marker to get further information about the venue and even initiate a new search just for that location.

NOTE: To use Google Maps you require a Google Maps Javascript API Key and to place it in the data-googleapikey attribute when loading the widget. For more information visit Maps Javascript API. For the print feature the key must also be enabled with the Google Static Maps API.

The data-map attribute

Independent Maps

The Independent mode will draw maps on your page wherever a map placeholder is found. There are two types of maps that can be drawn.

<script src= "https://widget.fetchcourses.ie/sfcw_init" data-map= "both" data-googleapikey= "<<>>"> </script>

Using Social Media Icons

The widget can display social media icons with each course description. This enables the visitor to share the link to the course information on Facebook, Twitter, Google Plus, Linked-In, Twitter and Pinterest.

Setting up the widget to show social media icons is a 2 step process.

1. Font Awesome CSS

The page hosting the widget needs to include the font awesome CSS used to render the social media icons.

<link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/font-awesome/4.7.0/css/font-awesome.min.css">

2. Widget Flag

Tell the widget to display the social media icons. Do this by adding the socialicons; flag to the data-flags attribute.

<script src= "https://widget.fetchcourses.ie/sfcw_init" data-flags = "socialicons;"> </script>