JumpKnowledge Button Technical Guide

My Saved Knowledge / Sign In / Register

See what we've been up to lately updated Friday, May 11, 2007

Technical Guide

The purpose of this guide is to allow any site to integrate with the JumpKnowledge Annotation Engine directly without having to use the Custom Button Wizard.

For example:

If you have a blog service, you can programmatically add the JumpKnowledge icon next to every blog post. This would allow a reader to click the icon and annotate only that blog post. (If the Custom Button Wizard was used, the icon would annotate all the blog posts on the page.)
If you have an email newsletter service, you can programmatically add an icon to every published email for email recipients to "annotate the email & forward to a friend". (If the Custom Button Wizard was used, you would need to create a new button for every email newsletter.)

Sites that are program driven (e.g., ASP, JSP, ColdFusion, etc) are the best candidates for full integration.

Invoking the JumpKnowledge service

The JumpKnowledge syntax is very simple to learn and use. All you have to do is construct a hyperlink or form with the service name and parameters.

The service name is http://jkn.com/Annotate

If you use the hyperlink construct, all parameter values that Encode=Yes must be encoded (see below). However, if you use the form construct, do not encode the parameter values because a form automatically encodes them for you.

Parameters

Parameter Name	Parameter Value	Encode	Required
v	The version number must be set to ap102. If you change this version number without authorization, it may break backwards comparability.	No	Yes
url	The web page that is to be annotated. The URL must be publicly accessible. If the url parameter is not supplied, then the URL is obtained from the Referer header. However, the referer header is not completely reliable because: Some users configure their browsers to suppress the Referer header. Some companies configure their web proxy to suppress the Referer header for security reasons. When a user clicks a hyperlink in an email, Referer is not set. Therefore, it's best to explicitly pass in the url.	Yes	Yes
returnurl	The web page that the user is returned to if the user cancels the annotation in middle. The web page that user is given as an option to return to when the annotation is completed. If this parameter is not supplied, then it defaults to the url parameter.	Yes	No
logo	A jpg or gif image that will be displayed in the top right-hand corner of the Annotation page. If a logo is not supplied, then the JumpKnowledge logo is displayed. The suggested size for the logo is 60 pixels high and 250 pixels wide	Yes	No
charset	The charset of the web page specified by the URL. Although this parameter is not strictly required, it will improve performance if you supply it. But be careful to specify the correct charset. It can be specified on upper or lower case. These are common charsets: US-ASCII, ISO-8859-1, UTF-8, UTF-16BE, UTF-16LE, UTF-16	No	Yes
type	The primary action that the user wants to perform email blog save print none If this parameter not supplied, then it defaults to none.	No	No

Examples

We color coded the various components to make it easier to understand the HTML code

Service Name is pink.
Parameter Names are blue
Parameter Values are green
Standard HTML markup is black.

Both of the examples below will bring up a Google search page to annotate & email. If canceled, you will be returned to Yahoo's home page. This demonstrates how the page to annotate can be different then the page to return to when canceled. In these examples, we are popping up the annotate window. If you prefer not to popup another window, just remove target="_blank".

Method	Example	Working Demo
hyperlink	<a target="_blank" href="http://jkn.com/Annotate?v=ap102 &url=http%3A%2F%2Fwww.google.com %2Fsearch%3Fhl%3Den%26q%3Dcan%2527t%2Bbuy%2Blove &returnurl=http%3A//yahoo.com &charset=utf-8"&type=email>Annotate Google & Email</a>	Annotate Google & Email
form	<form name="jkn" action="http://jkn.com/Annotate" target="_blank"> <input type="hidden" name="v" value="ap102" /> <input type="hidden" name="url" value="http://www.google.com/search? hl=en&q=can%27t+buy+love" /> <input type="hidden" name="returnurl" value="http://yahoo.com" /> <input type="hidden" name="charset" value="utf-8" /> <input type="hidden" name="type" value="email" /> <a href="#" onclick="document.jkn.submit();return false">Annotate Google & Email </a> </form>	Annotate Google & Email

Encoding

One of the most common mistakes that developers make when integrating to a service like JumpKnowledge is failing to encode parameter values. Not all parameter values have to be encoded, but parameter values that contain characters like &$,:;=?@<>% must be encoded. In the case of JumpKnowledge: url, returnurl, and logo all have to be encoded.

Encoding is programming language specific, so we prepared a list of encoding functions for popular programming languages (see below). If your programming language is not listed, please post it in the forum and we'll research it for you.

Encoding Spaces and + (plus)

There is a point of contention in the encoding specification over how to encode the space and + (plus) characters.

Some encoding functions encode a space as + and + as %2B.
Some encoding functions encode a space as %20 and a + does not get encoded.
The newest encoding functions encode a space as %20 and + as %2B so there is no confusion.

In practice, all encoding functions should work with JumpKnowledge, but if you have a choice between the three, we recommend you use the newest method as it is the most reliable since it's the least prone to confusion.

Online Websites to Encode

You can use these online websites to manually encode parameter values.

http://www.barelyfitz.com/projects/encoder/ Choose encodeURIComponent	This website will encode a space as %20 and + as %2B
http://www.barelyfitz.com/projects/encoder/ Choose encodeURI	This website will encode a space as %20 and + will not be encoded
http://meyerweb.com/eric/tools/dencoder	This website will encode a space as + and + as %2B

Encoding Functions

Programming Language	Function	Notes
ASP / VB.NET	Server.URLEncode(paramval )
Coldfusion	URLEncodedFormat(paramval )
JavaScript	encodeURIComponent( paramval )	Do not use escape() or encodeURI()
Java	java.net.URLEncoder(paramval, "utf-8" )
JSP	If you hare using the JSTL, use the url and param tags which have encoding built in. If not, use *java.net.URLEncoder( paramval, "utf-8" )* from Java
.NET	HttpServerUtility.UrlEncode(paramval)	Do not use HtmlEncode
Perl	uri_escape( paramval )
PHP	urlencode( $paramval )
Python	urllib quote( $paramval )
Ruby	URI.escape(paramval, Regexp.new("[^#{URI::PATTERN::UNRESERVED}]"))	See here for more details

Support

Confused or frustrated? You don't have to be that way. Help is on the way. Don't run—jump on over to the JumpKnowledge Forum for your must troublesome issues. Feedback and feature requests are also welcome.

We want you to be happy! Your feedback is very important to us. Please submit your feedback here

Your usage of jkn.com is governed by your Terms of Service