Nothing in web2py prevents you from using other
Ajax``ajax:w``:cite libraries such as Prototype, ExtJS, or YUI, but we decided to package jQuery because we find it to be easier to use and more powerful than other equivalent libraries. We also find that it captures the web2py spirit of being functional and concise.
### web2py_ajax.html
The scaffolding web2py application "welcome" includes a file called
``
views/web2py_ajax.html
``:code
which looks like this:
``
{{
response.files.insert(0,URL('static','js/jquery.js'))
response.files.insert(1,URL('static','css/calenadar.css'))
response.files.insert(2,URL('static','js/calendar.js'))
response.include_meta()
response.include_files()
}}
<script type="text/javascript"><!--
// These variables are used by the web2py_ajax_init
Here is a list of useful effects defined by jQuery:
- jQuery(...).show(): Makes the object visible
- jQuery(...).hide(): Makes the object hidden
- jQuery(...).slideToggle(speed, callback): Makes the object slide up or down
- jQuery(...).slideUp(speed, callback): Makes the object slide up
- jQuery(...).slideDown(speed, callback): Makes the object slide down
- jQuery(...).fadeIn(speed, callback): Makes the object fade in
- jQuery(...).fadeOut(speed, callback): Makes the object fade out
The speed argument is usually "slow", "fast" or omitted (the default). The callback is an optional function that is called when the effect is completed.
jQuery effects can also easily be embedded in helpers, for example,
in a view:
``
{{=DIV('click me!', _onclick="jQuery(this).fadeOut()")}}
``:code
jQuery is a very compact and concise Ajax library; therefore web2py does not need an additional abstraction layer on top of jQuery (except for the ``ajax`` function discussed below). The jQuery APIs are accessible and readily available in their native form when needed.
Consult the documentation for more information about these effects and other jQuery APIs.
The jQuery library can also be extended using plugins and User Interface Widgets. This topic is not covered here; see ref.``jquery:ui``:cite for details.
#### Conditional fields in forms
A typical application of jQuery effects is a form that changes its appearance based on the value of its fields.
This is easy in web2py because the SQLFORM helper generates forms that are "CSS friendly". The form contains a table with rows. Each row contains a label, an input field, and an optional third column. The items have ids derived strictly from the name of the table and names of the fields.
The convention is that every INPUT field has an id ``tablename_fieldname`` and is contained in a row with id ``tablename_fieldname__row``.
As an example, create an input form that asks for a taxpayer's name and for the name of the taxpayer's spouse, but only if he/she is married.
Create a test application with the following model:
``
db = DAL('sqlite://db.db')
db.define_table('taxpayer',
Field('name'),
Field('married', 'boolean'),
Field('spouse_name'))
``:code
and the corresponding view "default/edit.html"
``deletable``:inxx
The ``deletable=True`` argument in the SQLFORM constructor instructs web2py to display a "delete" checkbox in the edit form. It is ``False`` by default.
web2py's "web2py.js" includes the following code:
``
jQuery(document).ready(function(){
jQuery('input.delete').attr('onclick',
'if(this.checked) if(!confirm(
"{{=T('Sure you want to delete this object?')}}"))
this.checked=false;');
});
``:code
By convention this checkbox has a class equal to "delete". The jQuery code above connects the onclick event of this checkbox with a confirmation dialog (standard in JavaScript) and unchecks the checkbox if the taxpayer does not confirm:
[[image @///image/en7700.png center 480px]]
### The ``ajax`` function
In web2py.js, web2py defines a function called ``ajax`` which is based on, but should not be confused with, the jQuery function ``$.ajax``. The latter is much more powerful than the former, and for its usage, we refer you to ref.``jquery``:cite and ref.``jquery:b``:cite. However, the former function is sufficient for many complex tasks, and is easier to use.