.. You may want to use the usual include line. Uncomment and adjust the path. 
.. include:: ../Includes.txt


====================
EXT : Categorization
====================

:Author:
      Kasper Skårhøj

:Created:
      2002-11-01T00:32:00

:Changed by:
      Stéphane Combaudon

:Changed:
      2005-02-18T13:56:03

:Author:
      Smile

:Email:
      typo3@smile.fr

:Info 3:


:Info 4:


.. _EXT-Categorization:

EXT : Categorization
====================

Extension Key:  **smile\_categorization**

Copyright 2005, Smile, <typo3@smile.fr>

This document is published under the Open Content License

available from http://www.opencontent.org/opl.shtml

The content of this document is related to TYPO3

\- a GNU/GPL CMS/Framework available from www.typo3.com

.. _Table-of-Contents:

Table of Contents
-----------------

**EXT : Categorization 1**

**Introduction 1**

Glossary 1

What does it do?1

**User manual 2**

Create a category 2

Categorize a content 3

Plugin “Category contents” 3

**Configuration 4**

Installation 4

Parameters 4

**Technical details 6**

Overridden classes 6

Database update 6


.. _Introduction:

Introduction
------------


.. _Glossary:

Glossary
^^^^^^^^

*[from http://www.searchtools.com/info/classifiers.html]*

*Categorization* is the process of associating a document with one or
more subject categories. So the entry for a page on cross trainer
shoes could go into Running, Manufacturing, Sports Medicine, etc. All
of these are legitimate, depending on the context.

*Cataloging* and  *Classification* come from libraries, where
specialists enter the metadata (such as author, date, title and
edition) for a document, apply subject categories to it, and place it
into a class (such as a call number) for later retrieval. These tend
to be used interchangeably with Categorization.

A  *Thesaurus* is a set of related terms describing a set of
documents. This is not hierarchical: it describes the standard terms
for concepts in a controlled vocabulary. Thesauri include synonyms and
more complex relationships, such as broader or narrower terms, related
terms and other forms of words.

*Taxonomy* is the organization of a particular set of information for
a particular purpose. It comes from biology, where it's used to define
the single location for a species within a complex hierarchic.
Biologists have arguments about where various species belong, although
DNA analysis can resolve most of the questions. In informational
taxonomies, items can fit into several taxonomic categories.

*Ontology* is the study of the categories of things within a domain.
It comes from philosophy and provides a logical framework for academic
research on knowledge representation. Work on ontologies involves
schema and diagrams for showing relationships in Venn diagrams, trees,
lattices and so on.


.. _What-does-it-do:

What does it do?
^^^^^^^^^^^^^^^^

The  **smile\_categorization** extension adds a categorization feature
to Typo3.

One way to look at this extension is as a new mean of delivering a
content item in pages other than the one where it was created. Typo3
already allows this, but mostly on a one-by-one basis, and a ‘target
driven’ approach, meaning you go to the target page, you say “I will
add something here”, you pick a content and you’re done. This is not
always satisfactory. First you may want a more ‘source driven’
approach, meaning a scheme where you think about other deliveries of
the content  *when you create it* . Secondly, categorization is a
rule-based mechanism for defining multiple delivery. And finally, the
tree structure of categories will allow to define alternate navigation
schemes.

Here’s how it works. Basically, you can define one or several
hierarchical trees of categories, then you may define a relationship
between a content and one or more of these categories. Defining this
relationship is optional, thus some contents may not be categorized,
while others may be linked to several categories. Once contents have
been categorized, you may deliver content according to these
categorization schemes. This possibility may be used to provide more
than one navigation logic, i.e. a way for visitors to access content
not through the primary organization, but through alternate
organizations.

Let us consider the following example.

Imagine your web site is about music. You have designed a primary
structure as per music genre, say Rock, Jazz, Latin, New Age,
Inspirational, Opera, etc. But this is not the only way to categorize
music. You might also have organized your contents as per  *countries*
, or per  *price range* , or per  *Record Company* , or many other
schemes. And some visitors could be more pleased with these other
schemes.

Well, the smile\_categorization extension allows you to provide
several organization and thus several navigation schemes within your
content.

When a new content item is created, a piece of music, it is created
*within a given node* as per the primary tree structure, and also
linked to a country, an author, a price range, a record company. And
on the front-end side, your site may propose to navigate the music
arena  *per record company* .

One thing to notice, which this example did not mention, is that each
categorization axis may be linear (Rock, Jazz, Latin, etc.) or
hierarchical i.e. organized as a tree (classical, classical>romantic,
classical>romantic>berlioz, …).

More specifically :

- Categories are created by creating pages with the “category” type.

- One or more categories can be matched to unspecified contents.

- “Category” pages behave like standard pages : they can have their own
  contents and be linked into a tree structure.

- “Category” pages automatically display categorized contents, i.e.
  content linked to the category. Category pages may be hidden if this
  automatic delivery is not wanted.

- Categorized contents can be displayed as complete contents or as
  summaries with a link to the original content.

- A plugin is available to display categorized contents with many
  formats on an unspecified page.


.. _User-manual:

User manual
-----------

First, the extension needs to be installed and configured : see the
"Configuration" section.


.. _Create-a-category:

Create a category
^^^^^^^^^^^^^^^^^

To create a category, create a page in the tree structure of the pages
of the site. There are two possibilities to make this page a category:

- Set its type to “ **category** ” (in the “ **Edit page header** ”
  menu) ;

- Set its type to “ **advanced** ” and check the “ **Activate as a
  category** ” checkbox.

When a page is “categorized”, a field called “ **category name** ” is
available. This field enables to give a name to the category. If a
category name is set, it will be used instead of the page title in the
list of all the categories available to categorize a content.

|img-1|


.. _Categorize-a-content:

Categorize a content
^^^^^^^^^^^^^^^^^^^^

Once categories, and category trees are defined, you may categorize
content items.

To associate one or more categories to a content, edit the content in
the back-end and click on the “Categories of the content” field. A
pop-up window is opened with the tree structure of the site (the tree
could be limited to a part of the site tree structure, cf. Section
“Configuration/Display of the element browser”). Only categories are
clickable. Click on the category you want to associate to the content.
Repeat the process for each category.

|img-2|

|img-3|

To see the result in the front-end, go to one of the category pages
you have associated your content to. This content is then
automatically displayed on this page.


.. _Plugin-Category-contents:

Plugin “Category contents”
^^^^^^^^^^^^^^^^^^^^^^^^^^

To display categorized contents in an unspecified page, insert a
plugin and choose the “Category contents” one. These two fields are
then available :

- **Categories to display** : this field enables to choose one or more
  categories among the available categories ;

- **Type of display** : this field enables to choose the display type

- **Categories tree** : displays the tree structure of the selected
  categories ;

- **Contents list (titles and abstracts)** : displays contents abstracts
  and titles with a link to the original contents ;

- **Contents list (complete contents)** : displays the complete
  contents.

|img-4|


.. _Configuration:

Configuration
-------------


.. _Installation:

Installation
^^^^^^^^^^^^

To install the extension using the Extension Manager, choose the
module " **Ext Manager** " in the left menu. Then, choose " **Import
extensions from online repository** " in the top menu and select this
extension in the list. Click Ok to all changes asked by Typo3.

In order the category pages to display categorized contents,  **the
following lines have to be copied in your typoscript template** (where
CONTENT\_ZONE is the HTML marker in your template file) :

::

   subparts.CONTENT_ZONE = COA
   
   # Contents from the current page
   subparts.CONTENT_ZONE.10 = CONTENT
   subparts.CONTENT_ZONE.10 < styles.content.get
   
   # Contents from categories
   subparts.CONTENT_ZONE.20 < tempCategorisation
   


.. _Parameters:

Parameters
^^^^^^^^^^


.. _Display-of-contents:

Display of contents
"""""""""""""""""""

The five following parameters are available for the extension :

- the  **template file** used for the display in abstract mode ;

- the  **threshold number of contents to be displayed in complete mode**
  (beyond this number,contents are displayed in abstract mode) ;

- the  **maximal length** (in number of chars) of abstracts ;

- the  **field used to order the categorized contents** , by date or by
  header ;

- the  **order** used, ascendant or descendant.

Here is the default values :

::

   plugin.smile_categorization {
     
     # HTML template used to display contents in abstract mode.
     templateFile = typo3conf/ext/smile_categorisation/template.tmpl
   
     # Threshold beyond which contents are displayed in abstract mode.
     nbmax = 6
   
     # Abstract length in number of chars.
     abstractLength = 100
   
     # Display order type of contents : 'date' ou 'title' :
     orderType = date
   
     # Display contents in ascendent 'asc' or descendent 'desc' order :
     orderAsc = desc
   
   }

To modify one value, copy the line to the “constants” field of the
typoscript template, and change the value.

Another solution is to use the constant editor : in “Template” mode,
select “Constant Editor” in the top right corner of the page, then
select “PLUGIN.SMILE\_CATEGORIZATION” in the “Category” combobox.

|img-5|


.. _Display-of-the-element-browser:

Display of the element browser
""""""""""""""""""""""""""""""

When we categorize a content, a window with the tree structure of the
site enables to choose a category. This window enables to choose only
categories. That's why the administrator can limit the tree structure
to a part of the site. This is useful if all the category pages are
under the same root page. One can add the following line in the “
**Tsconfig** ” field of a user or a usergroup :

::

   # Root page for the categories tree
   categoryRootPid = 18

“18” has to be replaced by the uid of the root page of categories.


.. _Technical-details:

Technical details
-----------------


.. _Overridden-classes:

Overridden classes
^^^^^^^^^^^^^^^^^^

The Typo3 following classes are overridden by the
smile\_categorization extension :

- the **tslib\_cObj** class from the  **tslib/class.tslib\_content.php**
  file is overridden by the  **ux\_tslib\_cObj** class from the
  **typo3conf/ext/smile\_categorization/class.ux\_tslib\_cObj.php**
  file;

- the  **TBE\_PageTree** and  **SC\_browse\_links** classes from the
  **typo3/browse\_links.php** file are overridden by the
  **ux\_TBE\_PageTree** and  **ux\_SC\_browse\_links** classes from the
  **typo3conf/ext/smile\_categorization/browse\_links\_category.php**
  file.


.. _Database-update:

Database update
^^^^^^^^^^^^^^^

**tt\_content** and  **pages** tables are modified by the
smile\_categorization extension. The following fields are added :


.. _Table-pages:

Table “pages”
"""""""""""""

- **tx\_smilecategorization\_category** : integer which is equal to 1
  for “advanced” pages which are categorized.

- **tx\_smilecategorization\_category\_name** : name of the category.


.. _Table-tt-content:

Table “tt\_content”
"""""""""""""""""""

- **tx\_smilecategorization\_categories** : list of the categories of
  the content. A category is represented by its page uid.

- **tx\_smilecategorization\_plugin\_categories** : list of categories
  to display with the “Categories contents” plugin.

- **tx\_smilecategorization\_plugin\_display** : type of display for the
  “Categories contents” plugin.0 : Tree of categories1 : Abstracts of
  contents2 : Complete contents

|img-6| EXT : Categorization - 6


.. ######CUTTER_MARK_IMAGES######

.. |img-1| image:: img-1.png
.. :align: left
.. :border: 0
.. :height: 329
.. :id: Image1
.. :name: Image1
.. :width: 669

.. |img-2| image:: img-2.png
.. :align: left
.. :border: 0
.. :height: 93
.. :id: Image2
.. :name: Image2
.. :width: 389

.. |img-3| image:: img-3.png
.. :align: left
.. :border: 0
.. :height: 207
.. :id: Image3
.. :name: Image3
.. :width: 425

.. |img-4| image:: img-4.png
.. :align: left
.. :border: 0
.. :height: 375
.. :id: Image4
.. :name: Image4
.. :width: 669

.. |img-5| image:: img-5.png
.. :align: left
.. :border: 0
.. :height: 254
.. :id: Image5
.. :name: Image5
.. :width: 669

.. |img-6| image:: img-6.png
.. :align: left
.. :border: 0
.. :height: 32
.. :id: Graphic1
.. :name: Graphic1
.. :width: 102