Metadata-Version: 1.1
Name: django-dcolumns
Version: 0.3.0
Summary: An app to give any Django database model the ability to dynamically add fields.
Home-page: https://github.com/cnobile2012/dcolumn
Author: Carl J. Nobile
Author-email: carl.nobile@gmail.com
License: MIT
Description: Django Tool to Create Dynamic Fields
        ====================================
        
        *** WARNING *** Version 0.3.0 breaks the previous two versions, but is easy to
        fix. You will need to reassign most 'Value Types' in the Dynamic Column model
        records in the admin. Until version 1.0.0 is reached this may happen again.
        
        Have you ever wanted to add new fields to a model, but you didn't have time to
        make the code and model changes required? Well this may be a solution to that
        often occurring scenario.
        
        It is highly recommended that after doing a pip install to clone the git
        repository as many examples exist there that will not be in a pip install.
        Examples of CSS used with the template tags mentioned below and a demo
        PostgreSQL database containing test data is also available. The repository can
        be found at: https://github.com/cnobile2012/dcolumn
        
        Basic Installation
        ------------------
        
         1. Add 'dcolumn' to your INSTALLED_APPS settings:
        
                INSTALLED_APPS = (
                    ...
                    'dcolumn.dcolumns',
                    )
        
         2. Add the following code stanza to the settings file. The `COLLECTIONS` key
            points to key value pairs where the key is the model name and the value
            is a unique name given to a collection set. This collection set is kept
            in the model named `ColumnCollection`. As of now there is only a single
            asynchronous call to the internal API. It is by default only accessed by
            logged in users. You can change this behavior by setting
            `INACTIVATE_API_AUTH` to `True`.
        
                DYNAMIC_COLUMNS = {
                    # The default key/value pairs for the ColumnCollection object to use
                    # for all tables that use dcolumn. The key is the table name and the
                    # value is the name used in the ColumnCollection record.
                    u'COLLECTIONS': {
                        u'Book': u'Book Current',
                        u'Author': u'Author Current',
                        u'Publisher': u'Publisher Current',
                        u'Promotion': u'Promotion Current',
                        },
                    # To allow anybody to access the API set to True.
                    u'INACTIVATE_API_AUTH': False,
                    }
        
         3. If you want authorization on the API you will need to set the standard
            Django setting 'LOGIN_URL' to something reasonable.
        
                # Change the URL below to your login path.
                LOGIN_URL = u"/admin/"
        
         4. There are two methods to define page location of each new field that you
            enter into the system. The 1st method is to just pass a tuple of each CSS
            class. They are enumerated starting with 0 (zero). They would be
            referenced as `css.0`, `css.1`, etc. The 2nd method is to pass a tuple of
            tuples with the first variable as the key and the second variable as the
            value. They would be reference as `css.top`, `css.center`, etc.
        
                # First method
                dcolumn_manager.register_css_containers(
                       (u'top-container', u'center-container', u'bottom-container')
                )
        
                # Second method
                dcolumn_manager.register_css_containers(
                       ((u'top', u'top-container'),
                        (u'center', u'center-container'),
                        (u'bottom', u'bottom-container'))
                )
        
         5. The models need to subclass the `CollectionBase` model base class from
            dcolumn. The model manager needs to subclass `StatusModelManagerMixin` and
            also needs to implement two methods named `dynamic_column` and
            `get_choice_map`. See the example code.
        
         6. The `CollectionBaseManagerBase` manager base class from dcolumn should also
            be sub-classed to pick up a few convenience methods. This is not mandatory.
        
         7. Any forms used with a dynamic column model will need to subclass
            `CollectionFormMixin`. You do not need to subclass `forms.ModelForm`, this
            is done for you already by `CollectionFormMixin`.
        
         8. Any views need to subclass `CollectionCreateUpdateViewMixin` which must be
            before the class-based view that you will use. Once again see the example
            code.
        
        Do Not's
        --------
        Once you have registered the choices/models with
        `dcolumn_manager.register_choice()` do not change it, as the numeric value is
        stored in the `DynamicColumn` table. So obviously if you really really really
        need to change it you can, but you must manually modify the `Relation` in all
        the affected rows in the `DynamicColumn` table.
        
        You will see that this is all rather simple and you'll need to write very
        little code to support DynamicColumns.
        
        If you need to hardcode any of the slugs elsewhere in your code then you
        definitely need to set the 'Preferred Slug' field to your desired slug. If you
        do not do this the slug will track any changes made to the 'Name' fields
        breaking your code. The only caveat is that the slug will now track the
        'Preferred Slug' field, so don't change it after your code is using the slug
        value. I've put this out of the way and hidden in the admin 'Status' section
        of the 'Dynamic Columns' entries.
        
        
        API Details
        -----------
        
        ### Models and Managers
        
        #### DynamicColumnManager
         1. get_fk_slugs
           * Takes no arguments
           * Returns all dynamic column slugs that have a `value_type` of `CHOICE`.
             These include all Django models and the Choice models.
        
        #### DynamicColumn
         1. get_choice_relation_object_and_field
           * Takes no arguments
           * Returns the model object and the field used in the HTML select option
             text value.
        
        #### ColumnCollectionManager
         1. get_column_collection `method`
           * `name` positional argument and is a collection name as defined in the
             DYNAMIC_COLUMNS.COLLECTIONS dictionary.
           * `unassigned` keyword argument defaults to `False`, if `True` gets the
             items that are assigned to the collection name plus any unassigned items.
           * Returns a column collection.
         2. serialize_columns `method`
           * `name` positional argument and is a collection name as defined in the
             DYNAMIC_COLUMNS.COLLECTIONS dictionary.
           * `obj` keyword argument defaults to `None` otherwise an instance of a
             dynamic column enabled model.
           * Returns a serialized version of the dynamic columns.
         3. get_active_relation_items `method`
           * `name` positional argument and is a collection name as defined in the
             DYNAMIC_COLUMNS.COLLECTIONS dictionary.
           * Returns a list of dynamic columns that have a `value_type` of CHOICE.
         4. get_collection_choices `method`
           * `name` positional argument and is a collection name as defined in the
             DYNAMIC_COLUMNS.COLLECTIONS dictionary.
           * `use_pk` keyword argument defaults to `False`, if `True` returns the pk
             instead of the slug as the HTML select option value.
           * Returns a list of tuples that can be used for HTML select options.
        
        #### ColumnCollection
        There are no user methods on the `ColumnCollection` model at this time.
        
        #### CollectionBaseManagerBase
         1. get_all_slugs `method`
           * Takes no arguments
           * Returns a list of all slugs
         2. get_all_fields `method`
           * Takes no arguments
           * Returns a list of all model fields.
         3. get_all_fields_and_slugs `method`
           * Takes no arguments
           * Returns a list of all model fields and slugs.
        
        #### CollectionBase
         1. serialize_key_value_pairs `method`
           * Takes no arguments
           * Returns a dictionary where the key is the pk of a DynamicColumn instance
             and the value of the KeyValue instance associated with the DynamicColumn
             instance.
         2. get_dynamic_column `method`
           * `slug` positional argument, is the slug of any dynamic column object.
           * Returns the DynamicColumn instance relitive to this model instance.
         3. get_key_value_pair `method`
           * `slug` positional argument, is the slug of any dynamic column object.
           * `field` positional argument indicating the field to use in a choice or
              model.
           * Returns the value of the dynamic column.
         4. set_key_value_pair `method`
           * `slug` positional argument, is the slug of any dynamic column object.
           * `value` positional argument, is a value to be set on a keyvalue pair.
           * `field` keyword argument, is the field used to get the value on the object.
           * `force` keyword argument, default is False, do not save empty strings or
             None objects else True save empty strings only.
           * Returns nothing. Sets a value on a keyValue object.
        
        #### KeyValueManager
        There are no user methods on the `KeyValueManager` model manager at this time.
        
        #### KeyValue
        There are no user methods on the `KeyValue` model at this time.
        
        ### DynamicColumnManager
        This is not the model manager mentioned above. The `DynamicColumnManager` holds
        all the relevant states of the system and should be the first place you come
        when you need to know something about the system.
        
         1. register_choice `method`
           * `choice` positional argument and is a CHOICE type object either a Django
             model or a choice model.
           * `relation_num` positional argument and is a numeric identifier used as the
             HTML select option value.
           * `field` positional argument and is a string used as the HTML select option
             text value.
         2. choice_relations `property`
           * Takes no arguments
           * Returns a list of choices.
         3. choice_relation_map `property`
           * Takes no arguments
           * Returns a dictionary of choices.
         4. choice_map `property`
           * Takes no arguments
           * Returns a dictionary where the key is the choice model name and the value
             is a tuple of the choice model object and the relevant field name.
         5. register_css_containers `method`
           * `container_list` positional argument and is a list of the CSS classes or
             ids that will determine the location on the page of the various dynamic
             columns.
           * Returns nothing.
         6. css_containers `property`
           * Takes no arguments
           * Returns a list of tuples where the tuple is (num, text)
         7. css_container_map `property`
           * Takes no arguments
           * Returns a dictionary of the CSS containers.
         8. get_collection_name `method`
           * `model_name` positional argument and is the key name used in the
             settings.DYNAMIC_COLUMNS.COLLECTIONS.
           * Returns the `ColumnCollection` instance name.
         9. get_api_auth_state `method`
           * Takes no arguments
           * Returns the value of settings.DYNAMIC_COLUMNS.INACTIVATE_API_AUTH
         10. get_relation_model_field `method`
           * `relation` positional argument and is the value in the `DynamicColumn`
             relation field.
           * Returns the field used in the HTML select option text value.
        
        ### Template Tags
        There are three template tags that can be used. These tags will help with
        displaying the proper type of fields in your templates.
        
        #### auto_display
        The `auto_display` tag displays the dynamic columns in your template as either
        form elements or `span` elements. This tag takes one positional argument and
        three keyword arguments. Please look at the example code for usage.
        
         1. relation `dict`
           * A dictionary representing the meta data for a specific field. This data
             is a single value dict that can be found in the context as `relations`.
         2. prefix `str`
           * Defaults to an empty string, but can be used to put a common prefix on all
             tag id and name attributes. Not often used.
         3. option `(list, tuple) or dict`
           * Used only for choice type fields, but can be passed into the template tag
             for all types--if needed it will be used. The entire `dynamicColumns` from
             the context can be passed in (dict) or just the specific field's data
             `list or tuple`.
         4. display `bool`
           * This keyword argument is either `True` or `False`. `False` is the default
             and generates `input` or `select` tags for form data. If `True` `span`
             tags are generated for detail pages where no forms would generally be used.
        
        #### single_display
        The `single_display` tag displays a single slug based on a `CollectionBase`
        derived model. This tag would often be used in list templates.
        
         1. obj `model instance`
           * A model instance that is derived from `CollectionBase`.
         2. slug `str`
           * The `slug` from a DynamicColumn record.
         3. as `str`
           * A delimiter keyword used to define the next argument.
         4. name `str`
           * The variable name created in the context that will hold the value of the
             slug. ex. If the slug is `first-name` the context variable could be
             `first_name`.
        
        #### combine_contexts
        The `combine_contexts` tag combines two different context variables. This would
        often be used to get the template error from a form for a specific slug. ex.
        The combination of `form.error` and `relation.slug` would give you the error
        for a form `input` element.
        
         1. obj `instance object`
           * Any instance object that has member objects.
         2. variable `variable indicating member object`
           * Reference to any member object on the `obj`.
        
        
        Feel free to contact me at: carl dot nobile at gmail.com
        
Platform: UNKNOWN
Classifier: Environment :: Web Environment
Classifier: Framework :: Django
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 2
Classifier: Programming Language :: Python :: 2.7
Classifier: Topic :: Internet :: WWW/HTTP
Classifier: Topic :: Internet :: WWW/HTTP :: Dynamic Content
