This short tutorial will guide you through an example TDI usage scenario. It is a good point to start with, as it introduces main TDI principles. It has absolutely no ambitions to present a complete description. For further information, consider reading:
- Introductory description and motivation behind TDI.
- Full documentation: Browse side and protocol description.
The tutorial should take only about 5 minutes.
In this tutorial, we will demonstrate TDI principles on an example e-shop that sells animals. The homepage of such shop may look like this:
We will show some examples of what can TDI do with this page. First, a customer sets a filter, then he or she selects an animal to buy. TDI will be responsible to update the page state using AJAX.
Submit a Form
The home page contains a filter, which is represented by an HTML element that may look like this:
As the first action, the customer sets the filter to show only animals with no legs or more than four legs. After checking the boxes, the filter is submitted:
Under normal circumstances, the filter settings (values of checkboxes) are sent to the server via a POST request:
The server is expected to generate a new complete HTML page that will look similarly to the previous one, but with the list of animals updated to reflect the filter state.
TDI in Action
(note the class attribute at the 1st line)
One small change to the page, one giant modification to its behavior. If we submit the form with
tdi class, TDI script automatically intercepts the action and modifies the request sent to the server:
(note the extra parameters at the 1st line)
What exactly happened and why? TDI added two extra parameters to the request:
_infuse=1- this tells the server that TDI is in action and the response should be modified accordingly. Namely, instead of returning the whole new page, only a list of TDI instructions is expected in the response.
_ts- contains the current timestamp to avoid caching. Do not bother with it now.
The server sees the
_infuse parameter, so it only returns the updated list of products (ugh, animals, of course) satisfying new filter settings. To render the new list, the server typically invokes the very same server-side template that is used to generate the list inside a whole page. The response will have
text/xml content type (instead of
text/html) and it will look like this:
update instruction, there is an HTML code corresponding to the new list content. The response tells the client to update the corresponding DOM element.
To see a little bit more of TDI features, we will follow our user one more step. Imagine a Buy link is clicked:
If we want to process this action with TDI, we just tag the link with
tdi class again:
And, once again, TDI intercepts the user action and appends its two extra parameters (
_ts) to the request:
The server does not generate the whole page because of the
_infuse parameter is present. Instead, it sends necessary updates to the page. In this case, more than one instruction is present, so the logic will have to be a little bit more complicated.
- Inserts a new item in the shopping cart, before the total sum.
- Remove one CSS class from a user profile box and adds another class. This visually indicates that the shopping cart is non-empty (by a different color, for example).
- Changes the total amount to be paid.
- ... and so on.
After all of the instructions are performed, the page will be updated.
And that's it! Again, the update is done without the page being reloaded.
What else can TDI do for you
The example above was just a quick introduction. TDI can do much more. The concise list of its basic features follows to give you an idea.
- Update the content of some HTML element in the page DOM.
- Add or remove a class of an HTML element.
- Insert a new HTML code to some specified place.
- Include a custom style (CSS). Optionally, it ensures the style is used only once for the page.
- Reload the current page completely.
- Redirect the user to a different URL.
- Open a new browser window.
- Also, TDI may be extended with additional custom actions, such as displaying user messages etc.
To provide a feedback to users, TDI allows to add a visual indication of a request being processed. See Browser-side documentation for details.
If you want to experiment with TDI by yourself you may: