[Jifty-commit] r7407 - jifty/trunk/lib/Jifty/Manual

[Jifty commits]

Author: sartak
Date: Tue Aug 18 17:54:17 2009
New Revision: 7407

Modified:
   jifty/trunk/lib/Jifty/Manual/Preload.pod

Log:
Description, usage

Modified: jifty/trunk/lib/Jifty/Manual/Preload.pod
==============================================================================
--- jifty/trunk/lib/Jifty/Manual/Preload.pod	(original)
+++ jifty/trunk/lib/Jifty/Manual/Preload.pod	Tue Aug 18 17:54:17 2009
@@ -4,6 +4,12 @@
 
 =head1 DESCRIPTION
 
+Preloading lets you optimistically load regions before they are to be
+displayed. This improves user experience because preloaded updates are
+effectively instant; the user does not wait for an HTTP request/response cycle.
+The request/response cycle still happens, but it happens behind the scenes
+while the user is filling out the form or reading the current page.
+
 =head1 WARNING
 
 Preloading is applicable only if your use case fulfills a specific set of
@@ -42,5 +48,37 @@
 
 Good luck!
 
+=head1 USAGE
+
+To mark a form element as preloadable, use the C<< preload => 'cache_key' >>
+option:
+
+    form_submit(
+        onclick => {
+            submit       => $vote,
+            preload      => 'vote',
+            refresh_self => 1,
+            arguments    => {
+                change => $next_change->id,
+            },
+        },
+    );
+
+This marks the onclick handler as preloadable. When this button is I<rendered>,
+the user's web browser will request this region immediately. When this button
+is button is I<clicked>, the user's web browser will instantly refresh the
+region without having to send an AJAX request and wait for the response.
+
+The value of C<preload> is a cache key. This lets you reuse the same cache for
+multiple handlers. For example, if you're going to display ten vote buttons,
+then ordinarily you would make ten preload requests. However, if you give all
+of the buttons the C<vote> cache key, only one preload request will be made.
+Obviously this means that the specific button being clicked should not matter.
+If you have a "undo vote" button which sends you backwards, you would not want
+to preload that with the same cache key as regular votes. In fact, you probably
+do not want to preload it all if it's a rare occurrence.
+
+=head1 GORY DETAILS
+
 =cut