Warning: Can't synchronize with repository "(default)" (Unsupported version control system "svn": No module named svn). Look in the Trac log for more information.

Changes between Version 22 and Version 23 of SimpleWidgetForm


Ignore:
Timestamp:
07/18/06 11:11:30 (13 years ago)
Author:
milde
Comment:

Basic wiki-fication

Legend:

Unmodified
Added
Removed
Modified
  • SimpleWidgetForm

    v22 v23  
    11'''Note:''' Check the bottom of the page for the example project. 
    2  
    3 {{{ 
    4 #!rst 
    5 ============= 
    6 FormsTutorial 
    7 ============= 
    82 
    93This is a TurboGears (http://www.turbogears.org) project. It can be 
     
    2721displays a success message on the index page. 
    2822 
    29 Starting the Project 
    30 -------------------- 
     23== Starting the Project == 
    3124 
    3225As in 0.8, tg-admin quickstart creates a new project. This project was created 
    33 with the name ``FormsTutorial``. 
     26with the name `FormsTutorial`. 
    3427 
    3528* Note: This tutorial does not contain step-by-step instructions to create the final project. 
     
    4033layout has changed a bit. 
    4134All configuration that was previously duplicated between dev and prod 
    42 has been moved to ``formstutorial/config/app.cfg``. 
    43  
    44 Some features of the ``app.cfg`` file to note (but which will 
     35has been moved to `formstutorial/config/app.cfg`. 
     36 
     37Some features of the `app.cfg` file to note (but which will 
    4538not be discussed): 
    4639 
    4740* You can now change the templating engine basis by installing a new 
    4841  templating plugin. Control which is active by setting the 
    49   ``tg.defaultview`` setting. 
     42  `tg.defaultview` setting. 
    5043* TurboGears now requires you to explicitly state that an exposed method can 
    5144  be formatted as json. You can restore the 0.8 behavior by setting the 
    52   ``tg.allow_json`` variable to true. 
     45  `tg.allow_json` variable to true. 
    5346* TurboGears now comes with Visit Tracking and an Identity framework. Both 
    5447  are disabled by default. 
    5548 
    56  
    57 Starting from the index() 
    58 ------------------------- 
    59  
    60 Open up ``formstutorial/controllers.py`` in your favorite text editor. Ignore 
    61 the first part and skip down to the ``Root`` class. The first major change 
     49== Starting from the index() == 
     50 
     51Open up `formstutorial/controllers.py` in your favorite text editor. Ignore 
     52the first part and skip down to the `Root` class. The first major change 
    6253here is the new decorators. 
    6354 
    64 In earlier versions of 0.9 svn, the ``@expose`` decorator both published the 
     55In earlier versions of 0.9 svn, the `@expose` decorator both published the 
    6556decorated method and provided form validation. This was deemed to be 
    66 inflexible, and in 0.9 ``@expose`` provides publishing related functions 
    67 (template, engine, allow_json, etc) while the new ``@validate`` decorator 
     57inflexible, and in 0.9 `@expose` provides publishing related functions 
     58(template, engine, allow_json, etc) while the new `@validate` decorator 
    6859dictates which form (keep reading, forms are coming) to use for input 
    6960processing. 
    7061 
    71 You may notice that templates passed to ``@expose`` in this example don't 
     62You may notice that templates passed to `@expose` in this example don't 
    7263start with "formstutorial". This is the new relative import feature in Kid. 
    7364Naming your templates this way simplifies project renaming. 
    7465 
    75 Take a quick glance at ``formstutorial/templates/welcome.kid``.  
     66Take a quick glance at `formstutorial/templates/welcome.kid`.  
    7667 
    7768The main feature 
    78 to notice here is the use of ``std.url`` for the link. If your project was 
    79 mounted at ``http://blah/foo/``, ``std.url`` will take the '/foo/' into 
     69to notice here is the use of `std.url` for the link. If your project was 
     70mounted at `http://blah/foo/`, `std.url` will take the '/foo/' into 
    8071account and send your users to '/foo/add' rather than the incorrect '/add'. 
    8172 
    82 We've exhausted the interesting bits of index, now lets move on to ``add``. 
    83  
    84 Intro to Forms and Widgets 
    85 -------------------------- 
     73We've exhausted the interesting bits of index, now lets move on to `add`. 
     74 
     75== Intro to Forms and Widgets == 
     76 
    8677The ``formstutorial/templates/form.kid`` is a completely generic form 
    8778displaying template. It takes an optional title (default is 'Forms Tutorial') 
     
    10394You must have your Fields in a Form in order to use the widgets framework:: 
    10495 
     96{{{ 
     97#!python 
    10598  example_form = widgets.TableForm( 
    10699        fields=[widgets.TextField(name="test",label="Example")], 
    107100        submit_text="Submit Me") 
     101}}} 
    108102 
    109103This proto-form needs to be put on the page by calling it with an action 
    110104argument in your template:: 
    111105 
     106{{{ 
     107#!python 
    112108  ${example_form(action="sample")} 
     109}}} 
    113110 
    114111Which will produce the following output:: 
    115112 
     113{{{ 
     114#!text/html 
    116115    <FORM ACTION="sample" NAME="form" METHOD="post"> 
    117116        <TABLE BORDER="0"> 
     
    132131        </TABLE> 
    133132    </FORM> 
     133}}} 
    134134 
    135135The form strips off the submit field so that you don't have to deal with it. 
    136 If you do want to manage the submit button, add a ``widget.Submit`` to your 
     136If you do want to manage the submit button, add a `widget.Submit` to your 
    137137form. The default label is the capitalized widget name. Create a custom label 
    138 using the ``label`` argument. 
     138using the `label` argument. 
    139139 
    140140Conversion from a python value to a string displayed as part of the form is 
    141141handed by a FormEncode validator, which is attached to the widget using the 
    142 named ``validator`` argument. More on validation later. 
     142named `validator` argument. More on validation later. 
    143143 
    144144The function/constructor form syntax is a bit unweildy and doesn't look nice 
    145145on the screen, so a declarative syntax is provided and is used in this 
    146146project. To take advantage of this syntax, simply subclass 
    147 ``widgets.WidgetsList``. Widgets declared this way will automatically 
     147`widgets.WidgetsList`. Widgets declared this way will automatically 
    148148have their name set to the attribute name but are otherwise exactly as they 
    149149would be if you created them as shown above. When instantiated, the widgets 
     
    151151when you put it in a form, such as adding additional widgets:: 
    152152 
     153{{{ 
     154#!python 
    153155  comment_form_2 = widgets.TableForm( 
    154156      fields=CommentFields().append( 
     
    157159      submit_text="Submit Tweaked Form" 
    158160  ) 
    159  
    160 Validation 
    161 ---------- 
    162 The ``comment_form`` has a validator on each of the first two fields. It's 
    163 fairly obvious that the first field (``validators.NotEmpty``)is required, but 
    164 the second field (``validators.Email``) is required as well. Adding a 
     161}}} 
     162 
     163== Validation == 
     164 
     165The `comment_form` has a validator on each of the first two fields. It's 
     166fairly obvious that the first field (`validators.NotEmpty`)is required, but 
     167the second field (`validators.Email`) is required as well. Adding a 
    165168validator to the field generally makes that field required, but you can get 
    166 around this by passing an ``if_empty="default value"`` argument to the 
     169around this by passing an `if_empty="default value"` argument to the 
    167170validator's constructor. Note that validators don't need to be instantiated 
    168171unless you're passing in arguments. 
    169172Each of the form's validators are rolled up into a form-wide 
    170 ``FormEncode.Schema``, which is used to check the contents for validity by the 
    171 ``@validate`` method decorator. 
    172  
    173 Methods previously had to check for ``cherrypy.form_errors`` and re-dispatch 
    174 based on the result. The new ``@error_handler`` decorator makes handling this 
     173`FormEncode.Schema`, which is used to check the contents for validity by the 
     174`@validate` method decorator. 
     175 
     176Methods previously had to check for `cherrypy.form_errors` and re-dispatch 
     177based on the result. The new `@error_handler` decorator makes handling this 
    175178error quite a bit simpler. The first argument to the decorator is the error 
    176 handling method. In the example, we're re-using ``add`` so that the form will 
     179handling method. In the example, we're re-using `add` so that the form will 
    177180be re-displayed if errors occur. A simple addition would be to display a 
    178181message to the user indicating there was a problem:: 
    179182 
     183{{{ 
     184#!python 
    180185  @expose(template=".templates.form") 
    181186  def add(self,tg_errors=None): 
     
    187192          title='New Comment' 
    188193      ) 
    189  
    190 In addition to redirecting the error, the ``@error_handler`` decorator will 
     194}}} 
     195 
     196In addition to redirecting the error, the `@error_handler` decorator will 
    191197look for a parameter named 'tg_errors' and will put error information into 
    192198that parameter. The decorator also has super RuleDispatch powers allowing you 
     
    198204As part of validation, the values of the form will be converted to the 
    199205appropriate python objects (this example is all strings, but if you used an 
    200 ``Int`` validator, for example, you'd get a python integer rather than a 
     206`Int` validator, for example, you'd get a python integer rather than a 
    201207string containing an integer). If you list the field names out 
    202208as arguments in the decorated function, as in the example, the values get put 
     
    204210argument parameter, e.g.:: 
    205211 
     212{{{ 
     213#!python 
    206214  @expose() 
    207215  @validate(form=comment_form) 
     
    212220                   data.get('comment','No Comment.')) 
    213221      #... 
    214  
    215 Then you get the data as a dictionary. The use of .get() above is needed for 
     222}}} 
     223 
     224Then you get the data as a dictionary. The use of `.get()` above is needed for 
    216225the last two because those attributes aren't guaranteed to exist by the 
    217226validators, while the first two are. 
    218227 
    219 The ``flash`` method displays a notice on the next page a user visits (and 
     228The `flash` method displays a notice on the next page a user visits (and 
    220229only on the first page). 
    221230 
    222 Back to the Index 
    223 ----------------- 
     231== Back to the Index == 
     232 
    224233And we conclude the tutorial where we began, back at the index. 
    225234 
     
    234243Note: The files for this example are courtesy of Michele Cella, but I've tweaked them 
    235244a bit! 
    236 }}}