Changeset 6946
- Timestamp:
- 12/18/07 21:52:13 (9 months ago)
- Files:
-
- django/trunk/docs/localflavor.txt (modified) (49 diffs)
Legend:
- Unmodified
- Added
- Removed
- Modified
- Copied
- Moved
django/trunk/docs/localflavor.txt
r6931 r6946 3 3 ========================== 4 4 5 Django comes with assorted pieces of code that are useful only for a particular 6 country or culture. These pieces of code are organized as a set of 5 Following its "batteries included" philosophy, Django comes with assorted 6 pieces of code that are useful for particular countries or cultures. These are 7 called the "local flavor" add-ons and live in the ``django.contrib.localflavor`` 8 package. 9 10 Inside that package, country- or culture-specific code is organized into 7 11 subpackages, named using `ISO 3166 country codes`_. 8 12 9 .. _ISO 3166 country codes: http://www.iso.org/iso/country_codes/iso_3166_code_lists/english_country_names_and_code_elements.htm10 11 13 Most of the ``localflavor`` add-ons are localized form components deriving from 12 the newforms_ framework. To use one of these localized components, just import 13 the relevant subpackage. For example, a form with a field for French telephone 14 numbers is created like so:: 14 the newforms_ framework -- for example, a ``USStateField`` that knows how to 15 validate U.S. state abbreviations, and a ``FISocialSecurityNumber`` that knows 16 how to validate Finnish social security numbers. 17 18 To use one of these localized components, just import the relevant subpackage. 19 For example, here's how you can create a form with a field representing a 20 French telephone number:: 15 21 16 22 from django import newforms as forms … … 20 26 my_french_phone_no = fr.forms.FRPhoneNumberField() 21 27 28 Supported countries 29 =================== 30 22 31 Countries currently supported by ``localflavor`` are: 23 32 24 * Argentina_ 25 * Australia_ 26 * Brazil_ 27 * Canada_ 28 * Chile_ 29 * Finland_ 30 * France_ 31 * Germany_ 32 * Holland_ 33 * Iceland_ 34 * India_ 35 * Italy_ 36 * Japan_ 37 * Mexico_ 38 * Norway_ 39 * Peru_ 40 * Poland_ 41 * Slovakia_ 42 * `South Africa`_ 43 * Spain_ 44 * Switzerland_ 45 * `United Kingdom`_ 46 * `United States of America`_ 47 33 * Argentina_ 34 * Australia_ 35 * Brazil_ 36 * Canada_ 37 * Chile_ 38 * Finland_ 39 * France_ 40 * Germany_ 41 * Holland_ 42 * Iceland_ 43 * India_ 44 * Italy_ 45 * Japan_ 46 * Mexico_ 47 * Norway_ 48 * Peru_ 49 * Poland_ 50 * Slovakia_ 51 * `South Africa`_ 52 * Spain_ 53 * Switzerland_ 54 * `United Kingdom`_ 55 * `United States of America`_ 56 57 The ``localflavor`` package also includes a ``generic`` subpackage, containing 58 useful code that is not specific to one particular country or culture. 59 Currently, it defines date and datetime input fields based on those from 60 newforms_, but with non-US default formats. Here's an example of how to use 61 them:: 62 63 from django import newforms as forms 64 from django.contrib.localflavor import generic 65 66 class MyForm(forms.Form): 67 my_date_field = generic.forms.DateField() 68 69 .. _ISO 3166 country codes: http://www.iso.org/iso/country_codes/iso_3166_code_lists/english_country_names_and_code_elements.htm 48 70 .. _Argentina: `Argentina (django.contrib.localflavor.ar)`_ 49 71 .. _Australia: `Australia (django.contrib.localflavor.au)`_ … … 69 91 .. _United Kingdom: `United Kingdom (django.contrib.localflavor.uk)`_ 70 92 .. _United States of America: `United States of America (django.contrib.localflavor.us)`_ 71 72 The ``localflavor`` add-on also includes the ``generic`` subpackage, containing73 useful code that is not specific to one particular country or culture.74 Currently, it defines date and date & time input fields based on those from75 newforms_, but with non-US default formats. Here's an example of how to use76 them::77 78 from django import newforms as forms79 from django.contrib.localflavor import generic80 81 class MyForm(forms.Form):82 my_date_field = generic.forms.DateField()83 84 93 .. _newforms: ../newforms/ 85 94 86 87 .. admonition:: Adding a Flavor 88 89 We'd love to add more of these to Django, so please create a ticket for 90 anything that you've found useful. Please use unicode objects 91 (``u'mystring'``) for strings, rather than setting the encoding in the file 92 (see any of the existing flavors for examples). 93 95 Adding flavors 96 ============== 97 98 We'd love to add more of these to Django, so please `create a ticket`_ with 99 any code you'd like to contribute. One thing we ask is that you please use 100 Unicode objects (``u'mystring'``) for strings, rather than setting the encoding 101 in the file. See any of the existing flavors for examples. 94 102 95 103 Argentina (``django.contrib.localflavor.ar``) … … 109 117 A ``Select`` widget that uses a list of Argentina's provinces as its choices. 110 118 111 112 119 Australia (``django.contrib.localflavor.au``) 113 120 ============================================= … … 130 137 choices. 131 138 132 133 139 Brazil (``django.contrib.localflavor.br``) 134 140 ========================================== … … 151 157 A ``Select`` widget that uses a list of Brazilian states/territories as its 152 158 choices. 153 154 159 155 160 Canada (``django.contrib.localflavor.ca``) … … 188 193 its choices. 189 194 190 191 195 Chile (``django.contrib.localflavor.cl``) 192 196 ========================================= … … 204 208 choices. 205 209 206 207 210 Finland (``django.contrib.localflavor.fi``) 208 211 =========================================== … … 216 219 -------------- 217 220 218 A form field that validates input as a Finnish zip code. 221 A form field that validates input as a Finnish zip code. Valid codes 219 222 consist of five digits. 220 223 … … 225 228 choices. 226 229 227 228 230 France (``django.contrib.localflavor.fr``) 229 231 ========================================== … … 233 235 234 236 A form field that validates input as a French local phone number. The 235 correct format is 0X XX XX XX XX. 237 correct format is 0X XX XX XX XX. 0X.XX.XX.XX.XX and 0XXXXXXXXX validate 236 238 but are corrected to 0X XX XX XX XX. 237 239 … … 239 241 -------------- 240 242 241 A form field that validates input as a French zip code. 243 A form field that validates input as a French zip code. Valid codes 242 244 consist of five digits. 243 245 … … 246 248 247 249 A ``Select`` widget that uses a list of French departments as its choices. 248 249 250 250 251 Germany (``django.contrib.localflavor.de``) … … 255 256 256 257 A form field that validates input as a German identity card number 257 (Personalausweis_). 258 (Personalausweis_). Valid numbers have the format 258 259 XXXXXXXXXXX-XXXXXXX-XXXXXXX-X, with no group consisting entirely of zeroes. 259 260 … … 263 264 -------------- 264 265 265 A form field that validates input as a German zip code. 266 A form field that validates input as a German zip code. Valid codes 266 267 consist of five digits. 267 268 … … 271 272 A ``Select`` widget that uses a list of German states as its choices. 272 273 273 274 274 Holland (``django.contrib.localflavor.nl``) 275 275 =========================================== … … 297 297 choices. 298 298 299 300 299 Iceland (``django.contrib.localflavor.is_``) 301 300 ============================================ … … 305 304 306 305 A form field that validates input as an Icelandic identification number 307 (kennitala). 306 (kennitala). The format is XXXXXX-XXXX. 308 307 309 308 ISPhoneNumberField … … 319 318 choices. 320 319 321 322 320 India (``django.contrib.localflavor.in_``) 323 321 ========================================== … … 327 325 328 326 A form field that validates input as an Indian state/territory name or 329 abbreviation. 327 abbreviation. Input is normalized to the standard two-letter vehicle 330 328 registration abbreviation for the given state or territory. 331 329 … … 342 340 choices. 343 341 344 345 342 Italy (``django.contrib.localflavor.it``) 346 343 ========================================= … … 362 359 -------------- 363 360 364 A form field that validates input as an Italian zip code. 361 A form field that validates input as an Italian zip code. Valid codes 365 362 must have five digits. 366 363 … … 374 371 375 372 A ``Select`` widget that uses a list of Italian regions as its choices. 376 377 373 378 374 Japan (``django.contrib.localflavor.jp``) … … 382 378 ----------------- 383 379 384 A form field that validates input as a Japanese postcode. 385 It accepts sevendigits, with or without a hyphen.380 A form field that validates input as a Japanese postcode. It accepts seven 381 digits, with or without a hyphen. 386 382 387 383 JPPrefectureSelect … … 389 385 390 386 A ``Select`` widget that uses a list of Japanese prefectures as its choices. 391 392 387 393 388 Mexico (``django.contrib.localflavor.mx``) … … 399 394 A ``Select`` widget that uses a list of Mexican states as its choices. 400 395 401 402 396 Norway (``django.contrib.localflavor.no``) 403 397 ========================================== … … 414 408 -------------- 415 409 416 A form field that validates input as a Norwegian zip code. 410 A form field that validates input as a Norwegian zip code. Valid codes 417 411 have four digits. 418 412 … … 423 417 its choices. 424 418 425 426 419 Peru (``django.contrib.localflavor.pe``) 427 420 ======================================== … … 437 430 438 431 A form field that validates input as an RUC (Registro Unico de 439 Contribuyentes) number. Valid RUC numbers have elevendigits.432 Contribuyentes) number. Valid RUC numbers have 11 digits. 440 433 441 434 PEDepartmentSelect … … 443 436 444 437 A ``Select`` widget that uses a list of Peruvian Departments as its choices. 445 446 438 447 439 Poland (``django.contrib.localflavor.pl``) … … 460 452 461 453 A form field that validates input as a Polish National Official Business 462 Register Number (REGON_), having either seven or nine digits. 454 Register Number (REGON_), having either seven or nine digits. The checksum 463 455 algorithm used for REGONs is documented at 464 456 http://wipos.p.lodz.pl/zylla/ut/nip-rego.html. … … 469 461 ----------------- 470 462 471 A form field that validates input as a Polish postal code. 463 A form field that validates input as a Polish postal code. The valid format 472 464 is XX-XXX, where X is a digit. 473 465 … … 475 467 ---------------- 476 468 477 A form field that validates input as a Polish Tax Number (NIP). 478 formats are XXX-XXX-XX-XX or XX-XX-XXX-XXX. 469 A form field that validates input as a Polish Tax Number (NIP). Valid 470 formats are XXX-XXX-XX-XX or XX-XX-XXX-XXX. The checksum algorithm used 479 471 for NIPs is documented at http://wipos.p.lodz.pl/zylla/ut/nip-rego.html. 480 472 … … 491 483 provinces) as its choices. 492 484 493 494 485 Slovakia (``django.contrib.localflavor.sk``) 495 486 ============================================ … … 498 489 ----------------- 499 490 500 A form field that validates input as a Slovak postal code. 491 A form field that validates input as a Slovak postal code. Valid formats 501 492 are XXXXX or XXX XX, where X is a digit. 502 493 … … 510 501 511 502 A ``Select`` widget that uses a list of Slovak regions as its choices. 512 513 503 514 504 South Africa (``django.contrib.localflavor.za``) … … 518 508 --------- 519 509 520 A form field that validates input as a South African ID number. 510 A form field that validates input as a South African ID number. Validation 521 511 uses the Luhn checksum and a simplistic (i.e., not entirely accurate) check 522 512 for birth date. … … 525 515 --------------- 526 516 527 A form field that validates input as a South African postcode. 517 A form field that validates input as a South African postcode. Valid 528 518 postcodes must have four digits. 529 530 519 531 520 Spain (``django.contrib.localflavor.es``) … … 542 531 543 532 A form field that validates input as a Spanish bank account number (Codigo 544 Cuenta Cliente or CCC). 533 Cuenta Cliente or CCC). A valid CCC number has the format 545 534 EEEE-OOOO-CC-AAAAAAAAAA, where the E, O, C and A digits denote the entity, 546 office, checksum and account, respectively. 547 validates the entity and office. 548 account. 535 office, checksum and account, respectively. The first checksum digit 536 validates the entity and office. The second checksum digit validates the 537 account. It is also valid to use a space as a delimiter, or to use no 549 538 delimiter. 550 539 … … 552 541 ------------------ 553 542 554 A form field that validates input as a Spanish phone number. 543 A form field that validates input as a Spanish phone number. Valid numbers 555 544 have nine digits, the first of which is 6, 8 or 9. 556 545 … … 558 547 ----------------- 559 548 560 A form field that validates input as a Spanish postal code. 549 A form field that validates input as a Spanish postal code. Valid codes 561 550 have five digits, the first two being in the range 01 to 52, representing 562 551 the province. … … 571 560 572 561 A ``Select`` widget that uses a list of Spanish regions as its choices. 573 574 562 575 563 Switzerland (``django.contrib.localflavor.ch``) … … 586 574 ------------------ 587 575 588 A form field that validates input as a Swiss phone number. 589 format is 0XX XXX XX XX. 576 A form field that validates input as a Swiss phone number. The correct 577 format is 0XX XXX XX XX. 0XX.XXX.XX.XX and 0XXXXXXXXX validate but are 590 578 corrected to 0XX XXX XX XX. 591 579 … … 593 581 -------------- 594 582 595 A form field that validates input as a Swiss zip code. 583 A form field that validates input as a Swiss zip code. Valid codes 596 584 consist of four digits. 597 585 … … 600 588 601 589 A ``Select`` widget that uses a list of Swiss states as its choices. 602 603 590 604 591 United Kingdom (``django.contrib.localflavor.uk``) … … 622 609 A ``Select`` widget that uses a list of UK nations as its choices. 623 610 624 625 611 United States of America (``django.contrib.localflavor.us``) 626 612 ============================================================ … … 637 623 A valid SSN must obey the following rules: 638 624 639 * Format of XXX-XX-XXXX640 * No group of digits consisting entirely of zeroes641 * Leading group of digits cannot be 666642 * Number not in promotional block 987-65-4320 through 987-65-4329643 * Number not one known to be invalid due to widespread promotional644 use or distribution (e.g., the Woolworth's number or the 1962645 promotional number)625 * Format of XXX-XX-XXXX 626 * No group of digits consisting entirely of zeroes 627 * Leading group of digits cannot be 666 628 * Number not in promotional block 987-65-4320 through 987-65-4329 629 * Number not one known to be invalid due to widespread promotional 630 use or distribution (e.g., the Woolworth's number or the 1962 631 promotional number) 646 632 647 633 USStateField … … 655 641 -------------- 656 642 657 A form field that validates input as a U.S. zip code.Valid formats are643 A form field that validates input as a U.S. ZIP code. Valid formats are 658 644 XXXXX or XXXXX-XXXX. 659 645 … … 661 647 ------------- 662 648 663 A form Selectwidget that uses a list of U.S. states/territories as its664 choices. 649 A form ``Select`` widget that uses a list of U.S. states/territories as its 650 choices.
