Updated documentation for 1.0b1

README.rst

@@ -2,6 +2,28 @@ Django Categories grew out of our need to provide a basic hierarchical taxonomy
 
 As a news site, our stories, photos, and other content get divided into "sections" and we wanted all the apps to use the same set of sections. As our needs grew, the Django Categories grew in the functionality it gave to category handling within web pages.
 
+New in 1.0
+==========
+
+**Abstract Base Class for generic hierarchical category models**
+   When you want a multiple types of categories and don't want them all part of the same model, you can now easily create new models by subclassing ``CategoryBase``. You can also add additional metadata as necessary.
+
+   Your model's can subclass ``CategoryBaseAdminForm`` and ``CategoryBaseAdmin`` to get the hierarchical management in the admin.
+
+   See the docs for more information.
+
+**Increased the default caching time on views**
+   The default setting for ``CACHE_VIEW_LENGTH`` was ``0``, which means it would tell the browser to *never* cache the page. It is now ``600``, which is the default for `CACHE_MIDDLEWARE_SECONDS <https://docs.djangoproject.com/en/1.3/ref/settings/#cache-middleware-seconds>`_
+
+**Updated for use with Django-MPTT 0.5**
+   Just a few tweaks.
+
+**Initial compatibility with Django 1.4**
+   More is coming, but at least it works.
+
+**Slug transliteration for non-ASCII characters**
+   A new setting, ``SLUG_TRANSLITERATOR``, allows you to specify a function for converting the non-ASCII characters to ASCII characters before the slugification. Works great with `Unidecode <http://pypi.python.org/pypi/Unidecode>`_.
+
 Updated in 0.8.8
 ================
 

doc_src/_static/default.css

@@ -532,21 +532,34 @@ pre {
     padding: 10px;
 }
 
+td.linenos {
+    width: 2em;
+}
+
 td.linenos pre {
     padding: 5px 0px;
     border: 0;
     background-color: transparent;
     color: #aaa;
 }
 
+td.code {
+
+}
+
 table.highlighttable {
     margin-left: 0.5em;
+    width: 100%;
 }
 
 table.highlighttable td {
     padding: 0 0.5em 0 0.5em;
 }
-
+table.highlighttable td.linenos {
+    text-align: right;
+    width: 1.5em;
+    padding-right: 0;
+}
 tt {
 	font-family:"Bitstream Vera Sans Mono",Monaco,"Lucida Console",Courier,Consolas,monospace;
 

doc_src/code_examples/custom_categories1.py

@@ -0,0 +1,9 @@
+from categories.models import CategoryBase
+
+class SimpleCategory(CategoryBase):
+    """
+    A simple of catgorizing example
+    """
+
+    class Meta:
+        verbose_name_plural = 'simple categories'

doc_src/code_examples/custom_categories2.py

@@ -0,0 +1,14 @@
+from django.contrib import admin
+
+from categories.admin import CategoryBaseAdmin, CategoryBaseAdminForm
+
+from .models import SimpleCategory
+
+class SimpleCategoryAdminForm(CategoryBaseAdminForm):
+    class Meta:
+        model = SimpleCategory
+
+class SimpleCategoryAdmin(CategoryBaseAdmin):
+    form = SimpleCategoryAdminForm
+
+admin.site.register(SimpleCategory, SimpleCategoryAdmin)

doc_src/code_examples/custom_categories3.py

@@ -0,0 +1,29 @@
+class Category(CategoryBase):
+    thumbnail = models.FileField(
+        upload_to=THUMBNAIL_UPLOAD_PATH, 
+        null=True, blank=True,
+        storage=STORAGE(),)
+    thumbnail_width = models.IntegerField(blank=True, null=True)
+    thumbnail_height = models.IntegerField(blank=True, null=True)
+    order = models.IntegerField(default=0)
+    alternate_title = models.CharField(
+        blank=True,
+        default="",
+        max_length=100,
+        help_text="An alternative title to use on pages with this category.")
+    alternate_url = models.CharField(
+        blank=True, 
+        max_length=200, 
+        help_text="An alternative URL to use instead of the one derived from "
+                  "the category hierarchy.")
+    description = models.TextField(blank=True, null=True)
+    meta_keywords = models.CharField(
+        blank=True,
+        default="",
+        max_length=255,
+        help_text="Comma-separated keywords for search engines.")
+    meta_extra = models.TextField(
+        blank=True,
+        default="",
+        help_text="(Advanced) Any additional HTML to be placed verbatim "
+                  "in the <head>")

doc_src/code_examples/custom_categories4.py

@@ -0,0 +1,15 @@
+def save(self, *args, **kwargs):
+    if self.thumbnail:
+        from django.core.files.images import get_image_dimensions
+        import django
+        if django.VERSION[1] < 2:
+            width, height = get_image_dimensions(self.thumbnail.file)
+        else:
+            width, height = get_image_dimensions(self.thumbnail.file, close=True)
+    else:
+        width, height = None, None
+
+    self.thumbnail_width = width
+    self.thumbnail_height = height
+
+    super(Category, self).save(*args, **kwargs)

doc_src/code_examples/custom_categories5.py

@@ -0,0 +1,5 @@
+class Meta(CategoryBase.Meta):
+    verbose_name_plural = 'categories'
+
+class MPTTMeta:
+    order_insertion_by = ('order', 'name')

doc_src/code_examples/custom_categories6.py

@@ -0,0 +1,9 @@
+class CategoryAdminForm(CategoryBaseAdminForm):
+    class Meta:
+        model = Category
+
+    def clean_alternate_title(self):
+        if self.instance is None or not self.cleaned_data['alternate_title']:
+            return self.cleaned_data['name']
+        else:
+            return self.cleaned_data['alternate_title']

doc_src/code_examples/custom_categories7.py

@@ -0,0 +1,17 @@
+class CategoryAdmin(CategoryBaseAdmin):
+    form = CategoryAdminForm
+    list_display = ('name', 'alternate_title', 'active')
+    fieldsets = (
+        (None, {
+            'fields': ('parent', 'name', 'thumbnail', 'active')
+        }),
+        ('Meta Data', {
+            'fields': ('alternate_title', 'alternate_url', 'description', 
+                        'meta_keywords', 'meta_extra'),
+            'classes': ('collapse',),
+        }),
+        ('Advanced', {
+            'fields': ('order', 'slug'),
+            'classes': ('collapse',),
+        }),
+    )

doc_src/custom_categories.rst

@@ -0,0 +1,58 @@
+.. _creating_custom_categories:
+
+==========================
+Creating Custom Categories
+==========================
+
+Django Categories isn't just for using a single category model. It allows you to create your own custom category-like models with as little or much customization as you need.
+
+Name only
+=========
+
+For many cases, you want a simple user-managed lookup table. You can do this with just a little bit of code. The resulting model will include name, slug and active fields and a hierarchical admin.
+
+#. Create a model that subclasses :py:class:`CategoryBase`
+
+   .. literalinclude:: code_examples/custom_categories1.py
+      :linenos:
+
+#. For the Django admin, create a subclass of :py:class:`CategoryBaseAdminForm`. Create an internal class called :py:class:`Meta` and assign the attribute ``model`` to your model (see line 9 in the example).
+
+   .. literalinclude:: code_examples/custom_categories2.py
+      :linenos:
+
+#. Create a subclass of CategoryBaseAdmin and assign ``form`` attribute the class created above (see line 12 in the above example).
+
+#. Register your model and custom model admin class.
+
+Name and other data
+===================
+
+Sometimes you need more functionality, such as extra metadata and custom functions. The :py:class:`Category` model in this package does this.
+
+#. Create a model that subclasses :py:class:`CategoryBase` as above.
+
+#. Add new fields to the model. The :py:class:`Category` model adds these extra fields.
+
+   .. literalinclude:: code_examples/custom_categories3.py
+      :linenos:
+
+#. Add new methods to the model. For example, the :py:class:`Category` model adds several new methods, including overriding the :py:meth:`save` method.
+
+   .. literalinclude:: code_examples/custom_categories4.py
+      :linenos:
+
+#. Alter :py:class:`Meta` or :py:class:`MPTTMeta` class. Either of these inner classes can be overridden, however your :py:class:`Meta` class should inherit :py:class:`CategoryBase.Meta`. Options for :py:class:`Meta` are in the `Django-MPTT docs <http://readthedocs.org/docs/django-mptt/en/latest/models.html#model-options>`_.
+
+   .. literalinclude:: code_examples/custom_categories5.py
+      :linenos:
+
+#. For the admin, you must create a form that subclasses :py:class:`CategoryBaseAdminForm` and at least sets the ``Meta.model`` attribute. You can also alter the form fields and cleaning methods, as :py:class:`Category` does.
+
+   .. literalinclude:: code_examples/custom_categories6.py
+      :linenos:
+
+#. Next you must subclass :py:class:`CategoryBaseAdmin` and assign the ``form`` attribute the form class created above. You can alter any other attributes as necessary.
+
+   .. literalinclude:: code_examples/custom_categories7.py
+      :linenos:

doc_src/getting_started.rst

@@ -4,7 +4,7 @@ Getting Started
 
 You can use Django Categories in two ways:
 
-1. As storage for one tree of categories, e.g.::
+1. As storage for one tree of categories, using the :py:class:`Category` model::
 
 	Top Category 1
 	  Subcategory 1-1
@@ -13,24 +13,29 @@ You can use Django Categories in two ways:
 	Top Category 2
 	  Subcategory 2-1
 
-2. As a storage of several trees of categories, e.g.::
-
-	Model 1
-	  Category 1
-	    Subcategory 1-1
-	      Subcategory 1-2
-	        subcategory 1-2-1
-	  Category 2
-	    Subcategory 2-1
-	Model 2
-	  Category 3
-	    Subcategory 3-1
-	      Subcategory 3-2
-	        subcategory 3-2-1
-	  Category 4
-	    Subcategory 4-1
-
-You can't do it as both at the same time, though.
+2. As the basis for several custom categories (see :ref:`creating_custom_categories`), e.g. a **MusicGenre** model
+
+   ::
+   
+   	MusicGenre 1
+   	  MusicSubGenre 1-1
+   	  MusicSubGenre 1-2
+   	    MusicSubGenre 1-2-1
+   	MusicGenre 2
+   	  MusicSubGenre 2-1
+   
+   and a **Subject** model
+
+   ::
+   
+   	Subject 1
+   	  Discipline 1-1
+   	  Discipline 1-2
+   	    SubDiscipline 1-2-1
+   	Subject 2
+   	  Discipline 2-1
+
+
 
 Connecting your model with Django-Categories
 ============================================
@@ -42,7 +47,7 @@ For 3rd-party apps or even your own apps that you don't wish to add Django-Categ
 .. _hard_coded_connection:
 
 Hard Coded Connection
-*********************
+---------------------
 
 Hard coded connections are done in the exact same way you handle any other foreign key or many-to-many relations to a model.
 
@@ -60,10 +65,10 @@ Don't forget to add the field or fields to your ``ModelAdmin`` class as well.
 .. _lazy_connection:
 
 Lazy Connection
-***************
+---------------
 
 Lazy connections are done through configuring Django Categories in the project's ``settings.py`` file. When the project starts up, the configured fields are dynamically added to the configured models and admin. 
 
 If you do this before you have created the database (before you ran ``manage.py syncdb``), the fields will also be in the tables. If you do this after you have already created all the tables, you can run ``manage.py add_category_fields`` to create the fields (this requires Django South to be installed).
 
-You add a many-to-one or many-to-many relationship with Django Categories using the ``CATEGORIES_SETTINGS['FK_REGISTRY']`` and ``CATEGORIES_SETTINGS['M2M_REGISTRY']`` settings respectively. For more information see :ref:`registering_models`\ .
+You add a many-to-one or many-to-many relationship with Django Categories using the :ref:`FK_REGISTRY` and :ref:`M2M_REGISTRY` settings respectively. For more information see :ref:`registering_models`\ .

doc_src/index.rst

@@ -2,7 +2,35 @@
 Django Categories v |version|
 =============================
 
-Contents:
+Django Categories grew out of our need to provide a basic hierarchical taxonomy management system that multiple applications could use independently or in concert.
+
+As a news site, our stories, photos, and other content get divided into "sections" and we wanted all the apps to use the same set of sections. As our needs grew, the Django Categories grew in the functionality it gave to category handling within web pages.
+
+New in 1.0
+==========
+
+**Abstract Base Class for generic hierarchical category models**
+   When you want a multiple types of categories and don't want them all part of the same model, you can now easily create new models by subclassing ``CategoryBase``. You can also add additional metadata as necessary.
+
+   Your model's can subclass ``CategoryBaseAdminForm`` and ``CategoryBaseAdmin`` to get the hierarchical management in the admin.
+
+   See the docs for more information.
+
+**Increased the default caching time on views**
+   The default setting for ``CACHE_VIEW_LENGTH`` was ``0``, which means it would tell the browser to *never* cache the page. It is now ``600``, which is the default for `CACHE_MIDDLEWARE_SECONDS <https://docs.djangoproject.com/en/1.3/ref/settings/#cache-middleware-seconds>`_
+
+**Updated for use with Django-MPTT 0.5**
+   Just a few tweaks.
+
+**Initial compatibility with Django 1.4**
+   More is coming, but at least it works.
+
+**Slug transliteration for non-ASCII characters**
+   A new setting, ``SLUG_TRANSLITERATOR``, allows you to specify a function for converting the non-ASCII characters to ASCII characters before the slugification. Works great with `Unidecode <http://pypi.python.org/pypi/Unidecode>`_.
+
+
+Contents
+========
 
 .. toctree::
    :maxdepth: 2
@@ -13,6 +41,7 @@ Contents:
    usage
    registering_models
    adding_the_fields
+   custom_categories
    reference/index
 
 Indices and tables

doc_src/installation.rst

@@ -2,11 +2,14 @@
 Installation
 ============
 
+To use the Category model
+=========================
+
 1. Install django-categories::
 
     pip install django-categories
 
-2. Add ``"categories"`` and ``"editor"`` to your ``INSTALLED_APPS`` list in your project's ``settings.py`` file.
+2. Add ``"categories"`` and ``"categories.editor"`` to your ``INSTALLED_APPS`` list in your project's ``settings.py`` file.
 
    .. code-block:: python
 
@@ -17,3 +20,24 @@ Installation
        ]
 
 3. Run ``./manage.py syncdb`` (or ``./manage.py migrate categories`` if you are using `South <http://south.aeracode.org/>`_)
+
+
+To only subclass CategoryBase
+=============================
+
+If you are going to create your own models using :py:class:`CategoryBase`, (see :ref:`creating_custom_categories`) you'll need a few different steps.
+
+1. Install django-categories::
+
+    pip install django-categories
+
+2. Add ``"categories.editor"`` to your ``INSTALLED_APPS`` list in your project's ``settings.py`` file.
+
+   .. code-block:: python
+
+       INSTALLED_APPS = [
+           # ...
+           "categories.editor",
+       ]
+
+3. Create your own models.