Creating a New iSites Tool

Creating a New iSites ToolGetting Past Hello [iSites]

Bobbi Fox, Office for Information Systems

Harvard University Libraryabcd-www 11 August 2010

I Built A Really Neat Widget Generator…

http://hul.harvard.edu/ois/systems/webservices/widgets/xsearch_wizard.html

That page used:• jquery-1.3.2.js• jquery-ui-1.7.2.custom.js• SmartWizard.js (modified by yrs truly)• jquery.quicksearch.js (ditto)• scrollabletable.js• chromatable.js (to keep MSIE happy)

… plus some stuff I cooked up.

(jQuery is soooo cool)

“Great, now go create an iSites version!”

But, but, but: I don’t work for iCommons, or have access to their servers/environment!

News That Surprised Me -- Part I

The html for your Tool is hosted, and served, by your server. This means that:

‼ Any persistent Tool configuration information must be stored on your server.

‼ Any persistent data needed for your Tool’s Topics must be stored on your server.

... To be continued…

What Wasn’t A Surprise

You don’t get to control

the Vertical

the Horizontal

All images on this page by Turnvater Jahn used under the Creative Commons Attribution-Share Alike license.

iSites Tool Development Basics

Developer's Guide for iSites Tools

http://isites.harvard.edu/developer_help

Some Definitions

(from the Developer's Guide for iSites Tools glossary)

Tool:

A software program that manages content in an iSite. Topic Box:

An instance of a Tool on an iSites page. View:

A piece of XHTML generated by a Tool and displayed in

an iSites page in response to an HTTP “GET”

Basic: How iSites Works*

For each Topic Box on the page:

1. iSites Core makes a RESTful call to the Tool’s server

2. The Tool’s server returns W3C compliant XMHTML

3. iSites Core applies its own “chrome:” styles, images, <divs>, etc. – including special <form> handling.

* This is a “High Concept” description only. YMMV

Diagram courtesy of David Heitmeyer of iCommons

How iSites Works

What the iSites “Core” Manages

• Authentication of the user (if required)• The permission level of the user• The Tool ID• The Topic ID• Placement of a Topic Box within a page

What Your Tool Manages

Any configuration data necessary to your Tool

Any other data used by your Tool

The code that produces your XHTML

What You Provide to iSites

At minimum:A URL to your “view” on your server, resulting in

W3C-conformant xhtml code of that view

For configuration, if any:A URL to your “edit” presentation on your server, resulting in

W3C-conformant xhtml code of that view

For forms that go to your server:A URL to your server that accepts “POST”, with your server

prepared to send a redirect after processing

Creating Views

Diagram courtesy of David Heitmeyer of iCommons

Creating Views

• Can take advantage of jQuery and/or Ext Js JavaScript libraries

• Can add JavaScript either in-line or as an additional upload.

<script src="tool:js/libSrch.js" type="text/javascript"

charset="utf-8"></script> <script src=“http://YOURURLHERE/js/libSrch.js"

type="text/javascript" charset="utf-8"></script>

• Can sometimes take advantage of objects, images, and CSS already created by iSites.

Must be W3C-compliant XHTML

Creating Views (cont’d)

Adding CSS is tricky.

(I use jQuery.rule to load in the additional CSS I need )

Be vewy, vewy careful!

Creating the Default View

The Default View is what the user sees when the Topic Box is first created.

Note: it’s now recommended to start with a default configuration, so the Administrator need do nothing else for the Topic Box to display.

Params in the URL requestParam Name Description

userid Encrypted with RC4 encryption, needs “shared key”

keyword iSites keyword for the site

siteId

siteType 12 == Standard, 10 == my.harvard

topicId Topic Box (Instantiation) ID

coreToolId ID of your tool – assigned by iCommons

urlRoot The URL root of the page

remoteAddr IP of the requesting browser

permissions Permissions for that user

pageContentId

pageid

context See next several slides…

state “edit”, “view”…

News That Surprised MePart II

‼ When iSites creates, copies (“clones”), or deletes a Topic Box, it POSTs to your server.

The URL is of a fixed format: {your_base_URL}/isitestool/create.do

{your_base_URL}/isitestool/clone.do {your_base_URL}/isitestool/delete.do

iSites doesn’t care what status code you return.

... To be continued…

isitestool/create.do

When the user first places your tool on a page, iSites POSTs to your server:

{your_base_URL}/isitestool/create.do?{all the params}

IF you process this, and return a status of 200 (“Success”), you can return a string. This becomes the value of any subsequent “context” parameter.

(I use it to contain the version number)

News That Surprised MePart II, Cont’d

If your service either doesn’t process the isitestool/create.do at all, or doesn’t return a string,

iSites assigns “failed” to the context parameter.

Subsequent calls for that Topic Box will look like this:

?context=failed&topicId=icd1234&…

... To be continued…

isitestool/clone.do

When the user copies a Topic Box instance of your tool on a page, iSites POSTs to your server:

{your_base_URL}/isitestool/clone.do?{all the params}

Where: topicId={the new Topic Box Id }, context={context of the old Topic Box}oldTopicId={‘Copied From’ ID}

IF you process this, and return a status of 200 (“Success”), you can return a string. This becomes the value of any subsequent “context” parameter for the new Topic Box.

(I again use it to contain the version number)

isitestool/delete.do

Best Practice:

If you are tracking Topic Boxes in your database, and are handling this request, it’s better to deactivate the record, rather than delete it.

iSites and Forms

• iSites “massages” your form on the way in.• The <form> element is massaged

• The parameter names are manipulated

• The “submit” action goes to iSites core, which then submits a POST to your Tool server

• Your tool then processes the input, and provides a redirect.

iSites and Forms (cont’d)

<form> before:

<form

method="get"

action="libSearchEdit.do”

class="isites-form" name="mXSNew">

<form> After

<form accept-charset="utf-8" id="formicb_pagecontent716693_mXSNew_" method="post"action="http://isites.harvard.edu/icb/icb.do?

keyword=k68465&amp;panel=icb.pagecontent716693%3ArlibSearchEdit%248&amp;pageid=icb.page.topiceditgeneral.icb.topic768276.icb.page346294&amp;pageContentId=icb.pagecontent716693&amp;state=edit&amp;action=libSearchEdit.do"

onsubmit="if (!doDefault(document.getElementById('formicb_pagecontent716693_mXSNew_'))) return false;return validate(document.getElementById('formicb_pagecontent716693_mXSNew_'));" class="isites-form" name="mXSNew" enctype="application/x-www-form-urlencoded">

Parameter Names In Forms

Before<input id="first"

name="rRsrc"

value=“Recommended resources" size="40" maxlength="60" type="text">

After<input id="first" name="rRsrcValue" value="Recommended resources" size="40" maxlength="60"

type="text"> <input value="rRsrc" name="inputField" type="hidden">

The Form Submit Process

Diagram courtesy of David Heitmeyer of iCommons

My Initial iSites Prototype:

Unbeknownst To Me…

…There already was a non-editable Library Search widget on iSites…

You do have to ask iCommons for the details, however.

iSites has some nice JS to use

Uses:

<textarea class=" editor" …>

Uses Ext.TabPanel:

…and some nice CSS

<div class="warning“>

<div class= "info">

[I don’t have an example of that]

<div class="update">

Speaking of CSS…

The official line is that you can’t include a CSS stylesheet, but you can use style=“foo” on elements

However, since you can include javascript, you can effect style changes that way.

e.g.: jQuery.rule (http://flesler.blogspot.com/2007/11/jqueryrule.html)

(Have I mentioned that jQuery is wicked cool? :-)

Using jQuery.rule

$.rule('div#mXS_selResources ul { display:block;background:#CEDFF5; padding: .5em .2em .5em;}')

.appendTo(sheet);• Make sure your styles are confined to

your own classes/id’s.• Be aware that Internet Explorer doesn’t

like commas!

There Are Also Lots Of Icons…

iCommons has most of the images from:

• famfamfam.com(link to preview page)

• fugue-icons-srchttp://code.google.com/p/fugue-icons-src/

(link to preview page)

Putting It All Together…

Display view

Putting It All Together (cont’d)…Edit View, top half

Putting It All Together (cont’d again)…

What You Initially Need From iCommons

Initial Tool setup to tell iSites:• The name of the tool• The URL of the “view”• The URL of the “edit” (if any)• Who has permissions:

– Owner(s)– Viewer(s)– Participant(s)

• Decryption key for the userId[All done through the iSites Admin Site]

iSites Help

You must ask iCommons to set up help pages for you, which you then get to edit.

Something That Would Be Really Nice To Have

A Testing Harness/Framework

Because so much else is happening on an iSites page*, it is difficult to trouble-shoot problems.

I’ve found that I can sometimes use the FF “View Selection Source” when the Topic Box shows an error. This really isn’t the way to solve the problem, however.

* Which always renders with warnings in an HTML validation

Suggested Improvements To The Process*

Documentation• How the Tool “permissioning” process works• Cool/Useful CSS styles already available• Cool/useful “widgets” (such as the text editor)

already available• “Head’s up” on changes in new versions

CommunityIt would be nice if iCommons could make us aware of

each other.In response to this in my talk, this document will appear after September 15

http://isites.harvard.edu/icb/icb.do?keyword=developer_help&tabgroupid=icb.tabgroup111715

Acknowledgments

From iCommons:David Heitmeyer, Colin Murtaugh,Kim Edelman, and David McElroy

From ATG:Annie Rota and Katie Vale

From Harvard Divinity School:Gloria Korsman and Susan Worst (my “guinea pigs” :-)

From OISJulie Wetherill and the wonderful OPS folksh/t Janet H. Taylor

Questions?

Bobbi Fox

Office for Information Systems

Harvard University Library

[email protected]