Merge pull request #155 from wengole/master

Add kwargs support for item() function.

.gitignore

@@ -4,3 +4,4 @@
 .idea
 .tox
 django_sitetree.egg-info
+docs/build

docs/source/apps.rst

@@ -16,24 +16,29 @@ Let's suppose you have `books` application and want do define a sitetree for it.
 
 .. code-block:: python
 
-      from sitetree.utils import tree, item
-
-      # Be sure you defined `sitetrees` in your module.
-      sitetrees = (
-          # Define a tree with `tree` function.
-          tree('books', items=[
-              # Then define items and their children with `item` function.
-              item('Books', 'books-listing', children=[
-                  item('Book named "{{ book.title }}"', 'books-details', in_menu=False, in_sitetree=False),
-                  item('Add a book', 'books-add'),
-                  item('Edit "{{ book.title }}"', 'books-edit', in_menu=False, in_sitetree=False)
-              ])
-          ]),
-          # ... You can define more than one tree for your app.
-      )
-
-
-  Please consider `tree` and `item` signatures for possible options.
+    from sitetree.utils import tree, item
+
+    # Be sure you defined `sitetrees` in your module.
+    sitetrees = (
+      # Define a tree with `tree` function.
+      tree('books', items=[
+          # Then define items and their children with `item` function.
+          item('Books', 'books-listing', children=[
+              item('Book named "{{ book.title }}"', 'books-details', in_menu=False, in_sitetree=False),
+              item('Add a book', 'books-add'),
+              item('Edit "{{ book.title }}"', 'books-edit', in_menu=False, in_sitetree=False)
+          ])
+      ]),
+      # ... You can define more than one tree for your app.
+    )
+
+
+Please see `tree` and `item` signatures for possible options.
+
+.. note::
+
+    If you added extra fields to the Tree and TreeItem models,
+    then you can specify their values when instantiating `item` see :ref:`custom-model-sitetree`
 
 
 Export sitetree to DB

docs/source/models.rst

@@ -31,7 +31,7 @@ and `TreeItemBase` classes respectively:
 
     class MyTreeItem(TreeItemBase):
         """And that's a tree item model with additional `css_class` field."""
-        css_class = models.IntegerField('Tree item CSS class', default=50)
+        css_class = models.CharField('Tree item CSS class', max_length=50)
 
 
 
@@ -57,7 +57,40 @@ to instruct Django to use them for your project instead of built-in ones:
     See :ref:`Overriding SiteTree Admin representation <admin-ext>` for more information.
 
 
+.. _custom-model-sitetree:
 
+Sitetree definition with custom models
+--------------------------------------
+
+Given the example model given above, you can now use the extra fields when defining a sitetree programmatically:
+
+.. code-block:: python
+
+    from sitetree.utils import tree, item
+
+    # Be sure you defined `sitetrees` in your module.
+    sitetrees = (
+      # Define a tree with `tree` function.
+      tree('books', items=[
+          # Then define items and their children with `item` function.
+          item('Books', 'books-listing', children=[
+              item('Book named "{{ book.title }}"',
+                   'books-details',
+                   in_menu=False,
+                   in_sitetree=False,
+                   css_class='book-detail'),
+              item('Add a book',
+                   'books-add',
+                   css_class='book-add'),
+              item('Edit "{{ book.title }}"',
+                   'books-edit',
+                   in_menu=False,
+                   in_sitetree=False,
+                   css_class='book-edit')
+          ])
+      ]),
+      # ... You can define more than one tree for your app.
+    )
 
 .. _models_referencing:
 

sitetree/tests.py

@@ -606,8 +606,9 @@ def basic_test(self, new_style=False, reset_cache=False):
         trees = (
             compose_dynamic_tree((
                 tree('dynamic_main_root', items=(
-                    item('dynamic_main_root_1', 'dynamic_main_root_1_url', url_as_pattern=False),
-                    item('dynamic_main_root_2', 'dynamic_main_root_2_url', url_as_pattern=False),
+                    # Testing kwargs parameter for item(). Needs a full proper test
+                    item('dynamic_main_root_1', 'dynamic_main_root_1_url', url_as_pattern=False, sort_order=2),
+                    item('dynamic_main_root_2', 'dynamic_main_root_2_url', url_as_pattern=False, sort_order=1),
                 )),
             ), target_tree_alias='main'),
             compose_dynamic_tree((

sitetree/utils.py

@@ -49,7 +49,7 @@ def traverse(items):
 def item(title, url, children=None, url_as_pattern=True, hint='', alias='', description='',
          in_menu=True, in_breadcrumbs=True, in_sitetree=True,
          access_loggedin=False, access_guest=False,
-         access_by_perms=None, perms_mode_all=True):
+         access_by_perms=None, perms_mode_all=True, **kwargs):
     """Dynamically creates and returns a sitetree item object.
 
     :param str title:
@@ -73,7 +73,7 @@ def item(title, url, children=None, url_as_pattern=True, hint='', alias='', desc
     item_obj = get_tree_item_model()(title=title, url=url, urlaspattern=url_as_pattern,
                                    hint=hint, alias=alias, description=description, inmenu=in_menu,
                                    insitetree=in_sitetree, inbreadcrumbs=in_breadcrumbs,
-                                   access_loggedin=access_loggedin, access_guest=access_guest)
+                                   access_loggedin=access_loggedin, access_guest=access_guest, **kwargs)
 
     item_obj.id = generate_id_for(item_obj)
     item_obj.is_dynamic = True