Skip to Content

Wiki source code of ERPrototaculous

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