Django Categories v1.1 documentation

# Registering Models

- Table of Contents
- index
  next
  previous

# Registering Models

## Registering models in settings.py

It is nice to not have to modify the code of applications to add a relation to categories. You can therefore do all the registering in `settings.py`. For example:

    CATEGORIES_SETTINGS = {
        'FK_REGISTRY': {
            'app.AModel': 'category',
            'app.MyModel': (
                'primary_category',
                {'name': 'secondary_category', 'related_name': 'mymodel_sec_cat'}, )
        },
        'M2M_REGISTRY': {
            'app.BModel': 'categories',
            'app.MyModel': ('other_categories', 'more_categories', ),
        }
    }

The `FK_REGISTRY` is a dictionary whose keys are the model to which to add the new field(s). The value is a string or tuple of strings or dictionaries specifying the necessary information for each field.

The `M2M_REGISTRY` is a dictionary whose keys are the model to which to add the new field(s). The value is a string or tuple of strings specifying the necessary information for each field.

### Registering one Category field to model

The simplest way is to specify the name of the field, such as:

    CATEGORIES_SETTINGS = {
        'FK_REGISTRY': {
            'app.AModel': 'category'
        }
    }

This is equivalent to adding the following the `AModel` of `app`:

    category = models.ForeignKey(Category)

If you want more control over the new field, you can use a dictionary and pass other `ForeignKey` options. The `name` key is required:

    CATEGORIES_SETTINGS = {
        'FK_REGISTRY': {
            'app.AModel': {'name': 'category', 'related_name': 'amodel_cats'}
        }
    }

This is equivalent to adding the following the `AModel` of `app`:

    category = models.ForeignKey(Category, related_name='amodel_cats')

### Registering two or more Category fields to a Model

When you want more than one relation to `Category`, all but one of the fields must specify a `related_name` to avoid conflicts, like so:

    CATEGORIES_SETTINGS = {
        'FK_REGISTRY': {
            'app.MyModel': (
                'primary_category',
                {'name': 'secondary_category', 'related_name': 'mymodel_sec_cat'}, )
        },

### Registering one or more Many-to-Many Category fields to a Model

    CATEGORIES_SETTINGS = {
        'M2M_REGISTRY': {
            'app.AModel': 'categories',
            'app.MyModel': (
                {'name': 'other_categories', 'related_name': 'other_cats'},
                {'name': 'more_categories', 'related_name': 'more_cats'},
            ),
        }
    }

## Registering a many-to-one relationship

To create a many-to-one relationship (foreign key) between a model and Django Categories, you register your model with the `register_fk` function.

`register_fk`(model, field_name='category', extra_params={}])

  Parameters:

  - model – The Django Model to link to Django Categories
  - field_name – Optional name for the field default: category
  - extra_params – Optional dictionary of extra parameters passed to the `ForeignKey` class.

Example, in your `models.py`:

    import categories
    categories.register_fk(MyModel)

If you want more than one field on a model you have to have some extra arguments:

    import categories
    categories.register_fk(MyModel, 'primary_category')
    categories.register_fk(MyModel, 'secondary_category', {'related_name':'mymodel_sec_cat'})

The `extra_args` allows you to specify the related_name of one of the fields so it doesn’t clash.

## Registering a many-to-many relationship

To create a many-to-many relationship between a model and Django Categories, you register your model with the `register_m2m` function.

`register_m2m`(model, field_name='categories', extra_params={}])

  Parameters:

  - model – The Django Model to link to Django Categories
  - field_name – Optional name for the field default: categories
  - extra_params – Optional dictionary of extra parameters passed to the `ManyToManyField` class.

Example, in your `models.py`:

    import categories
    categories.register_m2m(MyModel)