Commits

Christian Scholz committed 23d84da

added some documentation of features to come.

Comments (0)

Files changed (3)

docs/ajaxprotocol.txt

+=================
+The Ajax Protocol
+=================
+
+When having dynamic pages which change without a complete reload, Ajax is in play. For making these things easier :mod:`quantumcore.dynamicpage` provides some helper functionality for sending data from and to the rendered HTML page.
+
+To understand what's happening here are the components which play together:
+
+    ``Page``
+        The Page object is the component which binds everything together. It's the one rendering the actual HTML page and knows about all variants and actions.
+    ``Slot``
+        A slot is simply a method inside a ``PageVariant`` which returns a bit of HTML.
+    ``PageVariant``
+        A ``PageVariant`` class holds the slot methods explained above and is referenced from a ``Page`` object by name via a dictionary.
+    ``Action``
+        An action is a method inside the ``Page`` object which performs some functionality and returns some commands to be send to the HTML page.
+    ``HTML Page``
+        The HTML page is the output of a ``Page`` object when being called. One can see it as the representation of the ``Page`` object and the selected ``PageVariants`` on the user's screen. This HTML page can change on the fly without a complete reload by replacing, deleting or appending parts of it.
+        
+
+Lets assume that a page is rendered on a user's browser and the user clicks the ``Edit`` button. We now want one part of the page to be replaced by the edit form.
+
+To do this the following needs to be setup:
+
+    * A JavaScript trigger needs to be defined for the Edit button click
+    * A handler on the server needs to respond to this action. Let's assume it responds to ``/ajax/editform``.
+    
+Then the flow for the example is as follows:
+
+ 1. The user clicks the ``Edit`` button
+ 2. The Javascript trigger is activated and does a ``GET`` on ``/ajax/editform``.
+ 3. The server is instantiating the corresponding ``Page`` object
+ 4. The server calls the ``editform()`` method on this ``Page`` object
+ 5. The ``editform()`` method is somehow creating the form and using a helper function to prepare commands to be send to the HTML page.
+ 6. The server sends those commands encoded via JSON as a response to the ``GET`` request.
+ 7. A :term:`jQuery` plugin is called when receiving the response, reading the commands and performing them.
+ 8. One command will be "replace the contents of DOM element ``content`` with this bit of HTML" and the HTML will be the editform.
+
+In the end the user will see the editform. Additionally we might have some command which simply calls some initialization script for e.g. activating an Rich Text Editor or something similar.
+
+Something like this will also happen when the user saves the form. Only a ``POST`` request probably with normal POST data will be sent to the server (to a different URL, e.g. ``/ajax/save``) and again some commands will be received, either for displaying errors or for replacing the form by the new content.
+
+
+Commands
+========
+
+
+The command structure
+*********************
+
+Commands being sent back look like follows in JSON::
+
+    [{<command> : <command payload>}, 
+     ...
+    ]
+    
+An example for replacing an element might look like this::
+
+    [{ replace : 
+        { id: 'content', content: '<form />' } 
+     }
+    ]
+
+The commands
+************
+
+:mod:`quantumcore.dynamicpage` provides only simple commands like follows:
+
+The helper functions on the server side
+***************************************
+
+
+The jQuery plugin
+*****************
+    
+    
+Writing your own command
+************************
+
+
+Registering your command
+------------------------
+
    
    intro
    tutorial
+   internals
    
 
 Indices and tables

docs/internals.txt

+=============
+The Internals
+=============
+
+This chapter is mainly for developers who want to start extending :mod:`quantumcore.dynamicpage`. It explains how it works and how you can setup a development sandbox.
+
+.. toctree::
+   :maxdepth: 2
+   
+   ajaxprotocol