Django

Code

Changeset 6652

Show
Ignore:
Timestamp:
11/05/07 07:59:52 (1 year ago)
Author:
mtredinnick
Message:

Documentation for creating custom model fields.

Files:

Legend:

Unmodified
Added
Removed
Modified
Copied
Moved

  • django/trunk/docs/model-api.txt

    r6566 r6652  
    10141014------------------ 
    10151015 
    1016 **New in Django development version** 
    1017  
    1018 Django's built-in field types don't cover every possible database column type -- 
    1019 only the common types, such as ``VARCHAR`` and ``INTEGER``. For more obscure 
    1020 column types, such as geographic polygons or even user-created types such as 
    1021 `PostgreSQL custom types`_, you can define your own Django ``Field`` subclasses. 
    1022  
    1023 .. _PostgreSQL custom types: http://www.postgresql.org/docs/8.2/interactive/sql-createtype.html 
    1024  
    1025 .. admonition:: Experimental territory 
    1026  
    1027     This is an area of Django that traditionally has not been documented, but 
    1028     we're starting to include bits of documentation, one feature at a time. 
    1029     Please forgive the sparseness of this section. 
    1030  
    1031     If you like living on the edge and are comfortable with the risk of 
    1032     unstable, undocumented APIs, see the code for the core ``Field`` class 
    1033     in ``django/db/models/fields/__init__.py`` -- but if/when the innards 
    1034     change, don't say we didn't warn you. 
    1035  
    1036 To create a custom field type, simply subclass ``django.db.models.Field``. 
    1037 Here is an incomplete list of the methods you should implement: 
    1038  
    1039 ``db_type()`` 
    1040 ~~~~~~~~~~~~~ 
    1041  
    1042 Returns the database column data type for the ``Field``, taking into account 
    1043 the current ``DATABASE_ENGINE`` setting. 
    1044  
    1045 Say you've created a PostgreSQL custom type called ``mytype``. You can use this 
    1046 field with Django by subclassing ``Field`` and implementing the ``db_type()`` 
    1047 method, like so:: 
    1048  
    1049     from django.db import models 
    1050  
    1051     class MytypeField(models.Field): 
    1052         def db_type(self): 
    1053             return 'mytype' 
    1054  
    1055 Once you have ``MytypeField``, you can use it in any model, just like any other 
    1056 ``Field`` type:: 
    1057  
    1058     class Person(models.Model): 
    1059         name = models.CharField(max_length=80) 
    1060         gender = models.CharField(max_length=1) 
    1061         something_else = MytypeField() 
    1062  
    1063 If you aim to build a database-agnostic application, you should account for 
    1064 differences in database column types. For example, the date/time column type 
    1065 in PostgreSQL is called ``timestamp``, while the same column in MySQL is called 
    1066 ``datetime``. The simplest way to handle this in a ``db_type()`` method is to 
    1067 import the Django settings module and check the ``DATABASE_ENGINE`` setting. 
    1068 For example:: 
    1069  
    1070     class MyDateField(models.Field): 
    1071         def db_type(self): 
    1072             from django.conf import settings 
    1073             if settings.DATABASE_ENGINE == 'mysql': 
    1074                 return 'datetime' 
    1075             else: 
    1076                 return 'timestamp' 
    1077  
    1078 The ``db_type()`` method is only called by Django when the framework constructs 
    1079 the ``CREATE TABLE`` statements for your application -- that is, when you first 
    1080 create your tables. It's not called at any other time, so it can afford to 
    1081 execute slightly complex code, such as the ``DATABASE_ENGINE`` check in the 
    1082 above example. 
    1083  
    1084 Some database column types accept parameters, such as ``CHAR(25)``, where the 
    1085 parameter ``25`` represents the maximum column length. In cases like these, 
    1086 it's more flexible if the parameter is specified in the model rather than being 
    1087 hard-coded in the ``db_type()`` method. For example, it wouldn't make much 
    1088 sense to have a ``CharMaxlength25Field``, shown here:: 
    1089  
    1090     # This is a silly example of hard-coded parameters. 
    1091     class CharMaxlength25Field(models.Field): 
    1092         def db_type(self): 
    1093             return 'char(25)' 
    1094  
    1095     # In the model: 
    1096     class MyModel(models.Model): 
    1097         # ... 
    1098         my_field = CharMaxlength25Field() 
    1099  
    1100 The better way of doing this would be to make the parameter specifiable at run 
    1101 time -- i.e., when the class is instantiated. To do that, just implement 
    1102 ``__init__()``, like so:: 
    1103  
    1104     # This is a much more flexible example. 
    1105     class BetterCharField(models.Field): 
    1106         def __init__(self, max_length, *args, **kwargs): 
    1107             self.max_length = max_length 
    1108             super(BetterCharField, self).__init__(*args, **kwargs) 
    1109  
    1110         def db_type(self): 
    1111             return 'char(%s)' % self.max_length 
    1112  
    1113     # In the model: 
    1114     class MyModel(models.Model): 
    1115         # ... 
    1116         my_field = BetterCharField(25) 
    1117  
    1118 Note that if you implement ``__init__()`` on a ``Field`` subclass, it's 
    1119 important to call ``Field.__init__()`` -- i.e., the parent class' 
    1120 ``__init__()`` method. 
     1016If one of the existing model fields cannot be used to fit your purposes, or if 
     1017you wish to take advantage of some less common database column types, you can 
     1018create your own field class. Full coverage of creating your own fields is 
     1019provided in the `Custom Model Fields`_ documentation. 
     1020 
     1021.. _Custom Model Fields: ../custom_model_fields/ 
    11211022 
    11221023Meta options