Creating a New iSites Tool


Published on

Bobbi Fox has provided slides from her talk on "Creating a New iSites Tool" at the August 11 ABCD-WWW / HarvardWWW working group meeting at Harvard University.

Bobbi works in the Office for Information Systems, Harvard University Library

Published in: Education
  • Be the first to comment

  • Be the first to like this

No Downloads
Total views
On SlideShare
From Embeds
Number of Embeds
Embeds 0
No embeds

No notes for slide
  • Note: a string , not an html page .
  • Note: a string , not an html page .
  • Creating a New iSites Tool

    1. 1. Creating a New iSites Tool Getting Past Hello [ iSites ] Bobbi Fox, Office for Information Systems Harvard University Library abcd-www 11 August 2010
    2. 2. I Built A Really Neat Widget Generator…
    3. 3. <ul><li>That page used: </li></ul><ul><li>jquery-1.3.2.js </li></ul><ul><li>jquery-ui-1.7.2.custom.js </li></ul><ul><li>SmartWizard.js ( modified by yrs truly) </li></ul><ul><li>jquery.quicksearch.js ( ditto ) </li></ul><ul><li>scrollabletable.js </li></ul><ul><li>chromatable.js ( to keep MSIE happy ) </li></ul><ul><li>… plus some stuff I cooked up. </li></ul>(jQuery is soooo cool)
    4. 4. “ Great, now go create an iSites version!” <ul><li>But, but, but: I don’t work for iCommons, or have access to their servers/environment! </li></ul>
    5. 5. News That Surprised Me -- Part I <ul><li>The html for your Tool is hosted, and served, by your server. This means that: </li></ul><ul><ul><li>Any persistent Tool configuration information must be stored on your server. </li></ul></ul><ul><ul><li>Any persistent data needed for your Tool’s Topics must be stored on your server. </li></ul></ul><ul><li>... To be continued… </li></ul>
    6. 6. What Wasn’t A Surprise You don’t get to control All images on this page by Turnvater Jahn used under the Creative Commons Attribution-Share Alike license. the Vertical the Horizontal
    7. 7. iSites Tool Development Basics <ul><li>Developer's Guide for iSites Tools </li></ul><ul><li> </li></ul>
    8. 8. Some Definitions <ul><li>(from the Developer's Guide for iSites Tools glossary ) </li></ul><ul><li>Tool: </li></ul><ul><li>A software program that manages content in an iSite. </li></ul><ul><li>Topic Box: </li></ul><ul><li>An instance of a Tool on an iSites page. </li></ul><ul><li>View: </li></ul><ul><li>A piece of XHTML generated by a Tool and displayed in an iSites page in response to an HTTP “GET” </li></ul>
    9. 9. Basic: How iSites Works* <ul><li>For each Topic Box on the page: </li></ul><ul><li>iSites Core makes a RESTful call to the Tool’s server </li></ul><ul><li>The Tool’s server returns W3C compliant XMHTML </li></ul><ul><li>iSites Core applies its own “chrome:” styles, images, <divs>, etc. – including special <form> handling. </li></ul><ul><li>* This is a “High Concept” description only. YMMV </li></ul>
    10. 10. Diagram courtesy of David Heitmeyer of iCommons How iSites Works
    11. 11. What the iSites “Core” Manages <ul><li>Authentication of the user (if required) </li></ul><ul><li>The permission level of the user </li></ul><ul><li>The Tool ID </li></ul><ul><li>The Topic ID </li></ul><ul><li>Placement of a Topic Box within a page </li></ul>
    12. 12. What Your Tool Manages <ul><li>Any configuration data necessary to your Tool </li></ul><ul><li>Any other data used by your Tool </li></ul><ul><li>The code that produces your XHTML </li></ul>
    13. 13. What You Provide to iSites <ul><li>At minimum: </li></ul><ul><li>A URL to your “view” on your server, resulting in </li></ul><ul><ul><li>W3C-conformant xhtml code of that view </li></ul></ul><ul><li>For configuration, if any : </li></ul><ul><li>A URL to your “edit” presentation on your server, resulting in </li></ul><ul><ul><li>W3C-conformant xhtml code of that view </li></ul></ul><ul><li>For forms that go to your server: </li></ul><ul><li>A URL to your server that accepts “POST”, with your server </li></ul><ul><ul><li>prepared to send a redirect after processing </li></ul></ul>
    14. 14. Creating Views Diagram courtesy of David Heitmeyer of iCommons
    15. 15. Creating Views <ul><li>Can take advantage of jQuery and/or Ext Js JavaScript libraries </li></ul><ul><li>Can add JavaScript either in-line or as an additional upload. </li></ul><ul><li><script src=&quot; tool:js/libSrch.js &quot; type=&quot;text/javascript&quot; charset=&quot;utf-8&quot;></script> </li></ul><ul><li><script src=“ http://YOURURLHERE/js/libSrch.js &quot; type=&quot;text/javascript&quot; charset=&quot;utf-8&quot;></script> </li></ul><ul><li>Can sometimes take advantage of objects, images, and CSS already created by iSites. </li></ul>Must be W3C-compliant XHTML
    16. 16. Creating Views (cont’d) <ul><li>Adding CSS is tricky. </li></ul><ul><li>(I use jQuery.rule to load in the additional CSS I need ) </li></ul><ul><li>Be vewy, vewy careful! </li></ul>
    17. 17. Creating the Default View <ul><li>The Default View is what the user sees when the Topic Box is first created. </li></ul>Note: it’s now recommended to start with a default configuration, so the Administrator need do nothing else for the Topic Box to display.
    18. 18. Params in the URL request Param 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”…
    19. 19. News That Surprised Me Part II <ul><li>When iSites creates, copies (“clones”), or deletes a Topic Box, it POSTs to your server. </li></ul><ul><li>The URL is of a fixed format: </li></ul><ul><li> {y our_base_URL }/isitestool/ create .do </li></ul><ul><li>{ your_base_URL }/isitestool/ clone .do </li></ul><ul><li>{ your_base_URL }/isitestool/ delete .do </li></ul><ul><li>iSites doesn’t care what status code you return. </li></ul><ul><li>... To be continued… </li></ul>
    20. 20. isitestool/ <ul><li>When the user first places your tool on a page, iSites POSTs to your server: </li></ul><ul><li>{ your_base_URL }/isitestool/ create .do? {all the params} </li></ul><ul><li>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. </li></ul><ul><li>(I use it to contain the version number) </li></ul>
    21. 21. News That Surprised Me Part II, Cont’d <ul><li>If your service either doesn’t process the isitestool/ at all, or doesn’t return a string, </li></ul><ul><li>iSites assigns “failed” to the context parameter. </li></ul><ul><li>Subsequent calls for that Topic Box will look like this: </li></ul><ul><li>?context=failed&topicId=icd1234&… </li></ul><ul><li>... To be continued… </li></ul>
    22. 22. isitestool/ <ul><li>When the user copies a Topic Box instance of your tool on a page, iSites POSTs to your server: </li></ul><ul><li>{ your_base_URL }/isitestool/ ? { all the params} </li></ul><ul><li>Where: </li></ul><ul><li>topicId ={the new Topic Box Id }, </li></ul><ul><li>context ={context of the old Topic Box} </li></ul><ul><li>oldTopicId ={‘Copied From’ ID} </li></ul><ul><li>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 . </li></ul><ul><li>(I again use it to contain the version number) </li></ul>
    23. 23. isitestool/ <ul><li>Best Practice: </li></ul><ul><li>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. </li></ul>
    24. 24. iSites and Forms <ul><li>iSites “massages” your form on the way in. </li></ul><ul><ul><li>The <form> element is massaged </li></ul></ul><ul><ul><li>The parameter names are manipulated </li></ul></ul><ul><li>The “submit” action goes to iSites core, which then submits a POST to your Tool server </li></ul><ul><li>Your tool then processes the input, and provides a redirect. </li></ul>
    25. 25. iSites and Forms (cont’d) <ul><li><form> before: </li></ul><ul><li><form </li></ul><ul><li>method =&quot;get&quot; </li></ul><ul><li>action =&quot;” </li></ul><ul><li>class =&quot;isites-form&quot; name =&quot;mXSNew&quot;> </li></ul>
    26. 26. <form> After <ul><li><form accept-charset=&quot;utf-8&quot; </li></ul><ul><li>id=&quot;formicb_pagecontent716693_mXSNew_&quot; </li></ul><ul><li>method =&quot;post&quot; </li></ul><ul><li>action =&quot;;panel=icb.pagecontent716693%3ArlibSearchEdit%248&amp;;pageContentId=icb.pagecontent716693&amp;state=edit&amp;; </li></ul><ul><li>onsubmit=&quot;if (!doDefault(document.getElementById('formicb_pagecontent716693_mXSNew_'))) return false;return validate(document.getElementById('formicb_pagecontent716693_mXSNew_'));&quot; class=&quot;isites-form&quot; name=&quot;mXSNew&quot; enctype=&quot;application/x-www-form-urlencoded&quot;> </li></ul>
    27. 27. Parameter Names In Forms <ul><li>Before </li></ul><ul><li>< input id=&quot;first&quot; </li></ul><ul><li>name=&quot;rRsrc&quot; </li></ul><ul><li>value=“Recommended resources&quot; size=&quot;40&quot; maxlength=&quot;60&quot; type=&quot;text&quot;> </li></ul>After < input id=&quot;first &quot; name=&quot;rRsrcValue&quot; value=&quot;Recommended resources&quot; size=&quot;40&quot; maxlength=&quot;60&quot; type=&quot;text&quot;> < input value=&quot;rRsrc&quot; name=&quot;inputField&quot; type=&quot;hidden&quot;>
    28. 28. The Form Submit Process Diagram courtesy of David Heitmeyer of iCommons
    29. 29. My Initial iSites Prototype:
    30. 30. Unbeknownst To Me… … There already was a non-editable Library Search widget on iSites…
    31. 31. <ul><li>You do have to ask iCommons for the details, however. </li></ul>iSites has some nice JS to use Uses: <textarea class=&quot; editor&quot; …> Uses Ext.TabPanel:
    32. 32. … and some nice CSS <ul><li><div class= &quot; warning “> </li></ul><div class= &quot; info &quot;> [I don’t have an example of that] <div class= &quot; update &quot;>
    33. 33. Speaking of CSS… <ul><li>The official line is that you can’t include a CSS stylesheet, but you can use style=“foo” on elements </li></ul><ul><li>However, since you can include javascript, you can effect style changes that way. </li></ul><ul><li>e.g.: jQuery.rule ( ) </li></ul><ul><li>( Have I mentioned that jQuery is wicked cool? :-) </li></ul>
    34. 34. Using jQuery.rule <ul><li>$.rule('div#mXS_selResources ul { display:block;background:#CEDFF5; padding: .5em .2em .5em;}') </li></ul><ul><li>.appendTo(sheet); </li></ul><ul><li>Make sure your styles are confined to your own classes/id’s. </li></ul><ul><li>Be aware that Internet Explorer doesn’t like commas! </li></ul>
    35. 35. There Are Also Lots Of Icons… <ul><li>iCommons has most of the images from: </li></ul><ul><li> </li></ul><ul><li>(link to preview page) </li></ul><ul><li>fugue-icons-src </li></ul><ul><li> </li></ul><ul><li>(link to preview page) </li></ul>
    36. 36. Putting It All Together… <ul><li>Display view </li></ul>
    37. 37. Putting It All Together (cont’d)… <ul><li>Edit View, top half </li></ul>
    38. 38. Putting It All Together (cont’d again)…
    39. 39. What You Initially Need From iCommons <ul><li>Initial Tool setup to tell iSites: </li></ul><ul><li>The name of the tool </li></ul><ul><li>The URL of the “view” </li></ul><ul><li>The URL of the “edit” (if any) </li></ul><ul><li>Who has permissions: </li></ul><ul><ul><li>Owner(s) </li></ul></ul><ul><ul><li>Viewer(s) </li></ul></ul><ul><ul><li>Participant(s) </li></ul></ul><ul><li>Decryption key for the userId </li></ul><ul><li>[All done through the iSites Admin Site] </li></ul>
    40. 40. iSites Help <ul><li>You must ask iCommons to set up help pages for you, which you then get to edit. </li></ul>
    41. 41. Something That Would Be Really Nice To Have <ul><li>A Testing Harness/Framework </li></ul><ul><li>Because so much else is happening on an iSites page*, it is difficult to trouble-shoot problems. </li></ul><ul><li>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. </li></ul><ul><li>* Which always renders with warnings in an HTML validation </li></ul>
    42. 42. Suggested Improvements To The Process* <ul><li>Documentation </li></ul><ul><li>How the Tool “permissioning” process works </li></ul><ul><li>Cool/Useful CSS styles already available </li></ul><ul><li>Cool/useful “widgets” (such as the text editor) already available </li></ul><ul><li>“ Head’s up” on changes in new versions </li></ul><ul><li>Community </li></ul><ul><li>It would be nice if iCommons could make us aware of each other. </li></ul><ul><li>In response to this in my talk, this document will appear after September 15 </li></ul>
    43. 43. Acknowledgments <ul><li>From iCommons: </li></ul><ul><li>David Heitmeyer, Colin Murtaugh, </li></ul><ul><li>Kim Edelman, and David McElroy </li></ul><ul><li>From ATG: </li></ul><ul><li>Annie Rota and Katie Vale </li></ul><ul><li>From Harvard Divinity School: </li></ul><ul><li>Gloria Korsman and Susan Worst </li></ul><ul><li>(my “guinea pigs” :-) </li></ul><ul><li>From OIS </li></ul><ul><li>Julie Wetherill and the wonderful OPS folks </li></ul><ul><li>h/t Janet H. Taylor </li></ul>
    44. 44. Questions? <ul><li>Bobbi Fox </li></ul><ul><li>Office for Information Systems </li></ul><ul><li>Harvard University Library </li></ul><ul><li>[email_address] </li></ul>