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.