®

AD402@Formulas Meet AJAX

Jack Ratcliff

Rock-Tenn Company

Agenda

Quick History of @Formulas and Ajax

How to “do” Ajax

Current Domino+Ajax usage

Examples of different ways @formulas can be used in Ajax applications

The all powerful “Form Formula”

How @Formulas can be called ‘natively’ with Ajax from within a Browser

Q & A

Quick History of @Formulas

The Lotus Formula Language (@functions and @commands) The first release (1989)The only programming language until Release 4 (Jan. 1996)Rewritten from scratch by Damien Katz for Notes and Domino 6 (Oct. 2002)

Performance dramatically improvedMany of the 64K limits removedLooping constructs added

Some commonly used @functions are@DbLookup, @DbColumn@UserName, @UserNamesList, @UserAccess, @UserRoles@GetDocField, @SetDocField@Today, @Now, @Yesterday, @Adjust@For, @While, @DoWhile, @Transform

Quick History of @FormulasSome recently added @formulas

Release 5.x@AddToFolder, @Command([Folder])@BrowserInfo@ValidateInternetAddress

Release 6.x@WebDbName, @ReplicaID@CheckFormulaSyntax, @Eval@AttachmentModifiedTimes@GetAddressBooks, @GetField, @GetHttpHeader, @UrlQueryString@DocLock**@For, @While, @DoWhile@ServerName, @ServerAccess@Sort, @SetViewInfo*, @Transform@DbCommand(“Domino”;…) > FolderList

Release 7.x@IsDB2, @DB2Schema@PolicyIsFieldLocked, @IsEmbeddedInsideWCT*

* does not work on the web

** works only in a WebQueryOpen agent

Quick History of AjaxFrom Wikipedia – “Ajax, shorthand for Asynchronous JavaScript and XML, is a web development technique for creating interactive web applications. The intent is to make web pages feel more responsive by exchanging small amounts of data with the server behind the scenes, so that the entire web page does not have to be reloaded each time the user requests a change. This is meant to increase the web page's interactivity, speed, and usability.”

Jessie James Garrett coined the term in February 2005. “He came up with the pseudo-acronym in the shower while searching for a shorthand way to explain to clients why the recent offerings by Google can perform so robustly.” (Wall Street Journal Online, 3 Nov 2005)

The Ajax technique uses a combination of JavaScript, DOM, XMLHttpRequest object, and XML (JSON, text, etc.).

Microsoft originally developed the XMLHttpRequest concept, and it has been available in IE 5.0 since 1999.

Mozilla added a native implementation in Mozilla 1.0 in 2002.

Other browsers soon followed (Safari, Opera, Konqueror, iCab).

How To Make an Ajax Call

Simplified Method

First, you have to have a XMLHttpRequest object*.IE way

oXHR = new ActiveXObject("Microsoft.XMLHTTP");

Standards way (and IE 7)

oXHR = new XMLHttpRequest();

Simplified cross-browser wayif (window.XMLHttpRequest) { // Mozilla, Safari, …

oXHR = new XMLHttpRequest(); } else if (window.ActiveXObject) { // IE

oXHR = new ActiveXObject("Microsoft.XMLHTTP"); }

Next, you have to decide what to do after you receive the server response.oXHR.onreadystatechange = nameOfTheFunction

* Steps taken from the “Ajax:Getting Started” tutorial on the http://developer.mozilla.org site

How To Make an Ajax CallNow you need to make your request.

GEToXHR.open(‘GET’, ‘http://yourserver/db/view/unid?OpenDocument’, true);oXHR.send(null);

POSToXHR.setRequestHeader(‘Content-Type’, ‘application/x-www-form-urlencoded’);oXHR.open(‘POST’, ‘http://yourserver/db/view/unid?SaveDocument’, true);oXHR.send(name=value&anothername=othervalue&so=on);

Finally, you need to handle the server response.function nameOfFunction() {

if (oXHR.readyState == 4) { if (oXHR.status == 200) {

alert(oXHR.responseText); } else {

alert('There was a problem with the request.'); }

} }

Is there an easier way?

That is a lot to remember, and it does not cover everything!

What if…The request is taking longer than we want? (oXHR.readyState != 4)The request fails? (oXHR.status != 200)What if Microsoft does something different?What if a new browser hits the market?What if one of the many browsers introduce a XMLHttpRequest bug?What if we need more features? (updater, periodic updater, etc.)

Use a JavaScript Toolkit That Includes Ajax Support

There are many JavaScript toolkits that include Ajax support.

Douglas Crockford in a lecture given in October of this year said that there are an estimated 200 Ajax libraries out there!

The ones I like and useSarissa

An ECMAScript library acting as a cross-browser wrapper for native XML APIs Gives a common api to do client-side xml/xslt processing

PrototypeJavaScript framework for class-driven development

Why Use a JavaScript Toolkit

“When the browser war started over 10 years ago, there were two browsers. IE won the war and left us with really only one browser to worry about.”

Today, as Douglas Crockford put it, “we are living in WWW War II, and in this war there are now four major browser makers, and each will be flooding the web with bugs!”

So…let the toolkit makers worry about how to make Ajax work in each browser and you worry about writing code to solve your user’s business problems!

My Observations of Ajax and Domino/db/view?ReadViewEntries

JavaScript “simulated” @DbLookup and @DbColumnMy own “dhtml web views”

Scrollable viewsMulti-expanding categories

/db/view?ReadDesignFor retrieving the design information of a view and its columns

/db/outline?ReadEntriesWeb-based “tree controls” that are similar to outlines embedded in forms/pages in a Notesapplication

/db/agent?OpenAgentUsually used for more complex logic to send data back to the browser; however, I believe this technique is over used.

LotusScript– Print “Content-Type: text/xml” (application/xml, text/plain, etc.)– Print “your data”

Java – java.io.PrintWriter pw = this.getAgentOutput();

pw.println("Content-type: text/xml"); – pw.println(“your data”);

My Observations of Ajax and Domino

/db/page?OpenPageReturning just about anything from JavaScript to text to xmlUsually hardcoded text with computed text using @formulas

/db/view/unid?OpenDocumentUsually hardcoded xml tags surrounding fields with @formula computed fields and/or computed text

/db/view?OpenViewDedicated views returning JavaScript or xml@Formulas usually in column formulas

Additional @Formula Usage on the Web

We use @formulas everywhereView selection/column formulasComputed and computed for display fieldsComputed text

Putting them all together we have done things such as:Store information into JavaScript variables

var username = ‘<Computed Value>’; var username = ‘Jack Ratcliff/RockTenn’;

Create XML pages/forms with @formulas to compute various pieces of data<username><Computed Value></username><username>Jack Ratcliff/RockTenn</username>

Create XML views when ?ReadViewsEntries do not give us the format we want“<status>” + status + “</status>”<status>Open</status>

Create JavaScript array views that use view data to populate JavaScript arrays“arProductDescription[i]=\”” + productDescription + “\; i++;”arProductDescription[i] = “some description”; i++;

JavaScript @Formula “Simulations” for the Web

Many developers want to call @formulas directly in their JavaScript code.

Many have started JavaScript libraries to “simulate” @formulas.Workplace DesignerOpenNTFNotes.netStan Rogers’ JS Formula Library

The most popular have been for @DbLookup and @DbColumn.Using Ajax to process the XML returned from ?ReadViewEntriesUsing Ajax to process the XML/text return from ?OpenAgent

Pros and Cons of JavaScript @Formula “Simulations”

ProsSimple @formulas will execute quicker.Return values will already been in the correct format.

ConsA lot of work is involved in writing JavaScript functions to simulate @formulas.@DbLookup and @DbColumn solutions that use ?ReadViewEntries consume more bandwidth than necessary.@DbLookup and @DbColumn solutions that use an agent consume more server resources, are slower, and are not as scalable.

Ways @Formulas can be Used with Ajax

@formulas on a page

@formulas on a form

@formulas in a view

@formulas in a WebQueryOpen event

@formulas in a WebQuerySave event

@formulas dynamically created from within a browser and sent to a Domino server to process

@Formulas on a Page

Page can be used to produce just about anything.JavaScriptXMLJSONText

Make sure to set the appropriate “Content type”.

@Formulas on a Page - Example

Problem to SolveNeed to know the “NotesSession” information about the current user

The SolutionPage = dwt.NotesSession

Use a dedicated page with our xml and @formulas that compute the various pieces of information that could be found within the NotesSession classSet the page’s content type to application/xml

Ajax call to:../db/dwt.NotesSession?OpenPage

@Formulas on a Form

Similar to a page in that we can have the form return just aboutanything.

Set the appropriate “Content type”.?ReadForm and ?OpenDocument will use the Content type you set.?OpenForm only works with a Content type of Notes or text/html.?SaveDocument or ?CreateDocument ignores the content type you set is text/html is returned.

If you use a WebQuerySave agent, you can change the Content type.However, you cannot set the content type using @SetHttpHeader(“Content-Type”;”application/xml”).

With the use of a folder or view AND a Form Formula, we can haveour @formulas execute within the context of the current document.

This technique gives you the ability toDetermine if a user has the ability to edit a document or notSimulate a ../db/view/unid?ReadDocument to get the xml representation of a document (almost)Do doc locking using @DocLock when coupled with @formulas in the WebQueryOpen event

@Formulas on a Form – Example 1

Problem to SolveNeed to know if the current user has edit access to a document

The SolutionForm = dwt.DocumentAccess

Use a dedicated form that has our xml and our @formulas that compute whether a user has edit access to a document or notSet form’s content type to application/xmlInclude a SaveOptions field that computes to “0” so the document never gets saved with this form.

Folder = ($dwt.DocumentAccess)A dedicated folder is used with a Form Formula set to this form.When we open our document from this folder, it is opened with our custom form.Thus, it executes all @formulas within the document’s context.

Ajax call to:../db/($dwt.DocumentAccess)/unid?OpenDocument

@Formulas on a Form – Example 2

Problem to SolveWould like the xml representation of a document (the dxl)

The SolutionForm = dwt.ReadDocument

Use a dedicated form that has our xml and our @formulas that compute whether a user has edit access to a document or notSet form’s content type to application/xmlUsing @DocFields, @For, @GetField, we can build an xml representation of a NotesDocument.

Folder = ($dwt.ReadDocument)A dedicated folder is used with a Form Formula set to this form.When we open our document from this folder, it is opened with our custom form.Thus, it executes all @formulas within the document’s context.

Ajax call to:../db/($dwt.ReadDocument)/unid?OpenDocument

@Formulas on a Form – Example 2

Missing Information<noteinfo>

Sequence attribute – not sure how to determine this via an @function<modified> - using @Modified but it returns a value representing the next-to-last time the document was saved<revised> - There is not an @Revised function. Maybe can use $Revisions field<addedtofile> - There is not an @AddedTofile function. Not sure what could be used here

<item>Richtext fields do not include the info that dxlimporter includes (i.e. font, color, para, etc.).Formula fields return nothing.Authors, Readers, and Names fields – cannot determine with @function these data types

Note – If you do need some of this missing information like richtext info, you will need to use the DxlExporter or NotesDxlExporter classes in an Agent to get this information.

@Formulas in WebQueryOpen - Example

Problem to SolveNeed to provide web based document locking using the native document locking features of Notes/Domino

The SolutionForm = dwt.DocLock

Use a dedicated form that accepts ‘option’ as a query string parameter and pass this ‘option’ to @DocLock([option]).Set form’s content type to application/xml

WebQueryOpen eventSince @DocLock will not work in a field or computed text, place all of the code in the WebQueryOpen event.Since we are not calling an agent in the WebQueryOpen event via the @Command([ToolsRunMacro];agent), we should not suffer the overhead of a ‘normal’LotusScript or Java agent.

Folder = ($dwt.DocLock)A dedicated folder is used with a Form Formula set to this form.When we open our document from this folder, it is opened with our custom form.Thus, it executes all @formulas within the document’s context.

Ajax call to:../db/($dwt.DocLock)/unid?OpenDocument

“Native” @Formulas with Ajax

Not a JavaScript rewrite of @formulas

Use Ajax to “wrap” the native @formula and post to the server

Run the native @formula on the server and return the resultUse $$Return field to execute formula and return result@CheckFormulaSyntax@Eval

Does not support UI @Commands

Not all @functions are supported, but surprisingly, many are!

“Native” @Formulas with Ajax

DatabaseEvery user that needs to execute @formulas will need to be able to “Write Public Documents”.

This includes those with only Reader Access.The reason for this is that the @formulas are posted to a dedicated form.We could change this so that the @formulas are read from the querystring and executed that way. However, there are various limitations with how long the url can be in some browsers so very long and complex formulas could be truncated.

Form – dwt.FormulaFields

formula – where your formula will be posted to$PublicAccess – Computed when Composed, “1” – need this for when users only have Reader accessSaveOptions – always set to “0” since we don’t care to save the document. However, maybe it can be set to 1 if we want a way to “cache” the result.$$Return -- @Eval(formula) is done here and returned to the browser.Set Content type = text/plain since the @Eval of a formula will return a text string

“Native” @Formulas with Ajax

Folder – ($dwt.Formula) Use a Folder so the server does not incur any overhead to maintain a view.Set the Form Formula to “dwt.Formula” so our custom form will be used instead of the form that the document was created with.

Ajax code to “post” @formula?CreateDocument – used if the formula does not need to execute within the context to a document

@DbColumn, @DbLookup, @Replace, @Sort, etc.?SaveDocument – used if the formula DOES need to execute within the context of a document

@GetField, @SetField, @AddToFolder, any formula that access field by their field nameUse encodeURIComponent to encode formula text

A “Gotcha”When posting to a Domino Form, you can NOT change the Content-type with @SetHttpHeader. You can change within a LotusScript or Java agent, but since we want to avoid agents we’re stuck with this.The result is the Content-type stays text/html and Domino sends back and html document with the results of our Eval in the <body> tag.Using prototype’s string.stripTags() method we can strip all of the tags and just get to our results. However, if your @formula builds tags then they will be stripped as well.

“Native” @Formulas with Ajax - Example

Create your @formulas on the fly with JavaScript and post the formula to the server to execute.

Examples@AddToFolder@Left, @Right, @Sum, @Replace, @Transform@For, @While, @DoWhile@GetField, @GetDocField@Set Field, @SetDocFieldEditable Views with @SetDocFieldSelect fields with @DbColumn and @DbLookup

So Why Ajax to Execute @Formulas

Ajax providesGood user experienceRicher, desktop like application

Ajax with @formulas providesDevelopers to plug-in code without major modifications to current forms/views. (e.g.. Need doc locking? then drop the form/view into the database and everywhere you need to use doclocking call the JavaScript doclocking code. No need to include a subform on each form that needs this or to include <computed text> to setup some helper JavaScript vars, etc.)Good balance between what is done on the server and in the browser. Originally code used to be all done on the server but that required bigger, faster servers and did not take advantage of the memory and processing power of the PC. Then, everyone started doing more in the browser with JavaScript. A good balance is to use Ajax to call server side code to execute and then send to the browser to do further processing.

Summary

When using dedicated forms and views/folders with a Form Formula, we can:

Do document locking on the web with @formulas even though the documentation says it cannot be done.Check document level access.Simulate document?ReadDocument to get the xml representation of data in a document.Write @formulas dynamically in the browser which can be wrapped in Ajax calls and sent to the server for evaluation.

Improvements/Enhancements

Add ability to cache @formula results

Support UI @commands

Create our own JavaScript library for the Notes classesNot all but just the ones that would be useful in web development

dwt.NotesSession– Already started

dwt.NotesView– Should not be too difficult considering all of the information ?ReadDesign

gives usdwt.NotesDocument

Improvements that IBM can help with

Already have ?OpenDocument?EditDocument?SaveDocument?CreateDocument?DeleteDocument

Why not have?EvaluateFormula?ReadDocument?LockDocument&option=Ability to change Content-type with @SetHttpHeader

Other Sessions

AD401 - Leveraging AJAX Frameworks to Build IBM Lotus Domino Web Applications

BP311 - The Great Code Giveaway - Web 2.0 Edition

Thank You

Please remember to fill out your evaluation.

Contact Info:jratcliff@rocktenn.comhttp://jackratcliff.com

© IBM Corporation 2007. All Rights Reserved.

The workshops, sessions and materials have been prepared by IBM or the session speakers and reflect their own views. They are provided for informational purposes only, and are neither intended to, nor shall have the effect of being, legal or other guidance or advice to any participant. While efforts were made to verify the completeness and accuracy of the information contained in this presentation, it is provided AS IS without warranty of any kind, express or implied. IBM shall not be responsible for any damages arising out of the use of, or otherwise related to, this presentation or any other materials. Nothing contained in this presentation is intended to, nor shall have the effect of, creating any warranties or representations from IBM or its suppliers or licensors, or altering the terms and conditions of the applicable license agreement governing the use of IBM software.

References in this presentation to IBM products, programs, or services do not imply that they will be available in all countries in which IBM operates. Product release dates and/or capabilities referenced in this presentation may change at any time at IBM’s sole discretion based on market opportunities or other factors, and are not intended to be a commitment to future product or feature availability in any way. Nothing contained in these materials is intended to, nor shall have the effect of, stating or implying that any activities undertaken by you will result in any specific sales, revenue growth or other results.

Performance is based on measurements and projections using standard IBM benchmarks in a controlled environment. The actual throughput or performance that any user will experience will vary depending upon many factors, including considerations such as the amount of multiprogramming in the user's job stream, the I/O configuration, the storage configuration, and the workload processed. Therefore, no assurance can be given that an individual user will achieve results similar to those stated here.

All customer examples described are presented as illustrations of how those customers have used IBM products and the results they may have achieved. Actual environmental costs and performance characteristics may vary by customer.

IBM, the IBM logo, Lotus, Lotus Notes, Notes, Domino, Domino.Doc, Domino Designer, Lotus Enterprise Integrator, Lotus Workflow, Lotusphere, QuickPlace, Sametime, WebSphere, Workplace, Workplace Forms, Workplace Managed Client, Workplace Web Content Management, AIX, AS/400, DB2, DB2 Universal Database, developerWorks, eServer, EasySync, i5/OS, IBM Virtual Innovation Center, iSeries, OS/400, Passport Advantage, PartnerWorld, Rational, Redbooks, Software as Services, System z, Tivoli, xSeries, z/OS and zSeries are trademarks of International Business Machines Corporation in the United States, other countries, or both.

Java and all Java-based trademarks are trademarks of Sun Microsystems, Inc. in the United States, other countries, or both.

Microsoft and Windows are trademarks of Microsoft Corporation in the United States, other countries, or both.

Intel and Pentium are trademarks or registered trademarks of Intel Corporation or its subsidiaries in the United States and other countries.

UNIX is a registered trademark of The Open Group in the United States and other countries.

Linux is a registered trademark of Linus Torbvalds in the United States, other countries, or both.

Other company, product, or service names may be trademarks or service marks of others.

All references to Acme, Renovations and Zeta Bank refer to a fictitious company and are used for illustration purposes only.