History: Category Admin

            The Tiki Category feature allows to manage and classify content being created on the fly, by different groups with different access permissions, and make navigation and indexing much easier.

^This page ((needs review))^
!Categories Admin

Category can be used together with ((groups)) to hide objects/pages from specific groups of users, creating "private" areas that may even look different from the rest of the site. 

Are categories the right tool for you? See: ((How to organize your content))

__To access__: Click the __Categories__ icon {icon name="sitemap" rotate="270" title="Image may vary depending on icon set in use."} on the ((Admin Panels|Admin Panel)) %%% or Access __http://example.org/tiki-admin.php?page=categories__ 

!!Creating categories and sub-categories
You can reach administration of categories through "Admin -> Categories" at the main menu.

^::{picture file=img/wiki_up//Categories-ADMIN-001.png}::^

Then, you can add a new category at top level (for instance: "''Status''").

^::{img src="img/wiki_up/categories_admin_02.png" }::^

Note that you have "__Assign permissions automatically: ''(recommended for best performance)''__". Leave it toggled on, for the time being, if you are not sure. 

If you click on a pre-existent category (for instance, in the newly created ''Status'' category), you'll be ready to add subcategories to it.

You should see the path to the category you are in, like "__Current Category: ===Top=== :: ===Status===__", in this case:
^::{img src="img/wiki_up/categories_admin_04.png" }::^ 

Then, you can add a new category (for instance: "''1. To Do''"), as a child of the parent category ("''Status''") selected.

^::{img src="img/wiki_up/categories_admin_03.png" }::^

Once created, if you click on the the "__>>>__" at the right of "Status" category, you could see the child categories below:

^::{img src="img/wiki_up/categories_admin_05.png" } ::^

After some work, you could have something like:

^::{img src="img/wiki_up/categories_admin_06.png" }::^

!!Creating categories in batch from CSV files

^Also see attached MS Word and PDF files that describe how to create categories in batch
by uploading CSV files^

{file name="Tiki 3 - How to Create Categories In Batch by Uploading a CSV File.pdf"}
{file name="Tiki 3 - How to Create Categories In Batch by Uploading a CSV File.doc"}

!!!!Step 1 : Create A CSV File that Describes Your Categories

^{img src="tiki-download_file.php?fileId=126" alt="Categories description CSV file"} ^

!!!!Step 2 : Navigate to [[http://<server-name>/tiki/tiki-admin_categories.php]] 
and use the ''Batch upload'' panel to select your Category CSV file and upload it 
to your Tiki [[replace <server-name> with the name of your server, such as "localhost"]]

^{img src="tiki-download_file.php?fileId=127" alt=""} ^

!!!!Step 3 : Verify that your new categories have been created

^{img src="tiki-download_file.php?fileId=129" alt=""} ^



But imagine that you would like that all content is readable only by registered users of your site, and only the content categorized as "__7.Validated__" is readable by anonymous. You could achieve that using  __category permissions__ (see following section).



!! Assigning permissions to categories
!!! How Category Permissions Work 

The category permission system follows the following rules.
# Categories are treated as objects, just like wiki pages and forums, etc.
# Category perms are hierarchical, unless you override the "& all children" option. Child objects will automatically inherit permissions from their parents.
# If there is a conflict between child and parent perms, permissions assigned to child objects take precedence over permissions assigned to parent objects.
# If a category allows (or does not disallow) user access to an object, the user's ((Groups)) permissions must also allow access to that kind of object.
# If no permissions are assigned to an object and any of its ancestor objects, global permissions for that users Groups are applied.
# Objects can be placed in more than one category. 
# Multiple category permissions: In the case where an object belongs to more than one category, the user must have permissions in ''all'' of the applied categories to perform that action. In other words, the category where the user had the lowest permissions takes precedence when considering if user can perform the action or not. 
# The stricter "must perms in all" rule can be relaxed (in tiki 1.10) to a "must have perms in one" by unchecking "Permission to all (not just any) of an object's categories is required for access" in ''admin->categories''.

To assign permissions to a category, go to tiki-admin_categories.php and click the appropriate key icon, which will send you to tiki-categpermissions.php. tiki-categpermissions looks and works very much like tiki-pagepermissions.php.

To know what the permissions mean exactly, see: ((Categories Details))


!!!!Changes to Category Perms Between 1.9 and 1.10

Before 1.10 there were only two category permissions:
*tiki_p_admin_categories
*tiki_p_view_categories
using these two perms, could not have a user who could view a categorized page but not edit (if they otherwise had edit permissions).

Starting in version 1.10, the permissions related to categories have been modified, to allow the possibility for users who can add an object to a category, but not change or remove the assigned categorization of an object.  

As such Tiki 1.10.x has different meaning for tiki_p_view_categories, and introduced some new perms like tiki_p_view_categorized. More information in ((Categories Details))^
!!! Example 
Following with the example in ((Categories Admin)), we need to click on the green key ({img src=img/icons/key_active.gif}) icon at the left of "''Status''" category:

^::{img src="img/wiki_up/categories_admin_06.png" }::^

which could show as something like:

^::{img src="img/wiki_up/categories_admin_07.png" }::^

As stated in the cited example, we want to remove from the anonymous group the permission to view the category content from all the "''Status''" subcategories. The easiest way is to click on "__(remove from this category & all its children)__":

|| group | permission | action
Anonymous | tiki_p_view_categories | __(remove from this category & all its children)__ (remove from this category only)
''(...)''||

You might need to confirm the action, depending on your configuration, to end up with a table like this:

^::{img src="img/wiki_up/categories_admin_08.png" }::^

Then, you can go back to "Admin categories", click on the ">>>" sign at the right of Status category, and click on the green key ({img src=img/icons/key_active.gif}) at the left of __7. validated__ (see image above, if needed). There we can add the permission ''tiki_p_view_categories'' for the ''anonymous'' group to read the content from that category, through clicking on "this category only" (or add the permission to that category and its children using the other button, if we had some child categories inside, and we would wish to do so).

^::{img src="img/wiki_up/categories_admin_09.png" }::^

That's it. :-)

Note that if there is no permission assigned to a category, you will see the yellow key ({img src=img/icons/key.gif}) icon next to it. 

And also that, starting in Tiki 1.10, a new category permission is added to Tiki in order to easily allow granting (or restricting) users to edit contents assigned to a category, through the permission "__tiki_p_edit_categories__" (= "Can edit items in categories").



!! Adding content to categories
You can add content to the categories from editing an object itself (see ((Category User))), on a edit an object by object basis, or in a centralized procedure from "Admin -> Categories".

For instance, we can add some content to the category "__1. To Do__", from the example above. We can click on the category name in the list, and we would see the objects which are already assigned to this category (no one in this example), and add new (existent) objects to this category:

^::{img src="img/wiki_up/categories_admin_10.png" }::^

After adding some objects, you will see them listed on the box "Objects in category __1. To Do__":

^::{img src="img/wiki_up/categories_admin_11.png" }::^

!! Applying themes to categories.
You can assign a basic theme style for you tiki site, but select some other theme site (such a customized them style similar to the previous but columnless, for instance) for specific objects in your tiki, or for specific categories. This way you might have, for instance, a homepage without columns, and after clicking on some links, keep browsing your site with some column/s on the side/s.

To enable this feature, you need to toggle it on as all the rest of fetures at "__Admin -> Features__".

^::{img src="img/wiki_up/categories_admin_12.png" }::^

The rest of information about how to use this feature can be read at its specific documentation page: ((Theme Control))

!!Using the current object categories in a tpl
tikiwiki>=3.0
If you want to use the current focus object categories in tiki.tpl for instance (you want to display some special menu in the column or in the header) you can use the feature 'Categories used in tpl' in admin->category
It will set the smarty variable objectCategoryIds
You can after use it like this
{CODE()}
{if isset($objectCategoryIds) and in_array(54, $objectCategoryIds)}
     {menu id=50}
{/if}
{CODE}
where 54 is the categoryId you want to display the menu.
The part ~np~isset($objectCategoryIds)~/np~ tests if you actually have activated the feature
The part ~np~in_array(54, $objectCategoryIds)~/np~ tests if the categoryId 54 is in the list of categoriees of the current focus object.
If you are on a page like tiki-index.php?page=foobar and if this page has the category 54 then the menu with menuId=50 will be displayed

!!General Admin setting
||Show Category Path|Show all the category paths of an object at the top of a page
Show Category Objects|Show the objects sorted by categories and object types that are in the same categories of the object at the bottom of a page
Category used in tpl|If you plan to use the category in the templates, you need to activate this feature. This will slow down you application as all the categories are looked for for the current object||

-=Related documentation pages=-
* ((Category))
* ((Category User))
* ((Categories Details))

!!Alias
*(alias(Categories-Admin))