3 <a name='overview' />
\r
6 <a href='http://iwf.sourceforge.net'>Interactive Website Framework</a>, or IWF, is essentially a set of javascripts which encapsulate a large
\r
7 portion of the "grunt work" required when making highly interactive websites. A highly interactive
\r
8 website can be defined as a site which performs background http requests (Ajax), permits smooth
\r
9 transitioning of elements' visibility and location (Animation), and immediate form validation.
\r
11 <h3>Intuitive API</h3>
\r
13 IWF has been designed from the ground up to allow for a "typical" web developer to be able to
\r
14 harness its power without changing his or her methodologies drastically.
\r
17 All IWF-related javascript and HTML has '<code>iwf</code>' as the prefix -- <code>iwfRequest()</code>, <code>iwfGetById()</code>, <code>iwfOnRequestError()</code>, etc.
\r
18 The only exception to this are 'private' functions which should be used internally by IWF itself -- these have a '<code>_iwf</code>' prefix.
\r
19 This '<code>iwf</code>' prefixing minimizes name clashing and makes it very obvious when calling into IWF.
\r
22 The primary limitation IWF imposes is that all HTML it handles <b>must</b> be XHTML compliant.
\r
23 However, I do not believe this is a very stringent requirement with disciplined developers.
\r
26 IWF also includes and uses its own xml parser, <code>iwfXmlDoc</code> and <code>iwfXmlNode</code>.
\r
27 I wrote this xml parser to have more intuitive javascript when manipulating xml on the client.
\r
28 For example, let's say we have the following xml:
\r
31 <site url='www.sourceforge.net'>
\r
32 <description>Great place for open source projects!</description>
\r
34 <site url='iwf.sourceforge.net'>
\r
35 <description>IWF Project Home</description>
\r
39 To pull the description for the IWF site using the typical DOM:<br />
\r
40 <pre>var desc = doc.documentElement.lastChild().firstChild().innerText;</pre>
\r
41 To pull the same node using the custom IWF implementation:<br />
\r
42 <pre>var desc = doc.internet.site[1].description[0].getText();</pre>
\r
45 As you can see, the IWF implementation produces very readable and maintainable javascript,
\r
46 albeit a non-standard way of accessing xml data.
\r
49 <h3>Xml At Heart</h3>
\r
51 IWF only understands xml. In fact, IWF has a very specific xml format it requires to enable
\r
52 one to fully utilize its capabilities.
\r
55 A typical xml stream that IWF understands and can automatically process looks like the following:
\r
60 <action type='html' target='divResponse' errorCode='' errorMessage='' >
\r
61 <h1>This is text within an H1 element.
\r
62 All data within this action node will be populated into the innerHTML
\r
63 attribute of the element with the id matching the one specified by the
\r
64 target attribute above, which is 'divResponse'.</h1>
\r
72 <li>A <code>response</code> node wraps the entire thing, but does nothing else.</li>
\r
73 <li>There may be multiple <code>action</code> nodes.</li>
\r
74 <li>The <code>action</code> node causes the browser to do different things based on the <code>type</code> attribute.</li>
\r
75 <li>If the <code>errorCode</code> is specified and != 0, the javascript function iwfOnRequestError will be called if it exists, and processing of this <code>action</code> node is aborted.</li>
\r
76 <li>The values for the <code>type</code> attribute are:
\r
78 <li>html == contents of node are XHTML</li>
\r
79 <li>javascript == contents of node are javascript</li>
\r
80 <li>xml == contents of node are xml</li>
\r
83 <li>The <code>target</code> only applies when <code>type</code> is 'html'. This specifies the id of the element which will be populated with the contents of the node.</li>
\r
84 <li>When <code>type</code> is javascript, the contents of the node are parsed and executed as javascript. It will be made available to the browser so other javascript already in the document can call this javascript.</li>
\r
85 <li>When <code>type</code> is xml, an <code>iwfXmlNode</code> object is passed to the <code>callback</code> function defined when <code>iwfRequest</code> was called. If none exists, this action is ignored.</li>
\r
88 <h3>Thread Safe Requests</h3>
\r
90 IWF uses a javascript feature called an inner function to handle multiple requests simultaneously.
\r
91 An inner function is simply a function defined within another function. What makes it special is the
\r
92 inner function has visibility to the outer function's local variables. Those local variables do not
\r
93 fall out of scope until after all items in the outer function's activation context has completed. By
\r
94 setting the XmlHttpRequest object's <code>onreadystatechange</code> callback to our inner function,
\r
95 it causes the inner function to stay activated -- which means the outer function's local variables are
\r
96 still available until that inner function has executed. When the XmlHttpRequest has completed, the
\r
97 inner function uses the outer function's variables to determine what method to callback (if any),
\r
98 which target was specified (if any), etc.
\r
101 If that was a little too much at once, don't sweat it. Essentially, your users can click multiple links
\r
102 rapidly and all requests will be performed and processed, without the worry of "missing" or "dropping" any.
\r
104 <h3>As Flexibile As Needed</h3>
\r
106 As mentioned above, IWF uses xml for all of its responses. That xml is inspected, and IWF acts
\r
107 according to how the xml specifies. So if you want to have your server kicking back XHTML and injecting
\r
108 it into an element in the browser, you can. If you want the server kicking back javascript and executing
\r
109 it, you can. If you want the server kicking back straight xml, which the client will be responsible for
\r
110 parsing and acting upon, you can.
\r
114 <h3>Browser Independent</h3>
\r
116 IWF is heavily reliant upon client-side javascript. In fact, if the user does not have a
\r
117 javascript-capable browser, or javascript is disabled, IWF simply will not work.
\r
120 However, all javascript has been written / tested / verified on Firefox 1.0.3 and IE 6.0 running under Win XP.
\r
121 Most of what IWF does is fairly basic, so most other major browsers should work fine. If not, <a href='mailto:brockweaver@sourceforge.net'>drop me a line</a> and I'll see if I can get it working.
\r
123 <plug type='shameless'>
\r
124 If you want me to start supporting Safari, <a href='donate.php'>donate to my iMac fund</a>!
\r
128 <h3>Server Platform Independent</h3>
\r
130 Since IWF is primarily a client-side technology, any web server which can kick out ASCII will work perfectly -- and by definition, any web server
\r
131 can do this. All IWF requires from the server is a valid xml stream in IWF format.
\r
134 PHP is my favorite web scripting language, so I have implemented a very simple class for emitting
\r
135 IWF-copmliant xml from a PHP server. This could very easily be ported to ASP, but since the release
\r
136 of ASP.NET, my focus has shifted away from it.
\r
projects / webpac2 / blob