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 Initial Version and Version 1 of AutoCompleteField


Ignore:
Timestamp:
02/11/06 12:20:18 (13 years ago)
Author:
bjourne@…
Comment:

an howto about AutoCompleteField

Legend:

Unmodified
Added
Removed
Modified
  • AutoCompleteField

    v1 v1  
     1Check out [http://www.google.com/webhp?complete=1&hl=en Google Suggest] to see input completion in action. The AutoCompleteField widgets allows you to very easily create a similar effect in TurboGears. See also the [http://trac.turbogears.org/turbogears/browser/trunk/turbogears/widgets/big_widgets.py#L83 AutoCompleteField] and the [http://trac.turbogears.org/turbogears/browser/trunk/turbogears/widgets/big_widgets.py#L83 AutoCompleteDesc] classes source code. 
     2 
     3== How to use AutoCompleteField ==  
     4 
     5 1. Create a new probject (`tg-admin quickstart`) and name it autocomplete, or reuse an old one. We will mount the code required for the `AutoCompleteField` one level below your `RootController`. 
     6 1. If you created a new project, remove the methods `login` and `logout` from your `controllers.py` file. We won't use them for this tutorial. 
     7 1. Import the AutoCompleteField widget to `controllers.py` with  
     8{{{ 
     9#!python 
     10from turbogears.widgets import AutoCompleteField 
     11}}} 
     12 1. Create a controller-class with an index-method that shows an empty page (for now): 
     13{{{ 
     14#!python 
     15class TestInputCompletion(controllers.Controller): 
     16    @turbogears.expose(template="autocomplete.templates.complete") 
     17    def index(self): 
     18        return dict() 
     19}}} 
     20 1. Mount an instance of your new controller: 
     21{{{ 
     22#!python 
     23class Root(controllers.RootController): 
     24    testcompletion = TestInputCompletion() 
     25}}} 
     26 Create the `complete.kid` file necessary to display the empty page by copying `welcome.kid` to `complete.kid` and clearing out everything inside the body. The file should look like this: 
     27{{{ 
     28<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> 
     29<html xmlns="http://www.w3.org/1999/xhtml" xmlns:py="http://purl.org/kid/ns#" 
     30    py:extends="'master.kid'"> 
     31 
     32<head> 
     33    <meta content="text/html; charset=UTF-8" http-equiv="content-type" py:replace="''"/> 
     34    <title>Testing the AutoCompleteField widget!</title> 
     35</head> 
     36 
     37<body> 
     38</body> 
     39</html> 
     40}}} 
     41 1. You can check if everything works OK so far by going to `localhost:8080/testcompletion`. You should see a blank page. 
     42 1. Add an `__init__` method to `TestInputCompletion` where you instantiate the AutoCompleteField widget: 
     43{{{ 
     44#!python 
     45def __init__(self): 
     46    self.acfield = AutoCompleteField()  
     47}}} 
     48 1. Modify complete.kid and add {{{${acfield.display()}}}} inside the `<body>` tag. That code automagically inserts all the HTML and Javascript code necessary to display the AutoCompleteField if we pass it an instance. Then change the `index` method so that the template gets passed our widget: 
     49{{{ 
     50#!python 
     51@turbogears.expose(template="autocomplete.templates.complete") 
     52def index(self): 
     53    return dict(acfield = self.acfield) 
     54}}} 
     55 1. You should now be able to see a lonely input-box if you go to http://localhost:8080/testcompletion. However, it doesn't complete any input yet. 
     56 1. The next step is to give the AutoCompleteField some data with which it can complete input. In a real program the data probably comes from a database, but here we just add the strings to the TestInputCompletion class that we wan't completed: 
     57{{{ 
     58#!python 
     59class TestInputCompletion(controllers.Controller): 
     60    countries = ["Abkhazia", "Afghanistan", "Akrotiri", "Åland", "Albania", "Algeria", 
     61                 "American Samoa", "Andorra", "Angola", "Anguilla", "Antigua and Barbuda", 
     62                 "Argentina", "Armenia", "Aruba", "Ascension Island", "Austria", "Azerbaijan"] 
     63}}} 
     64 1. Add a `search` method to TestInputCompletion: 
     65{{{ 
     66#!python 
     67@turbogears.expose(format = "json") 
     68def search(self, input): 
     69    input = input.lower() 
     70    matches = [country for country in self.countries \ 
     71               if country.lower().startswith(input)] 
     72    return dict(matches = matches) 
     73}}} 
     74 This method takes as it's input a search string and returns a page in JSON format with all the countries it thinks matches the search string. You can test it out by going to: http://localhost:8080/testcompletion/search?input=a. 
     75 1. Change how the AutoCompleteField is constructed so that it can interact witht the search method: 
     76{{{ 
     77#!python 
     78def __init__(self): 
     79    self.acfield = AutoCompleteField(search_controller = "search", 
     80                                     search_param = "input", 
     81                                     result_name = "matches") 
     82}}} 
     83  
     84That's it! You should now have an awesome AutoCompleteField that completes on countrynames. If not, state your problem here and the tutorial will be updated. 
     85 
     86== Possible additions == 
     87 * It would be cool if the AutoCompleteField updated a FastDataGrid in realtime. Only those rows that matches the input in the AutoCompleteField should be shown. 
     88 * Instead of hardcoding which strings that should be completed, the strings should come from a database. 
     89