From fb39bca24f66238f603e4791dc9199693a631666 Mon Sep 17 00:00:00 2001
From: Ismael Carnales <icarnales@gmail.com>
Date: Wed, 26 Aug 2009 08:44:22 -0300
Subject: [PATCH] added djangoitem doc

---
 docs/experimental/djangoitems.rst | 87 +++++++++++++++++++++++++++++++
 docs/experimental/index.rst       |  1 +
 2 files changed, 88 insertions(+)
 create mode 100644 docs/experimental/djangoitems.rst

diff --git a/docs/experimental/djangoitems.rst b/docs/experimental/djangoitems.rst
new file mode 100644
index 000000000..75163baf9
--- /dev/null
+++ b/docs/experimental/djangoitems.rst
@@ -0,0 +1,87 @@
+.. _topics-djangoitem:
+
+==========
+DjangoItem
+==========
+
+DjangoItems are a class of Item that gets its fields definition from a Django
+model, yo simply create a DjangoItem and specify to what Django model it
+relates to.
+
+Besides of getting the model fields defined on your Item, DjangoItem provides a
+mathod to create and populate a Django model instance with the Item data.
+
+Using DjangoItem
+================
+
+DjangoItem works much like ModelForms in Django, you create a subclass and
+define its ``django_model`` atribute to ve a valid Django model.  With this you
+will get an Item with a field for each Django model field. 
+
+In addition, you can define fields that aren't present in the model and even
+override fields that are present in the model defining them in the item. 
+
+Let's see some examples:
+
+Django model for the examples::
+
+   class Person(models.Model):
+       name = models.CharField(max_length=255)
+       age = models.IntegerField()
+
+Defining a basic DjangoItem:
+    
+   class PersonItem(DjangoItem):
+       django_model = Person
+       
+DjangoItem work just like :class:`scrapy.item.Item`::
+
+   p = PersonItem()
+   p['name'] = 'John'
+   p['age'] = '22'
+
+To obtain the Django model from the item, we call the extra method save() of
+the DjangoItem::
+
+   >>> person = p.save()
+   >>> person.name
+   'John'
+   >>> person.age
+   '22'
+   >>> person.id
+   1
+
+As you see the model is already saved when we call save, we can prevent this by
+calling it with ``commit=False``:: We can use commit=False in save method to
+obtain an unsaved model:
+
+   person = p.save(commit=False)
+   person.name
+   'John'
+   person.age
+   '22'
+   person.id
+   None
+
+As said before, we can add other fields to the Item::
+
+   class PersonItem(DjangoItem):
+       django_model = Person
+       sex = Field()
+
+   p = PersonItem()
+   p['name'] = 'John'
+   p['age'] = '22'
+   p['sex'] = 'M'
+
+.. note:: fields added to the Item won't be taken into account when doing a save()
+
+And we can override the fields of the model with your own:
+
+class PersonItem(DjangoItem):
+    django_model = Person
+    name = Field(default='No Name')
+
+This is usefull to provide properties to the field, like a default or any other
+property that your project uses.
+
diff --git a/docs/experimental/index.rst b/docs/experimental/index.rst
index ebe529a34..bfdc7cb0d 100644
--- a/docs/experimental/index.rst
+++ b/docs/experimental/index.rst
@@ -22,3 +22,4 @@ it's properly merged) . Use at your own risk.
    exporters
    images
    scripts
+   djangoitems