Mini AHAH Or A Taste Of AJAX
| As suggested by RafaelAlvarez in the discussion, I've copied the showcase from the munich.pm website now that twiki.org is running TWiki4. |
The capability of TWiki4 regarding dynamic retrieval of contents can
be shown with a couple of simple examples:
- Some simple ways to preview TML without going through an edit cycle
- A topic selector form, similar to the "jump box" in PatternSkin, but allowing to select from existing webs/topics in dropdown menues
- A topic explorer, very similar to the explorer known from MS Windows
- Another explorer, this time allowing to selectively collect entries from TWikiVariables
- A form and a table to display - and even change TWiki session variables without saving a topic
Feel free to create your own!
Full Table of Contents
A Word of Warning
This is a prototype, stuff hacked together in some evenings, just as a motivation why
XmlHTTPRequest is an interesting thing. There's still discussion in
TWikiAjaxFramework about the interface, about which javascript library to use, etc, and these discussion should remain in that topic.
Here is a showroom where you are kindly asked not to touch things and not to look too closely at the implementation. We might make some of the features shown here usable from other parts of twiki.org as well.
At some point in time the showcases here will be moved towards the API which will eventually drop out of the discussions in
TWikiAjaxFramework. Or maybe not, because it might be pretty irrelevant how
this particular topic is implemented as long as
you know what you can do with AHAH or
AJAX.
At some earlier point it may be advisable to split this topic in the showroom, the technical section, and the templates, or even split the templates (performance issue). But not right now - I ask for your patience.
Finally, the functions have been tested with IE 6.0 and Firefox 1.5 only, out of sheer lazyness on my side. They may wreak havoc on visitors using Opera, or Konqueror, though I'd expect them to fail rather harmlessly. Again, the fine print will be done in the framework of
TWikiAjaxFramework.
Showroom
Preview arbitrary TML Without Leaving The Page
This can be used to test some TWiki Markup Language (
TML), or to
simply inspect a TWiki variable without having to go through a
complete view/edit/save/view cycle. Available in three flavours: an
one-line input field, a text area, and a
real sandbox.
All these share some shortcoming: The TWiki Variables describing the
current web and topic (e.g.
TOPIC) are showing a
"wrong" value (so searches etc. are having the wrong defaults), and a
"Save" function is not implemented (though the latter would be
possible).
One Line Input Field
Enter Text,
TML, or
TWikiVariables. Try, for example,
[[MendedDrum]] or
%SEARCH{"Topic Explorer"}%.
To use in your own topic, say:
%INCLUDE{"Codev.MiniAhah" section="tmlinput"}%
Multiline Text Area
Use this one for trying bullet lists, table layouts, ...
To use in your own topic, say:
%INCLUDE{"Codev.MiniAhah" section="tmltextarea"}%
A Sandbox Within A Topic
With a sandbox like this, guests can try editing and formatting
without having to think about topic names. No trace will be left on
the server side.
To use in your own topic, say:
%INCLUDE{"Codev.MiniAhah" section="tmlsandbox"}%
A Dynamic Topic Selector Form
This is similar to the "Jump" box in
pattern skin,
but allows selecting from existing webs and topics instead of having to guess.
Clicking on the
will convert the
text boxes to dropdown menues, which will be filled with values only on request,
but cached for quick access.
Be careful when using this to select topics from a web with many
topics, this may take quite a while.
To use in your own topic, say:
%INCLUDE{"Codev.MiniAhah" section="topicselector"}%
A Dynamic Topic Explorer
This is similar to the Windows Explorer. Clicking on the
will
expand the webs, or topics, respectively.
Be careful when using this for webs with many
topics, this may take quite a while.
|
 (TWiki) |
To use in your own topic, say:
%INCLUDE{"Codev.MiniAhah" section="topicexplorer"}%
Is
TWikiVariables too fat for you? Mind you, it has
~150kB, includes lots of stuff and - per design - expands almost every
conceivable variable. Then read only the parts you really need.
A drawback is that the links to "Related" variables are broken. As
broken as if you access individual variable topics like
VarACTIVATEDPLUGINS, and for a similar reason.
|
(All TWiki Variables) |
To use in your own topic, say:
%INCLUDE{"Codev.MiniAhah" section="twikivarexplorer"}%
Conveniently Getting/Setting Session Variables
Usually, to set a session variable you need to edit and save a topic. This is inconvenient, as I'd dare to say, since topics live longer than sessions (most of the time) and unless you remember to update the topic at the end of the session, everyone reading this topic will get the session variable thrust upon him.
Set Using Key-Value Boxes
Enter the name of a session variable (for example
_SESSION_REMOTE_ADDR) to read its value, set if you want.
To use in your own topic, say:
%INCLUDE{"Codev.MiniAhah" section="sessionvariable"}%
A Table of Frequently Used Session Variables
Set your Session variables:
To use in your own topic, say:
%INCLUDE{"Codev.MiniAhah" section="sessionvariabletable"}%
Preparation for Usage in Your Topics
- Create the three topics MiniAhah, MiniAhahSelector and MiniAhahParam, either by copying the contents from this web or by expanding the zip files which I have still been to lazy to attach in the beginning and probably won't do at all because of the issues raised in the discussion.
- Include the following either in one of your templates, or only in the text those pages where you want to use the examples (you'll see it in raw or edit mode at the top of this topic):
<script type="text/javascript"><!--
var ahah_web = '%WEB%';
var ahah_topic_type = 'input';
// -->
</script>
<script type="text/javascript" src="http://www.twiki.org/p/pub/Codev/MiniAhah/ahah.js"></script>
See the demonstrations above for how to use the particular functions.
You don't have to stick with the functions given here. Take them just
as a examples, extend as you like.
Technical Section
- Purpose of this topic
- Short of a AJAX Framework, let's have a look what can be done with today's (TWiki4) functions, by leveraging a technique called "AHAH". AHAH (Asynchronous HTML and HTTP), also known as JAH (Javascript Asynchronous HTML) is sort of a lightweight AJAX (Asynchronous HTML And XML).
- AHAH References
- AHAH at Wikipedia
AHAH at Microformats
Comparison to Other TWiki Extensions
Today methods to expand or collapse parts of a
HTML page with
Javascript are quite frequently found in the internet. For TWiki,
there are several extensions which help authors doing this. So, why
yet another technique? Let's compare with some of those:
In contrast to
TWiki:Plugins.TwistyContrib,
TWiki:Plugins.RenderListPlugin,
TWiki:Plugins.TooltipPlugin and the
like, with AHAH the "expandable" data are not fetched in advance.
They're only fetched from the server when unfolding is requested,
using the AJAXoid
XMLHttpRequest(). If you are doing many unfolds,
the "traditional"
CSS folding techniques are faster because only one
request to the server is required - however, even then the perceived
speed may be better with AHAH, where the first screen is readily
available.
Comparing to
JSPopupPlugin, this extension is not a
plugin.
It does not define a new TWiki tag to the author. Instead, it is
targeted at TWiki power users who want to define blocks (see below)
for ready-to-use dynamic content.
Overview
To dynamically read things like a
%TOPICLIST% into a TWiki
topic, we need a possibility to 1) retrieve that information from the
server, and 2) display the list in the browser.
The first part is possible using Javascript: Modern browsers support a
function
XMLHttpRequest, which allows to pull (
XML) contents via
HTTP from a web server into a Javascript variable. As so often,
Microsoft's implementation is different from the rest of the world, but
there are plenty of explanations and examples in the internet how to
cope with that.
For the second part, we will use the
DOM property
innerHTML, which
describes the complete contents of a
HTML element. We are not going
to bother with parsing the results from
XMLHttpRequest (that is, by
the way, the difference between
AJAX and AHAH). We simply
replace
the contents of an element which has been present in a topic by the
contents from the server. Fortunately TWiki usually throws out valid
XHTML, which is valid
XML as well.
The Gory Details
Formulating the XMLHttpRequest
The central driver routine
XMLHttpRequest isn't called directly from event handlers or
HTML code.
There's always wrappers in between.
In a TWiki topic, there are two main possibilities to define these wrappers:
- As an
action attribute of a form element: <form action='javascript:my_wrapper(...)'>
- As an event handler, typically for
onsubmit, onchange, onclick events: <img src='...' onclick='my_wrapper(...)'>
Both are used in the examples above.
The most important part of the
XMLHttpRequest call is the target URL of the request.
We are using one of two specially crafted TWiki topics as target URLs as "AHAH drivers",
both having just one line: %TOPIC%Selector and %TOPIC%Param.
Do not, repeat:
Do not edit these topics unless you know very exactly what you're doing.
If viewed directly in a browser, the first one of them seems to be an exact copy of this topic,
whereas the second looks pretty empty. I'll describe them in more detail later.
Both the AHAH driver topics expect parameters: The
section describes a section (sic)
of a TWiki topic describing the
HTML to be returned as a result from the request, and
(arbitrarily) three parameters called
miniahah1,
miniahah2, and
miniahah3.
Only the first two are being used in the showroom today.
Formatting the Result
In the case of %TOPIC%Selector, the result of the
XMLHttpRequest is
formatted as a section in a TWiki topic - hereby able to use all TWiki
formatting features. The section is pulled in with
%INCLUDE% ,
which allows to pass parameters as of TWiki4. And that's the trick: The
main function of %TOPIC%Selector is to convert the URL parameters it
receives from the
XMLHttpRequest call to TWiki variables. The whole
topic reads (linefeeds added for easier reading):
%INCLUDE{"MiniAHAH" section="%URLPARAM{section}%"
MINIAHAH1="%URLPARAM{miniahah1}%"
MINIAHAH2="%URLPARAM{miniahah2}%"
MINIAHAH3="%URLPARAM{miniahah3}%" }%
Easy, isn't it?
%TOPIC%Param is even simpler:
%URLPARAM{miniahah1}%%URLPARAM{miniahah2}%%URLPARAM{miniahah3}%
...so all it does is to let TWiki process whatever is passed as parameters. That's
how the
TML previewers work - and that's all the magic needed.
To Do
- Make the documentation comprehensive, especially regarding the templates, and comprehensible (feedback welcome
). Documenting the javascript library isn't top priority since this part will tentatively vanish in favour of TWikiAjaxFramework.
- Split the various use case templates, mainly but not only for performance reasons. Today rendering MiniAhah for just one of the tiny templates always expands quite a lot of stuff, including
%WEBLIST% variables and searches.
- This requires adding a
templatetopic parameter to the javascript routines in addition to the section they are responding to today.
- Converge the javascript library, at least the javascript API, with TWikiAjaxFramework.
- Add more documentation / programmers guides about shuffling variables from (server side) TWiki to (client side) javascript and back again, and on quoting and escaping quotes in format strings. This is documented elsewhere, but is needed readily at hand when hacking own templates.
Mini AHAH Templates
The following templates implement what you can see in the demonstrations above.
They will look strange (at least) when viewed they bear no useful function, and only minimal effort has been taken to
maintain thie section as valid (X)HTML.
Templates for the TML Previewer
TML Single Line Template
TML Textarea Template
Sandbox Template
Templates for the Topic Selector Form
Template topicselector
This is the template for the dynamic topic selector above.
Templates for the Topic Explorer
|
(TWiki) |
|
(TWiki) |
 |
(TWiki)
|
|
 |
[[.WebHome][]] |
