jQuery plugin: Django Dynamic Formset

Several months ago, I posted this snippet over at Django Snippets. Since then, I’ve used it a few times, and eventually made it into a jQuery plugin. I always intended to release the plugin, but didn’t have time to write some decent documentation, and do a demo project.

After reading the comments on the snippet, I finally decided to bite the bullet this weekend, so here it is. To use it, download one of the releases (I’d recommend the one with the demo project), unzip it, and check out README.txt and INSTALL.txt.

Usage

I’ll assume you’ve already created your formsets. You can create

formsets using any of the provided methods: both regular formsets

(created with the “formset_factory“) and inline formsets

(created with the “inlineformset_factory“) are supported.

I’ll assume you’ve already created your formsets. You can create formsets using any of the provided methods: both regular formsets (created with the “formset_factory“) and inline formsets (created with the “inlineformset_factory“) are supported.

1. First, copy jquery.formset.js to your MEDIA_ROOT; don’t forget to include the jQuery library too!
2. Include a reference to the script in your template; again, don’t forget to reference the jQuery library (before the reference to the script).
3. Render the formset as you normally would — I usually use a table but you can use DIVs, Ps or whatever you desire. Let’s use the example markup below:

   <form id="myForm" method="post" action="">
     <table border="0" cellpadding="0" cellspacing="0">
       <tbody>
       {% for form in formset.forms %}
         <tr>
           <td>{{ form.field1 }}</td>
           <td>{{ form.field2 }}</td>
           <td>{{ form.field3 }}</td>
         </tr>
       {% endfor %}
       </tbody>
     </table>
     {{ formset.management_form }}
   </form>
   

4. Add the following script to your template (before the closing BODY tag, or in your HEAD, below the reference to jquery.formset.js):

   <script type="text/javascript">
     $(function() {
       $('#myForm tbody tr').formset({
         prefix: '{{ formset.prefix }}'
       });
     })
   </script>
   

   Notice how our jQuery selector targets the container for each form? We could have assigned a class to each TR and used that instead:

     $('.form-container-class').formset(...);
   

   Either way is fine, really :)

5. That’s it. Fini. Save your template and navigate to the appropriate view in your application, and you should see an “add another” link. Clicking on it should add another instance of your form to the page. You can remove instances by clicking the “remove” link; if there’s only one form in the formset, the remove link isn’t shown.

License

This plugin is released under the New BSD License – use it as you wish.

Quick Download

For the impatient, you can download the releases here:

• Source code, minified (using jsmin) version and docs
• Source code, minified version, docs and demo Django project

You might also want to check out the Google Code project.

If you find this useful, feel free to leave a nice comment saying so :) If you find bugs, want to submit a patch, or have an idea for a cool enhancement, submit them to the issue tracker.

Update (3oth Nov, 2009)

Version 1.1 is now available — I’ve updated the download links above to point to it. For details of the changes in 1.1, see the accompanying blog post.