TurboGears – ToscaWidgets 表單

任何Web應用程式最關鍵的方面之一是為使用者呈現使用者介面。HTML 提供了一個<form>標籤，用於設計介面。表單元素，例如文字輸入、單選按鈕、選擇等，可以適當使用。使用者輸入的資料以HTTP請求訊息的形式，透過GET或POST方法提交到伺服器端指令碼。

伺服器端指令碼必須從HTTP請求資料中重新建立表單元素。因此，表單元素必須定義兩次——一次在HTML中，一次在伺服器端指令碼中。

使用HTML表單的另一個缺點是很難（如果不是不可能的話）動態地渲染表單元素。HTML本身不提供驗證使用者輸入的方法。

ToscaWidgets2

TurboGears 依賴於 ToscaWidgets2，這是一個靈活的表單渲染和驗證庫。使用 ToscaWidgets，我們可以在Python指令碼中定義表單欄位，並使用HTML模板渲染它們。也可以對tw2欄位應用驗證。

ToscaWidgets 庫包含許多模組。下面列出了一些重要的模組：

tw2.core − 它提供核心功能。此模組中的小部件並非旨在供終端使用者使用。
tw2.forms − 這是一個基本的表單庫。它包含用於欄位、欄位集和表單的小部件。
tw2.dynforms − 它包含動態表單功能。
tw2.sqla − 這是 SQLAlchemy 資料庫的介面。

tw2.forms

它包含一個Form類，作為自定義表單的基礎。有一個TableForm類，它在兩列表格中渲染欄位非常有用。ListForm 以無序列表的形式呈現其欄位。

下表顯示了 tw2.forms 模組中最常用的欄位型別：

序號	欄位及描述
1	TextField 單行文字輸入欄位
2	TextArea 多行文字輸入欄位
3	CheckBox 顯示帶有標籤的可選中矩形框
4	CheckBoxList 多選複選框組
5	RadioButton 用於選擇/取消選擇的切換按鈕
6	RadioButtonList 一組互斥的單選按鈕
7	PasswordField 類似於TextField，但輸入鍵不會顯示
8	CalendarDatePicker 允許使用者選擇日期
9	SubmitButton 提交表單的按鈕
10	ImageButton 頂部帶有影像的可點選按鈕
11	SingleSelectField 允許從列表中選擇單個專案
12	MultipleSelectField 允許從列表中選擇多個專案
13	FileField 用於上傳檔案的欄位
14	EmailField 電子郵件輸入欄位
15	URLField 輸入URL的輸入欄位
16	NumberField 數字微調框
17	RangeField 數字滑塊

在下面的示例中，構建了一個使用其中一些小部件的表單。雖然大多數這些小部件都在 tw2.forms 中定義，但 CalendarDateField 在 tw2.Dynforms 模組中定義。因此，這兩個模組以及 tw2.core 在開頭都被匯入：

import tw2.core as twc
import tw2.forms as twf
import tw2.dynforms as twd

ToscaWidgets 表單是從tw2.forms.form基類派生的類。所需的小部件放置在 Layout 物件中。在此示例中，使用TableLayout。小部件以兩列表格的形式呈現。第一列顯示標題，第二列顯示輸入或選擇欄位。

使用以下建構函式建立 TextField 物件：

twf.TextField(size, value = None)

如果沒有提及，TextField 物件將採用預設大小，並且最初為空白。宣告 TextArea 物件時，可以提及行數和列數。

twf.TextArea("",rows = 5, cols = 30)

NumberField 物件是一個 TextField，它只能接受數字。在右側邊框上生成向上和向下箭頭，以增加或減少其中的數字。初始值也可以作為建構函式中的引數指定。

twf.NumberField(value)

在 CalendarDatePicker 框的右側，顯示一個日曆按鈕。按下時，會彈出一個日期選擇器。使用者可以手動在框中鍵入日期或從日期選擇器中選擇。

twd.CalendarDatePicker()

EmailField 物件呈現一個 TextField，但其中的文字必須採用電子郵件格式。

EmailID = twf.EmailField()

以下表單還有一個 RadioButtonList。此類的建構函式包含一個 List 物件作為 options 引數的值。將為每個選項渲染一個單選按鈕。預設選擇由 value 引數指定。

twf.RadioButtonList(options = ["option1","option2"],value = option1)

CheckBoxList 為列表中的每個選項渲染複選框。

twf.CheckBoxList(options = [option1, option2, option3])

下拉列表在此 ToscaWidgets 庫中稱為 SingleSelectfield。與 options 引數對應的 List 物件中的專案構成下拉列表。可見標題設定為 prompt_text 引數的值。

twf.SingleSelectField(prompt_text = 'text', options=['item1', 'item2', 'item3'])

預設情況下，表單顯示一個 Submit 按鈕，其標題為“儲存”。為了顯示另一個標題，建立一個 SubmitButton 物件並將其指定為 value 引數。

twf.SubmitButton(value = 'Submit')

表單提交到一個 URL，該 URL 指定為表單的 action 引數的值。預設情況下，表單資料透過 http POST 方法提交。

action = 'URL'

在以下程式碼中，使用上述解釋的小部件設計了一個名為 AdmissionForm 的表單。在 RootController 類之前將此程式碼新增到 root.py 中。

class AdmissionForm(twf.Form):
   class child(twf.TableLayout):
      NameOfStudent = twf.TextField(size = 20)
      AddressForCorrespondance = twf.TextArea("", rows = 5, cols = 30)
      PINCODE = twf.NumberField(value = 431602)
      DateOfBirth = twd.CalendarDatePicker()
      EmailID = twf.EmailField()
      Gender = twf.RadioButtonList(options = ["Male","Female"],value = 'Male')
      Subjects = twf.CheckBoxList(options = ['TurboGears', 'Flask', 'Django', 'Pyramid'])

      MediumOfInstruction = twf.SingleSelectField(prompt_text = 'choose',
         options = ['English', 'Hindi', 'Marathi', 'Telugu'])
			
      action = '/save_form'
      submit = twf.SubmitButton(value ='Submit')

現在將以下程式碼另存為模板目錄中的twform.html：

<!DOCTYPE html>
<html xmlns = "http://www.w3.org/1999/xhtml"
   xmlns:py = "http://genshi.edgewall.org/"
   lang = "en">
   
   <head>
      <title>TurboGears Form Example</title>
   </head>
   
   <body>
      <div id = "tw form">
         ${form.display(value = dict(title = 'default title'))}
      </div>
   </body>
   
</html>

在 RootController 類（在 root.py 中）中，新增以下控制器函式：

@expose('hello.templates.twform')
def twform(self, *args, **kw):
   return dict(page = 'twform', form = MovieForm)

在 AdmissionForm 類中，我們將stipulated/save_form作為操作URL。因此，在 RootController 中新增save_form()函式。

@expose()
def save_movie(self, **kw):
   return str(kw)

確保伺服器正在執行（使用 gearbox serve）。在瀏覽器中輸入https://:8080/twform。

按下提交按鈕會將此資料釋出到save_form() URL，該 URL 將以字典物件的形式顯示錶單資料。

{
   'EmailID': u'lathkar@yahoo.com', 
   'NameOfStudent': u'Malhar Lathkar', 
   'Gender': u'Male', 
   'PINCODE': u'431602', 
   'DateOfBirth': u'2015-12-29', 
   'Subjects': [u'TurboGears', u'Flask', u'Django'], 
   'MediumOfInstruction': u'', 
   'AddressForCorrespondance': u'Shivaji Nagar\r\nNanded\r\nMaharashtra'
}

列印頁面