unconed/soc/README.txt

These files are the result of the Summer of Code project "Add Ajax to Drupal".


1) Ajax Inline Editing
i.e. Being able to edit a node within a page and seeing the result immediately.

This feature was prototyped as inlineedit.js and inlineedit.module. Though this
does provide inline editing of posts, there are many problems with this
approach and it was not continued into a fully featured, finished patch/module.

The biggest hurdle is that, due to Drupal's flexible text processing system, we
cannot derive the original text from the HTML. Thus, we either need to pass the
unprocessed text along with each post (the approach taken by this prototype) or
we need a round-trip to the server to fetch that text when you start editing.

Both approaches are undesirable. Regardless, there is the downside that they
cannot accomodate the many different kinds of forms that a Drupal node can have.
Thus, it is only really useful for simple posts.

All things considered, editing posts in Drupal is a task that is best
accomplished by a separate page/form.


2) Asynchronous JavaScript file uploading (and Ajax progress bar)
i.e. Attaching a file to a post without having to reload the entire page.

Drupal.org issue: http://drupal.org/node/28483

This feature is contained in jsupload.patch. This patch applies against a recent
Drupal HEAD and mostly affects the upload.module as well as adding in a bunch of
extra JavaScript APIs. This feature has already been included in Drupal core and
will be available in the next major release of Drupal.

It does this by redirecting the submission of the form to a hidden <iframe> when
you click "Attach". Note that we cannot submit data through XMLHttpRequest
directly because you cannot read file contents from JS for security reasons.
Once the file is submitted, the upload-section of the form is updated through
DOM manipulations.

* The feature degrades back to the old upload behaviour when JavaScript is
  turned off (or is unsupported).
* If there are errors with the uploaded file (disallowed type, too big, ...),
  they are displayed at the top of the file attachments fieldset.
* I included some minor improvements to the Drupal JavaScript API and code.
* Though the hidden-iframe method sounds dirty, it's quite compact and is 100%
  implemented in .js files. It is written in a reusable fashion as an API in
  drupal.js.
* I added an API drupal_call_js() to bridge the PHP/JS gap: it takes a function
  name and arguments, and outputs a <script> tag. The kicker is that it
  preserves the structure and type of arguments, so e.g. PHP associative arrays
  end up as objects in JS.
* I also included a progressbar widget that I wrote for Neil Drumm's ongoing
  update.php work. It includes Ajax-based status updating/monitoring, but it is
  only used as a pure throbber in this patch. But as I had already written the
  code and it is going to be used in the near future anyway, I left that part
  in. If PHP supports ad-hoc upload info in the future (like Ruby on Rails does),
  we can implement that in 5 minutes using this code.

3) Ajax Tablesorting
i.e. Changing the sort order of a table without having to reload the entire page.

Drupal.org issue: http://drupal.org/node/30150

This feature is contained in jstablesort.patch, which applies to a current
Drupal HEAD. It mostly modifies the tablesorting API as well as some detail
changes to the modules that use it.

First-off: because most sortable tables in Drupal are spread over multiple
pages, client-side sorting of rows is not very useful in Drupal: choosing a
different sorting column changes the way rows are spread across the different
pages, so new data needs to be fetched regardless.

Instead, this patch fetches only the table through an Ajax request. There is
still a delay due to server round-trips, but the usability is still improved
because only the table changes and e.g. page scroll position is retained.

Originally this patch was quite a lot bigger and required modification to the
routines creating the tables. However the current incarnation works
transparently on any sortable table in Drupal, as long as it has an ID set (this
is needed to disambiguate multiple tables on a single page).

4) Ajax Pagers (switching of multiple pages in a list)

This feature is developed on top of patch #3 and thus only applies to tables
which are split into multiple pages (which covers most of the Drupal pagers).

It uses the same mechanism as above: the pager links are trapped and only the
table is fetched from the server.

Given that the usability of this feature is not as big and that the positioning
of pagers related to tables is still a point of discussion in Drupal, it is a
separate patch.
1	These files are the result of the Summer of Code project "Add Ajax to Drupal".
2
3
4	1) Ajax Inline Editing
5	i.e. Being able to edit a node within a page and seeing the result immediately.
6
7	This feature was prototyped as inlineedit.js and inlineedit.module. Though this
8	does provide inline editing of posts, there are many problems with this
9	approach and it was not continued into a fully featured, finished patch/module.
10
11	The biggest hurdle is that, due to Drupal's flexible text processing system, we
12	cannot derive the original text from the HTML. Thus, we either need to pass the
13	unprocessed text along with each post (the approach taken by this prototype) or
14	we need a round-trip to the server to fetch that text when you start editing.
15
16	Both approaches are undesirable. Regardless, there is the downside that they
17	cannot accomodate the many different kinds of forms that a Drupal node can have.
18	Thus, it is only really useful for simple posts.
19
20	All things considered, editing posts in Drupal is a task that is best
21	accomplished by a separate page/form.
22
23
24	2) Asynchronous JavaScript file uploading (and Ajax progress bar)
25	i.e. Attaching a file to a post without having to reload the entire page.
26
27	Drupal.org issue: http://drupal.org/node/28483
28
29	This feature is contained in jsupload.patch. This patch applies against a recent
30	Drupal HEAD and mostly affects the upload.module as well as adding in a bunch of
31	extra JavaScript APIs. This feature has already been included in Drupal core and
32	will be available in the next major release of Drupal.
33
34	It does this by redirecting the submission of the form to a hidden <iframe> when
35	you click "Attach". Note that we cannot submit data through XMLHttpRequest
36	directly because you cannot read file contents from JS for security reasons.
37	Once the file is submitted, the upload-section of the form is updated through
38	DOM manipulations.
39
40	* The feature degrades back to the old upload behaviour when JavaScript is
41	turned off (or is unsupported).
42	* If there are errors with the uploaded file (disallowed type, too big, ...),
43	they are displayed at the top of the file attachments fieldset.
44	* I included some minor improvements to the Drupal JavaScript API and code.
45	* Though the hidden-iframe method sounds dirty, it's quite compact and is 100%
46	implemented in .js files. It is written in a reusable fashion as an API in
47	drupal.js.
48	* I added an API drupal_call_js() to bridge the PHP/JS gap: it takes a function
49	name and arguments, and outputs a <script> tag. The kicker is that it
50	preserves the structure and type of arguments, so e.g. PHP associative arrays
51	end up as objects in JS.
52	* I also included a progressbar widget that I wrote for Neil Drumm's ongoing
53	update.php work. It includes Ajax-based status updating/monitoring, but it is
54	only used as a pure throbber in this patch. But as I had already written the
55	code and it is going to be used in the near future anyway, I left that part
56	in. If PHP supports ad-hoc upload info in the future (like Ruby on Rails does),
57	we can implement that in 5 minutes using this code.
58
59	3) Ajax Tablesorting
60	i.e. Changing the sort order of a table without having to reload the entire page.
61
62	Drupal.org issue: http://drupal.org/node/30150
63
64	This feature is contained in jstablesort.patch, which applies to a current
65	Drupal HEAD. It mostly modifies the tablesorting API as well as some detail
66	changes to the modules that use it.
67
68	First-off: because most sortable tables in Drupal are spread over multiple
69	pages, client-side sorting of rows is not very useful in Drupal: choosing a
70	different sorting column changes the way rows are spread across the different
71	pages, so new data needs to be fetched regardless.
72
73	Instead, this patch fetches only the table through an Ajax request. There is
74	still a delay due to server round-trips, but the usability is still improved
75	because only the table changes and e.g. page scroll position is retained.
76
77	Originally this patch was quite a lot bigger and required modification to the
78	routines creating the tables. However the current incarnation works
79	transparently on any sortable table in Drupal, as long as it has an ID set (this
80	is needed to disambiguate multiple tables on a single page).
81
82	4) Ajax Pagers (switching of multiple pages in a list)
83
84	This feature is developed on top of patch #3 and thus only applies to tables
85	which are split into multiple pages (which covers most of the Drupal pagers).
86
87	It uses the same mechanism as above: the pager links are trapped and only the
88	table is fetched from the server.
89
90	Given that the usability of this feature is not as big and that the positioning
91	of pagers related to tables is still a point of discussion in Drupal, it is a
92	separate patch.