Friday, April 23, 2010

What's New in the EKP 6.1 API

Although there are no major new areas of functionality in the EKP 6.1 API, there are several useful enhancements, listed herewith.

  • News feeds can now be filtered by category. Both api/publicNews and api/userNews now support an optional categoryId parameter. Why this is useful: If you are creating a topical portal, you can now restrict the articles shown to those that are relevant to the subject of the portal; for example, an onboarding portal can show articles targeted to the user, with the further restriction that only articles related to onboarding are shown.
  • api/module returns additional information. Specifically, module attributes are now returned, as are prices (currency and amount) for module sessions. (Since module attributes are not always intended for learners, they will be returned only if you authenticate as a System Administrator.) Why this is useful: Price information is essential for e-commerce portals, while module attributes can be used to retrieve implementation-specific data such as a product code to be passed to a payment gateway (if this is not the same as the EKP course ID).
  • Images specified via the Picture URL field are now available in news feeds. (Note that you can always include inline images in your articles using the HTML <img> tag.) Why this is useful: Images add impact to news articles, and being able to include those images on your portal sites will make those sites more engaging.

We hope these enhancements will make the API significantly more useful in EKP 6.1.

Monday, April 5, 2010

Images in News Feeds

EKP's API provides two functions for retrieving feeds of news articles in either RSS 2.0 or Atom 1.0 format. publicNews returns a feed of public news articles (the same articles that would appear on the login page), while userNews returns the personalized news feed for a specific user.

Previously, these feeds did not include any values for the Picture URL field configured for the articles (although they would include images included directly in the text of the articles using HTML markup). However, starting from build 6.0.0.127, these values will be included in feeds when using either the rssfull or atom format. (Picture URL values are not included when using the rssteasers format.)

Since neither RSS nor Atom include a distinct field for images, the value is included as an entity-escaped HTML img element inside the description element (for rssfull) or the content element (for atom). The unescaped img element would look similar to the example below.

<img alt='My Article'
     class='news-image'
     src='/ekp/nd/fresco/repository/myimage.jpg'>

When the img element is entity-escaped and included in a description element (for the rssfull format), the result would look as shown below.

<description>&lt;img alt='My Article' class='news-image'
src='/ekp/nd/fresco/repository/myimage.jpg'&gt; This is the text of the
article.</description>

The equivalent content element for the atom format is shown below.

<content type="html">&lt;img alt='My Article' class='news-image'
src='/ekp/nd/fresco/repository/myimage.jpg'&gt; This is the text of the
article.</description>

Note that the img element includes an attribute class='news-image', which you can take advantage of to apply special styling to these images using CSS if you are including the article text in your own Web pages. For example, the rule below ensures that all such images are floated to the right of the article text.

img.news-image {float: right;}

The rule below ensures that the images are not displayed.

img.news-image {display: none;}

If you want to use the image URL in a way that can't easily be accomplished using CSS, you could extract the URL, for example by parsing the article text into its own DOM and then applying the following XPath expression.

//img[@class="news-image"]/@src

We know that images can add significant impact to your content, and we hope that this change makes it easier for you to use news article images in your portal pages.