Skip to Content

Wiki source code of ERPrototaculous

Version 111.1 by Ravi Mendis on 2010/05/02 22:31
Hide last authors
Ravi Mendis 100.1 1 == Introduction ==
2
3 ERPrototaculous was developed to provide the ajax functionality in ERDivaLook.
4
5 === What is ERPrototaculous? ===
6
7 Features include:
8
Ravi Mendis 105.1 9 * 'Organic' support for [[Prototype>>http://www.prototypejs.org/]] and [[Scriptaculous>>http://script.aculo.us/]] in WebObjects.
Ravi Mendis 100.1 10 ** Light-weight dynamic elements to support Prototype
Ravi Mendis 102.1 11 ** Transparent API that doesn't hide or abstract Prototype and Scriptaculous
Ravi Mendis 100.1 12 ** Sans patches or extensions to Prototype
13 * Use of [[Unobtrusive Javascript>>http://en.wikipedia.org/wiki/Unobtrusive_JavaScript]].
14 * Pseudo-stateless ajax responses
15 * A set of widgets in the Prototype + Scriptaculous family.
16
17 ==== Unobtrusive Javascript in ERPrototaculous ====
18
19 Unobtrusive javascript is used in contrast to on-demand style of ajax programming.
20 By including Javascript as well as CSS globally in the page wrapper, CSS and Javascript don't have to load inside each and every ajax requests.
21 This keeps the ajax responses compact and simple.
22
23 The result is **faster** and more **reliable** ajax in WebObjects.
24
25 ==== Prototype WebObjects Elements ====
26
27 ##Ajax.Updater## and ##Ajax.Request## have been implemented as WebObjects elements.
28
29 ===== Ajax.Updater =====
30
31 Support for Prototype's [[Ajax.Updater>>http://www.prototypejs.org/api/ajax/updater]] is in the form of three elements:
32
33 * AjaxUpdaterLink
34 * AjaxUpdaterButton
35 * AjaxUpdaterForm (with ##onsubmit## for ajax form submission)
36
37 These components will update //any// **container** on the page:
38
39 {{code value="javascript"}}
40
41 new Ajax.Updater('container', url, {options});
42
43 {{/code}}
44
45 ===== Ajax.Request =====
46
47 Prototype's [[Ajax.Request>>http://www.prototypejs.org/api/ajax/request]] is in the form of:
48
49 * AjaxRequestLink
50 * AjaxRequestButton
51
52 These are used for strictly **background** ajax communication:
53
54 {{code value="javascript"}}
55
56 new Ajax.Request(url, {options});
57
58 {{/code}}
59
60 ==== Prototype + Scriptaculous Widgets ====
61
62 * Accordion
63 * LightWindow
64 * ModalBox
65 * CalendarDateSelect
Ravi Mendis 110.1 66 * [[FileUpload>>http://valums.com/ajax-upload/]]
Ravi Mendis 100.1 67
68 Support for these widgets have been similarly implemented as **button** and **link** variants, depending whether it is used inside a form or not.
69
70 == Ajax Forms in ERPrototaculous ==
71
72 Differences from using forms in WebObjects. i.e ##WOForm##:
73
74 1. All ajax form controls must be named. This includes text fields, selects and buttons.
75 (WebObjects dynamically assigned names are not compatible with ERPrototaculous).
76 1. All ajax forms in an ERPrototaculous app need to be instances of ##AjaxUpdaterForm##.
77 1. Ajax form submit buttons can be a:
78 1*. Static ##<button>##.
79 1*. WOSubmitButton (if the result is to update whole page/app).
80 1*. AjaxUpdaterButton (to update a **container**). Or
81 1*. AjaxRequestButton (for a **background** ajax request).
82
83 So forms are different in Ajax.framework and ERPrototaculous.
84
85 In ERPrototaculous you may still have typical WebObjects forms (i.e WOForm) as well as use ajax forms (i.e **AjaxUpdaterForm**).
86 They behave differently in that an AjaxUpdaterForm will update the contents of a container as opposed to the entire page.
87
88 {{warning title="Warning"}}
89
90 You must *name your form controls*, otherwise under certain circumstances Prototype (ajax) form submission will break.
91
92 {{/warning}}
93
Ravi Mendis 111.1 94 = Embrace Statelessness! =
Ravi Mendis 100.1 95
Ravi Mendis 111.1 96 {{include value="WO:Embrace Statelessness"}}{{/include}}
97
98 ERPrototaculous embraces the stateless model Ajax offers in exchange for simplifying the work WebObjects has to do -- it's a win--win!
99
100 So you may observe one notable difference between the ERPrototaculous and Ajax frameworks is in the way they handle ajax responses.
Ravi Mendis 100.1 101 In ERPrototaculous, updates and actions break with //The WebObjects Way// by being pseudo-stateless.
102
Ravi Mendis 111.1 103 === Ajax Response Handling in ERPrototaculous ===
104
Ravi Mendis 100.1 105 In a typical WebObjects application, when a user navigates to the previous page using the browser back button and subsequently clicks on a link in on that page, WebObjects needs to remember how to handle that action and to return the correct page. This is no longer necessary for ajax.
106
107 A user never travels backwards or forwards through the ajax application history.
108 (i.e there is no forward/back buttons for ajax requests - just as there aren't forward/back buttons on desktop apps).
109
110 So for ajax, the current state of the page fragment component is all that is necessary.
111
112 {{info title="No More"}}
113
114 A 100% ajax WO-app (like an [ERDivaLook|ERDivaLook] app) is no longer plagued by the well known _limitation_ of WebObjects - the browser *backtrack problem*.
115
116 {{/info}}
117
118 == Ajax Actions in ERPrototaculous ==
119
120 Typically, in a WebObjects application, an action would return the contents of the entire page.
121
122 Ajax responses are mostly page fragments or just part of a page.
123 So you should make sure the actions in ERPrototaculous (or AjaxUpdaterButton and AjaxRequestButton) return the proper page fragment as opposed to the entire page.
Ravi Mendis 102.1 124 This is different to how WebObjects normally works, so this is where you need to be careful.
Ravi Mendis 100.1 125
126 {{note title="Note"}}
127
128 ERPrototaculous actions *differ* from Ajax.framework actions - _They must return only the page fragment_.
129
130 {{/note}}
131
132 To assist with page fragments inside **forms**, you can make your ajax action responses a subclass of **WXPageFragment** (a utility to handle the forms processing between Prototype and WebObjects).
133
134 == Update Containers in ERPrototaculous ==
135
136 Perhaps the only real similarity to Ajax.framework is the ajax update container.
137 **WXGenericContainer** is the ERPrototaculous update container.
138 It is similar to an AjaxUpdateContainer when it has the binding ##ajax = true##, otherwise it's pretty much like **WOGenericContainer**.
139
140 It has been implemented as a utility or //convenience// for Prototype's ##Ajax.Updater##.
141 That is it can be used to update from a DOM //event// like popup //onchange//, or from a Prototype //callback// like //onComplete//, etc.
142
143 == Compatibility ==
144
145 ERPrototaculous can not be used with WebObjects 5.3 as it is dependent on the hooks for ajax added to WebObjects with version 5.4.
146
147 {{warning title="ERPrototaculous is WebObjects *5.4* compatible only"}}
148
149
150 {{/warning}}