Changes between Version 4 and Version 5 of NewManipulators

Timestamp:

Aug 21, 2006, 5:35:09 PM (18 years ago)

Author:

brantley

Comment:

Update to present.

NewManipulators

@@ -7 +7 @@
  3. Apply the data to the object and save, aka do something with the data.
 
-A validation aware model alone cannot complete this task as information needs to be provided that details the sorts of fields that should be used, and processes are needed to convert from string / post data to the pythonic data.  Furthermore many manipulation and form tasks require form fields that do not map directly to a model field, for instance a password changing form that requires a password to be given twice.  This example also illuminates how a form field might map directly to a model field, but may not want to give its direct value to the field.  As in a password, one probably wouldn't want: {{{user.password = data['password']}}}, but rather: {{{user.set_password(data['password'])}}}.
+A validation aware model alone cannot complete these tasks as information needs to be provided that details the sorts of fields that should be used, and processes are needed to convert from string / post data to the pythonic data.  Furthermore many manipulation and form tasks require form fields that do not map directly to a model field, for instance a password changing form that requires a password to be given twice.  This example also illuminates how a form field might map directly to a model field, but may not want to give its direct value to the field.  As in a password, one probably wouldn't want: {{{user.password = data['password']}}}, but rather: {{{user.set_password(data['password'])}}}.
 
 So we change Manipulators some, and then add model validation.  But we need to make our manipulator system leverage it.  In other words, when our model throws a ValidationError, we need to add it to our errors and then present our form back to the user.  This should be made simple for the developer so that they don't have to create a try/except block every time they want to save an object.
 
-This all means that validation exceptions could be thrown at any point in our manipulation process: conversion, validation, and model object saving.  There might even be more steps in the future, or with manipulators that aren't HTML based but something else like JSON.
+This means that validation exceptions could be thrown at any point in our manipulation process: conversion, validation, and model object saving.  There might even be more steps in the future, or with manipulators that aren't HTML based but something else like JSON.
 
 There are a few ways of doing this, from the developer's perspective.  Currently manipulator process in a custom view for the developer is needlessly complicated.  Compare the [http://www.djangoproject.com/documentation/forms/#using-the-changemanipulator current process] to the [http://code.djangoproject.com/wiki/CookBookManipulatorCustomManipulator rather basic one that added to the cookbook].  But with model validation it complicates both with even more code for checking for errors after the object.save().
@@ -18 +18 @@
 {{{
 #!python
-def create_article(request):
+def create_poll(request):
     try:
-        m = Article.CreateManipulator(request)
-        article = m.save()
-        return HttpResponseRedirect('/articles/update/%d/' % article.id)
+        m = Poll.CreateManipulator()
+        poll = m.process(request.POST)
+        return HttpResponseRedirect('/poll/%d/' % poll.id)
     except Form, form:
-        return render_to_response('articles/create.html', {'form': form})
+        return render_to_response('poll/create.html', {'form': form})
 }}}
 
-As you can see, our form is now more of an exception.  And our manipulation process is very simple, most of it takes place in the constructor itself, if durring that time a form is raised, it is presented.  Otherwise call "save()" on our manipulator.  In this case it creates and returns a new article. It will also raise a form if the model validation returns an error.  If no form is raised, we are done and return our Response.
-
+As you can see, our form is now more of an exception.  And our manipulation process is very simple, most of it takes place in {{{process()}}}, and if at any point a form is raised, it is presented.  Otherwise the manipulator calls and returns {{{save()}}}.  In this case it creates and returns a new poll object. It will also raise a form if the model validation returns an error.  If no form is raised, we are done and return our Response.
+
+There is a lot more code to this, as FormWrapper and FormFieldWrapper and some other pieces have been rewritten.  Here is the rub, though:
 
 {{{
@@ -35 +36 @@
     """     
     A Manipulator "manipulates" data and objects.  
-    Sample usage with Article.CreateManipulator:
-    
-    def create_article(request):
+    Sample usage with Poll.CreateManipulator:
+    
+    def create_poll(request):
     try:
-        m = Article.CreateManipulator(request)
-        article = m.save()
-        return HttpResponseRedirect(article.get_update_url())
+        m = Poll.CreateManipulator()
+        poll = m.process(request.POST)
+        return HttpResponseRedirect('/poll/%d/' % poll.id)
     except Form, form:
-        return render_to_response('articles/create.html', {'form': form})
+        return render_to_response('poll/create.html', {'form': form})
     
     As you can see, if a Manipulator needs to get information with a form, it 
-    will raise it's form.  At that point you can display it.
+    will raise it's form, which can then be placed right into a template context.
 
     To create a custom manipulator you have four functions that you may 
@@ -63 +64 @@
                     in the template context.
     """
-    
-    def __init__(self, request):
-        """
-        Initializes the Manipulator and instigates the process.  
-        Mainly you will want to define your fields here.
-        """
-        self.fields = (
-            SlugField("slug", attributes={'class': 'slug'}),
-            TextField("title", label="Headline", maxlength=60, attributes={'class': 'title'}),
-            LargeTextField("body", label="Story", attributes={'class': 'body'}),
-            DateTimeField("pub_date", label="This article will publish on this date"),
-        )
-        self.process(request.POST)
+
+    def __getitem__(self, k):
+        "Allows access of the fields via the brackets, like: manipulator['field_name']"
+        for f in self.fields:
+            if (f.name == k):
+                return f
+        raise KeyError, "Could not find field with the name %r." % k
+        
+    def __repr__(self):
+        return "Manipulator <%r, %r, %r>" % (self.fields, self.data, self.errors)
+    
+    def __init__(self):
+        # Properties that must be created:
+        self.fields = ()
+        # Properties that can optionally be created:
+        self.data = {}  # The default data given
+        self.errors = {}
     
     def convert(self, data):
@@ -91 +96 @@
         pass
     
-    def save(self):
+    def save(self, data):
         """
         Once the data has been converted and validated it is ready to be 
-        processed.  Usually this will entail updating an model instance.  To aid in
-        that task, there is a convenience self.update <see below>.
-        """
-        pass
-    
-    ### Utility Functions ###
-    def update(self, object, data):
-        """
-        Updates and saves a model object.  This will raise a form if there are any errors.
-        """
-        self.errors = object.update(data)
-        object.save()
-        if (self.errors):
-            raise Form
-        return object
-            
-    def add_errors(self, field, errors):
-        "A convenience function to add errors to a field's error list."
-        errors = list(errors)
-        self.errors.setdefault(field.name, []).extend(errors)
+        processed.  Usually this will entail creating or updating an model instance.
+        To aid in that task, there are convenience functions edit() and create(), 
+        see below for more details.
+        """
+        raise NotImplementedError
     
     ### Interneal functions ###
@@ -119 +109 @@
         "Perform the manipulation process."
         if (not data):
-            raise form
-        self.data = data.copy()
+            # Here we want to delete any data we have, just in case this manipulator is being re-used.
+            if 'data' in self.__dict__:
+                del self.data
+            if 'errors' in self.__dict__:
+                del self.errors
+            # Raise the form
+            raise self.form
+        self.data = copy_dict(data)   # copy_dict -> lambda m: dict((k, v) for k, v in m.items())
         self.errors = {}
         self._convert()
         self._validate()
+        return self._save()
     
     def _get_form(self):
@@ -129 +126 @@
     form = property(_get_form)
     
-    def _convert(self)
+    def _convert(self):
         """
         Goes through each field and converts the data in place on the data dictionary.
-        This will raise a form if there are validation errors by the end.
-        """
+        This will raise a Form if there are validation errors by the end.
+        """
+        
         for field in self.fields:
-            if (field.name in self.data):
+            name = field.name
+            if (name in self.data):
                 try:
-                    self.data[field.name] = field.to_python(self.data[field.field_name])
+                    #~ self.data[name] = field.to_python(self.data[name])
+                    self.data[name] = field.to_python(self.data[name])
                 except (validators.ValidationError, validators.CriticalValidationError), e:
-                    self.errors.setdefault(field.field_name, []).extend(e.messages)
+                    self.errors.setdefault(name, []).extend(e.messages)
         if (self.errors):
             raise self.form
         self.convert(self.data)
+        if (self.errors):
+            raise self.form
     
     def _validate(self):
@@ -149 +151 @@
         validation errors by the end.
         """
+        
         for field in self.fields:
-            for validator in field.validators:
-                try:
-                    validator(self.data[field.name])
-                except (validators.ValidationError, validators.CriticalValidationError), e:
-                    self.add_errors(e.messages)
+            name = field.name
+            #~ for validator in field.validators:
+                #~ try:
+                    #~ validator(self.data[name])
+                #~ except (validators.ValidationError, validators.CriticalValidationError), e:
+                    #~ self.errors.setdefault(name, []).extend(e.messages)
+            errors = field.validate(self.data)
+            if (errors):
+                self.errors.setdefault(name, []).extend(errors)
         if (self.errors):
             raise self.form
         self.validate(self.data)
+        if (self.errors):
+            raise self.form
+    
+    def _save(self):
+        try:
+            return self.save(self.data)
+        except (validators.ValidationError, validators.CriticalValidationError), e:
+            name = "Some field"
+            self.errors.setdefault(name, []).extend(e.messages)
+            raise self.form
     
     ### Default Properties ###
@@ -164 +181 @@
     fields = ()
 
-### Manipulator factories ###
+### Manipulator Factories / Helpers ###
 def create_manipulator(model_cls):
-    "Factory, making a CreateManipulator for a specified model class"
-    
     class CreateManipulator(Manipulator):
-        def __init__(self, request):
-            self.fields = model_cls._meta.create_fields
-            self.process(request.POST)
-            
-        def save(self):
-            self.update(model_cls(), data)
-            
+        def __init__(self):
+            self.fields = forms.generate_fields(model_cls)
+        
+        def save(self, data):
+            return create(Poll, data)
     return CreateManipulator
-   
-def update_manipulator(model_cls):
-    "Factory, making a UpdateManipulator for a specified model class"
-    
-    class UpdateManipulator(Manipulator):
-        def __init__(self, request, object):
+
+def edit_manipulator(model_cls):
+    class EditManipulator(Manipulator):        
+        def __init__(self, object):
+            self.fields = forms.generate_fields(model_cls)
             self.object = object
-            self.process(request.POST)
-            self.fields = model_cls._meta.update_fields
-            
-        def save(self):
-            self.update(self.object, data)
-            
-    return UpdateManipulator
+        
+        def save(self, data):
+            return forms.edit(self.object, data)
+    return EditManipulator
+
+def create(Model, data):
+    """
+    Usefull in the .save of a custom manipulator, this will quickly create an object for you.
+    """
+    m = Model(**data)
+    # In a validation aware model, any problems would arise here.
+    m.save()
+    return m
+    
+def edit(i, data):
+    """
+    Like create() above, this will update an object for you.
+    """
+    i.__dict__.update(data)
+    # Also validation errors would arise here.
+    i.save()
+    return i
 
 ### Attach to classes ###
-Article.CreateManipulator = create_manipulator(Article)
-Article.UpdateManipulator = update_manipulator(Article)
+Poll.CreateManipulator = create_manipulator(Poll)
+Poll.EditManipulator = edit_manipulator(Poll)
 
 ### Custom Manipulator ###
 class CustomManipulator(Manipulator):
     def __init__(self, request):
-        self.fields = (
-            SlugField("slug", attributes={'class': 'slug'}),
-            TextField("title", label="Headline", maxlength=60, attributes={'class': 'title'}),
-            LargeTextField("body", label="Story", attributes={'class': 'body'}),
-            DateTimeField("pub_date", label="This article will publish on this date"),
-        )
-        self.process(request.POST)
+        self.fields = generate_fields(Poll)   # Generate fields creates default fields for a Model
+
+        # Fields have an "attributes" attribute, that adds itself to the tag that is created for it.
+        # Here, we change our class to "vPopupDateField" so that a javascript function will know to
+        # add a Date popup window for when the field gets focus.
+        self.fields['pub_date'].attributes = {'class': 'vPopupDateField'}
     
     def save(self):
         # do something with the data...
         pass
-        
+
+### Custom views ###
+def create_poll(request):
+    try:
+        m = Poll.CreateManipulator()
+        poll = m.process(request)
+        return HttpResponseRedirect('/polls/%d/' % poll.id)
+    except Form, form:
+        return render_to_response('polls/create.html', {'form': form})
+            
+def update_poll(request, id):
+    poll = get_object_or_404(Poll, pk=id)
+    try:
+        m = Poll.EditManipulator(request, poll)
+        m.process(request)
+        return HttpResponseRedirect('/polls/%d/' % poll.id)
+    except Form, form:
+        return render_to_response('polls/update.html', {'form': form, 'poll': poll})
+
 ### Template Tag ###
-{% render-form form %}
-# or
-{% render-form-row form.slug %}
-# or ... etc.
+#
+# Forms should be renderable with a simple tag, that plops a form down for the user:
+#
+# <form action='.' method='post'>
+#    {% render-form form %}
+#    <input type='submit' value='Create Poll'/>
+# </form>
+#
+# or {% render-form-row form.slug %} could be used to create just a row.  Many more options exist.
+# 
 
 ### Generic Views ###
@@ -229 +279 @@
     def create_func(request):
         try:
-            m = model.CreateManipulator(request)
-            object = m.save()
+            m = model.CreateManipulator()
+            object = m.process(request)
             if hasattr(object, 'get_update_url'):
                 return HttpResponseRedirect(object.get_update_url())
@@ -239 +289 @@
     return create_func
     
-def update_view(model, template=None):
+def update_view(model, template=None, pk=None):
     """
     Generic update view.  Redirects to object.get_absolute_url() when it's done.
@@ -250 +300 @@
         object = get_object_or_404(model, pk=pk)
         try:
-            m = model.UpdateManipulator(request)
-            m.save()
+            m = model.EditManipulator(object)
+            m.process(request)
             return HttpResponseRedirect(object.get_absolute_url())
         except Form, form:
@@ -257 +307 @@
     return update_func   
 
-### urls.py usage ###
+### urls.py generic usage ###
 from app.models import Article
-('^articles/create/%d/$', 'django.views.generic.create_update.create_view', {'model':Article})
-('^articles/update/$',      'django.views.generic.create_update.update_view', {'model':Article})
-
-### Custom views ###
-def create_article(request):
-    try:
-        m = Article.CreateManipulator(request)
-        article = m.save()
-        return HttpResponseRedirect('/articles/update/%d/' % article.id)
-    except Form, form:
-        return render_to_response('articles/create.html', {'form': form})
-            
-def update_article(request, id):
-    article = get_object_or_404(Article, pk=id)
-    try:
-        m = Article.UpdateManipulator(request, article)
-        m.save()
-        return HttpResponseRedirect('/articles/%d/' % article.id)
-    except Form, form:
-        return render_to_response('articles/update.html', {'form': form, 'object': object})
+('^polls/create/%d/$', 'django.views.generic.create_update.create_view', {'model':Poll})
+('^polls/update/$',    'django.views.generic.create_update.update_view', {'model':Poll})
+
 }}}
 
+== Benefits ==
+The benefits of this system include:
+ * Custom form views become very simple, and intuitive.
+ * Validation aware models are harnessed in this system.
+ * Custom Manipulators could be defined in the model itself, which hightens the sense of everything in one place.  Likewise, it can be seperated out if it's too much code in one spot.
+ * Defining Custom Manipulators allows one greater control of how the Admin deals with objects.  Having a field automatically update with the author's User object would be a snap.  Also, some options could move from the {{{class Admin:}}} into the Custom Manipulator, which would tighten things up a great deal.
+ * Making your own Admin app now becomes a lot easier.  People often want to be able to simply plop a form down, and this gives them that ability.
+ * Because the form is raised, like an exception, it allows the writer to assume the data is correct the whole way through.  But when there is a validation error, it is handled easily.
+
 == Compatibility ==
-There would be some changes needed in some other django code for all of this to work out right:
- * The '''FormWrapper''' class would be destroyed, I believe, and would be supplanted by '''Form'''.
- * Form fields would alter somewhat, most of it would be cosmetic (e.g. changing "html2python" to "to_python" and adding a "label" and "attributes" keyword arguments in the constructor)
- * Models would gain an "update" function that took a dictionary, applied it to the properties, and then validated.
- * Meta in the Models would gain a "update_fields" and "create_fields" attribute.  Here you could define the fields used for your model's default Manipulators.
+There would be many changes needed in some other django code for all of this to work out right:
+ * The '''FormWrapper''' class would be destroyed, and would be supplanted by the easier '''Form'''.
+ * Form fields would be altered, both cosmetically "html2python" -> "to_python", and functionally for optimization / simplicity
+ * Models would have to gain the validation awareness that we've been talking about.
+ * The Model metaclass would need to create default Create and Edit manipulators if they weren't supplied (this would be very easily done).