Tuesday, March 30, 2010

Can I create a custom search form that displays the search results enclosed in navigation frames?

I've written before about how to link to an EKP page in such a way that the navigation frames are retained. The technique described in that post works so long as the exact URL of the target page (i.e. the page that will be enclosed in the navigation frames) is known in advance.

However, what if you want to provide access to a set of pages for which the exact URLs cannot be known in advance because they depend on input from the user? In particular, what if you want to provide a custom search form that displays the search results enclosed in the navigation frames?

In this case the technique described in the previous post won't work as-is because the exact URL depends on the user's search query. For example, if the user searches for bacon then the URL of the search results page will be as shown below.

/ekp/servlet/ekp?TX=FRAMELESSCATALOGSEARCH&KEYW=bacon

With a little JavaScript ingenuity we can achieve the desired effect. The trick is to add an onsubmit handler to the search form that takes the query and uses it to construct the URL of the target page, which it then uses to populate another, hidden, form field. This requires a JavaScript function contained in a script element that we will need to include in the head of the page's HTML source.

<script type="text/javascript">
 function setMainSrc() {
  document.searchform.mainSrc.value
   = "/ekp/servlet/ekp?TX=FRAMELESSCATALOGSEARCH&KEYW="
   + encodeURIComponent(document.searchform.KEYW.value);
 }
</script>

Below is the form itself, including both onsubmit handler and hidden field.

<form action="/ekp/servlet/ekp/pageLayout"
      name="searchform"
      onsubmit="setMainSrc(); return true;">
 <input name="KEYW" type="text">
 <input name="mainSrc" type="hidden">
 <input type="submit" value="Search">
</form>

When the user enters a query and clicks the Search button, he or she will see EKP's search results page enclosed in the standard navigation frames, even though the original page did not include any frames.

Tuesday, March 9, 2010

How can I hide the Logout link that appears as part of EKP's navigation controls?

By default EKP displays a Logout link as part of its navigation controls. In some cases it might be desirable to hide this link, in particular if EKP is being used in conjunction with a single sign-on solution in which it is not desired to provide application-specific sign-out functions.

This post describes a simple way to hide the Logout link using a Cascading Style Sheets (CSS) rule. Because it is CSS-based, this technique can be applied to specific skins, such that the Logout link appears only for specific groups of users depending on their skin setting.

The technique relies on the fact that, in most skins, the Logout link is the only element with both a class='sec-links' attribute and a target='_top' attribute. Therefore, applying the CSS rule shown below has the effect of hiding the Logout link without affecting other navigation links.

.sec-links[target="_top"] {display: none;}

For skins in which the Logout link appears in the left frame (or the right frame for right-to-left skins), this rule should be added to the file named left.css inside the skin directory. For example, for the EKP-60 skin the rule would be added to the file named left.css inside the nd/fresco/styles/EKP-60/ directory. For skins in which the Logout link appears in the top frame, this rule should be added to the file named top.css inside the skin directory.

This technique should work for most recent skins. It might not work for certain older skins, in particular those that use images for button labels.

Monday, March 8, 2010

Creating a custom sign-up form using PHP

EKP provides a built-in sign-up (self-registration) function for new users. However, there are situations in which you might want to provide a custom sign-up form, particularly if users are accessing EKP's functionality via a portal.

  • A custom sign-up form provides you with complete control of the “look and feel” of your sign-up page.
  • A custom sign-up form enables you to control what happens at the end of the sign-up process. For example, instead of directing users to a standard EKP start page, you can direct them to a page within a learning portal.

This post outlines how you might go about creating a custom sign-up page using PHP.

The first step is to create the sign-up form itself. This might reside in a file named signup.php for example.

<form action="handlesignup.php" method="POST">
    User ID: <input name="userid" type="text" maxlength="85">
    <br>
    Password: <input name="password" type="password">
    <br>
    Family Name: <input name="familyname" type="text" maxlength="85">
    <br>
    Given Name: <input name="givenname" type="text" maxlength="85">
    <br>
    <input type="submit" value="Sign Up">
</form>

When user submits this form, the browser will send an HTTP POST request to another PHP script named handlesignup.php. The example below shows what the code in this file might look like.

<?php

// defines $ekp_base, $auth_key
require 'config.php';

// Grab the parameters from the request
$user_id = $_POST['userid'];
$password = $_POST['password'];
$family_name = $_POST['familyname'];
$given_name = $_POST['givenname'];
// Other fields as needed...

// Format as CSV for the contentHandler/usersCsv API function
// CSV data consists of two lines: one for headers, and one for data
// Full list of permitted fields is same as for User Data Loader
// Note that almost all fields are optional
$data = '"Action","UserID","Password","FamilyName","GivenName"' . "\r\n"
      . '"A","' . $user_id . '","' . $password . '","' . $family_name . '","'
      . $given_name . '"';

// Use cURL to POST the CSV data to EKP
// Note that the profile parameter is optional
$ch = curl_init($ekp_base . 'contentHandler/usersCsv?profile=signupprofile');
curl_setopt($ch, CURLOPT_POST, TRUE);
curl_setopt($ch, CURLOPT_HTTPHEADER, array("Content-Type: text/csv"));

// Although EKP ignores the user name, a non-empty value must be used
// otherwise cURL will not include the authentication header
$user_name = "dummy";
curl_setopt($ch, CURLOPT_USERPWD, $user_name . ":" . $auth_key);

curl_setopt($ch, CURLOPT_POSTFIELDS, $data);
$result = curl_exec($ch);

curl_close($ch);

// Now show a confirmation page to the user, or redirect him or her to an
// appropriate page.

?>

<html>
    <head>
        <title>Sign-Up Completed</title>
    </head>
    <body>
        <h1>Thanks for signing up!</h1>
    </body>
</html>

Known issues

  • The code above does not attempt to escape the double quotation mark character ("), which has a special meaning in CSV, when it occurs in field values. In order to guard against possible data-injection attacks, the code should really replace each occurrence of this character with two instances of the character.
  • The code does not perform any validation of the input. A more robust example would validate the user input before calling the API function.
  • As a special case of the above, it is common on sign-up forms to ask the user to re-type his or her password, since a mistyped password might prevent the user from accessing his or her account. The example code shown here does not do this.

Wednesday, June 17, 2009

Publishing a podcast using the News Manager

EKP 5.6 provides RSS feeds both for public news on the login page and for personalized news on a learner's home page. (Note: RSS feeds are available only if your license includes API access.)

RSS feed link on Home Page

In EKP 5.6.0.129 we have added support for RSS enclosures. Roughly speaking, RSS enclosures serve the same purpose as email attachments—they make is possible to attach a file of arbitrary type to a text message. Probably the most interesting consequence of this change is that it's now possible to use the News Manager to publish a podcast. Here's how.

  1. Record a podcast episode, edit it as necessary, and save as an appropriate media file (audio or video). There are many tools available for recording, editing and encoding media files. For audio, we suggest Audacity for recording and editing, with the LAME MP3 encoder to generate MP3 files.

  2. Upload your media file to the Repository Manager.

    Uploading an MP3 file to the Repository Manager
  3. Create a news article in the News Manager. For the File Attachment URL field, select the media file you uploaded in the previous step. Make sure the article is targeted to the appropriate audience, and publish as usual.

    Creating a news article with attached MP3 file
  4. A listener/viewer can subscribe to an appropriate RSS feed using a “podcatcher” such as Apple's iTunes. The podcatcher will download new podcast episodes as they are made available. The episodes can then be played offline, and can also be synchronized to devices such as portable MP3 players and phones.

    Subscribed podcast in iTunes

Friday, June 5, 2009

The API Explorer

EKP provides an application programming interface (API) that enables other applications and Web sites to interact with EKP—for example, to create user accounts and enrollments, and to obtain information about courses, catalogs, enrollments and training records.

We've always provided API documentation as part of the EKP distribution. However, in working with software developers, we've identified a couple of ways in which the documentation could be improved.

Firstly, the API changes between releases as new API functions are added. This means it's important to work with the correct version of the documentation for the EKP version you're developing for. However, keeping track of different document versions is a hassle.

Secondly, most developers learn more easily if they are able to call API functions interactively and generate actual responses, rather than simply reading dry documentation. However, calling API functions generally involves writing code.

With these points in mind, in EKP 5.6 we introduced the API Explorer. The API Explorer serves two purposes: it is both an online reference for the API functions, and a tool that enables developers to learn about the API by calling its functions interactively.

Enterprise Knowledge Platform API

The API Explorer lists the API functions available. For each function, it provides information about how to invoke the function, including the URL and the expected HTTP method, parameters and authentication scheme. Where possible, it provides one or more HTML forms that can be used to call the API function directly from the browser. (Note: some API functions cannot be invoked from a browser.)

userNews API function

The API Explorer can be accessed by appending api/ to the base URL of your EKP site. For example, if your site is located at http://www.example.com/ekp/, then the API Explorer for the site can be accessed at http://www.example.com/ekp/api/. At the time of writing, an instance of the API Explorer is available at http://utest2.netdimensions.com/utest/api/.

Note: If you do not see the API Explorer at the expected URL, your Web server (e.g. Apache or IIS) might not be forwarding the requests to Tomcat. In the case of Apache, you can fix this by adding a directive like the one below to httpd.conf.

JkMount /ekp/api/* ajp13

Wednesday, June 3, 2009

Publishing a new course revision to learners who have already completed an earlier revision

EKP 5.5 introduced the ability to create new revisions of existing courses. This simplified the process of updating an existing course, and made it possible to keep track of which version of a course a learner was taking or had completed.

When you created a new revision of a course, EKP would automatically make the new revision available to learners who were enrolled in, but had not yet started, an earlier revision. EKP also provided the option to make the new revision available to learners who had already started, but had not yet completed, an earlier revision.

Since we released support for course revisions, several of you have told us that you also needed to be able to make new revisions automatically available to users who had already taken and completed an earlier revision of the course, so that those learners would see the latest content if they reviewed the completed course. So, as of EKP 5.6.0.122, there is a third option when creating a new course revision, which publishes the new revision to all learners, including those who have already completed an earlier revision.

Confirm New Course Revision

We hope this makes course revisions in EKP even more useful.

Tuesday, May 26, 2009

How to bulk import courses that do not have distinct identifiers in their course descriptions

EKP features bulk import utilities for both SCORM and AICC content. Using these utilities, you can package multiple courses into a zip file which you can then upload. EKP will create online modules based on the course descriptions in the zip file. In addition to information on how to launch and track the courses, EKP will extract descriptive information such as course titles, descriptions, objectives and so on. This is extremely handy if you need to import catalogs of hundreds or even thousands of courses.

Previously, the ID fields that EKP would use for the new modules would also be extracted from the course description files. While this usually works well, it fails if the course description files contain duplicate identifiers, since each module in EKP needs to have a distinct ID. This might happen for example if the course description files were created by copying a template and making only minimal changes.

Starting from version 5.6.0.119, the bulk import utilities provide an option to generate module IDs based on the file names of the imported items instead of the identifiers contained within course descriptions themselves. This provides an easy way to import large numbers of courses even if the identifiers within the course descriptions are not distinct.

How do you want the system to select IDs for the courses in this package? * Use IDs specified in the course descriptions * Use the base file names of the source files

The default is to use the identifiers specified in the course description files, as before. If you choose to generate IDs based on the file names and the items being imported are content packages, the IDs used will be the names of the “inner” zip files, without the .zip extension. If the items being imported are sets of AICC course structure files, the IDs used will be the base file names—for example, if one of the sets uses the file names course1.au, course1.crs, course1.cst and course1.des, then the ID used will be course1.

We know that many of you rely on the bulk import utilities to set up and updates your course catalogs, and we hope that this change makes them even more useful.