[TYPO3-ect] TEP 2: Common Category Framework WAS: Concept of global categories

[Elmar Hinz]

Ernesto Baschny [cron IT] wrote:

... lots of proposals and ideas.

> - probably others..
> 
> Cheers,
> Ernesto


Hi all who are interesed in common categories and tag clouds,

I have now taken most of the ideas from this thread and made a TEP from
this. It is still a draft and waits for your comments to be completed.

I will need some good advices how to integrate new form elements into
TCA forms. The possibilities of the normal selection elements are too
limited. I can't fill mm-relations in the way I would need to.

Does anybody has experiences whith user defined elements?


You can read the draft of the tep as a weblog or as reStructuredText.
The reStructuredText is below the weblog is here:

http://t3flyers.wordpress.com/2006/09/14/tep-common-category-framework-ccf/


======================================================================
======================================================================
======================================================================


Tep: 		2
title: 		Common Category Framework (CCF)
version:
lastModified:
author: 	Elmar Hinz
authority: 	Extension Coordination Team and R&D Commitee
status: 	draft
contentType: 	text/rst
created: 	14-Sept-2006

    Copyright (c)  2006  Elmar Hinz, elmar.hinz at team-red.net
    Permission is granted to copy, distribute and/or modify this document
    under the terms of the GNU Free Documentation License, Version 1.2
    or any later version published by the Free Software Foundation;
    with no Invariant Sections, no Front-Cover Texts, and no Back-Cover
Texts.
    A copy of the license is included in the section entitled "GNU
    Free Documentation License".



.. contents:: Table of Contents

===========
1. Abstract
===========

The Common Category Framework(CCF) enables different TYPO3 extensions
within an installation
or a subtree of an installation to use common sets of categories. This
offers a broad range of
advantages for developers and users. It opens the door to completely new
kinds of applications
and content organization.

The Common Category Manager(CCM) is a backend modlule to organize the
categories and to
map them to entries from different tables.

The Common Category Search (CCS) is a frontend plugin that offers the
search for datasets
of multiple tables by selections within categories of the CCF.

The Common Category Tags (CCT) is a set of plugins that offer content
tagging and
retrieving by the visitors of a site.

===============
2. Introduction
===============

The categories are organized within a category tree. To get a flat list
of categories they
have to be stored in one single node. If extensions need multiple kinds
of categories this is
done by using different branches of the tree. Also tag clouds can be
maintained by storing the
user contributed tags as categories into one single node.

The categories contain a list of optional meta tags. Only the title is
mandatory. It is possible
to extend the meta tags fields by TYPO3 extensions.

The relations between data and categories can be created as 1:N or M:M
relation.

A library extension will be provided, that enables the access to the CCF
by a simple API.

It is possible to internationalize categories. It is possible to use
access control to categories.

The data of existing extensions can be included into the system without
any alteration. This is
done by pointing to their entries with the m:m relation table.

The Common Category Manager(CCM) is a backend modlule to organize the
categories. Categories
can be created, deleted, moved and edited. Addtionoally categories can
be mapped to datasets
from the different tables. The manager is not meant as the default way
to map datasets. It is
meant as a fallback solution for extensions that havn't implemented the CCF.

The CCS is a frontend plugin that enables the retrieval of content from
multiple tables that
is categorized within the CCF. The result list links to the single views
of the original
extension.

The Common Category Tags (CCT) is a set of plugins that offer content
tagging and retrieving by
the visitors of a page like it is known from many popular internet
platforms like technorati,
`del.ico.us`_, flickr_ or wordpress_. User tags are used to build tag
cloudes and related tags
lists.

.. _technorati: http://www.technorati.com/tag/
.. _`del.ico.us`: http://del.icio.us/tag/typo3/
.. _flickr: http://www.flickr.com/explore/
.. _wordpress: http://t3flyers.wordpress.com/


=============
3. Motivation
=============

Today extensions come with their own system of categories each. Most
have a simple list of
categories. It is possible to do simple or multiple selections. More
enhanced extensions like
DAM or tt_news provide an own categorie tree. Operators of TYPO3
installations that want to use
one schema of categories for the whole range of extension data need to
configure the categories
several times.

The idea of common categories has been in the discussion since a long
time, as mere categories
as well as in connection with other metadate schemes like the UNIMARC
system or the
Web Ontology Language. A lot of valuable ideas have been discussed in
the newsgroup of the Extension coordination team.

This TEP will not cover the question how to connect CCF with OWL or
UNIMARC, but it is likely
that it can serve as a component for future developments like this.

CCF should become a member of the set of ECT supported basical
extensions. Common Category Search (CCS) and the Common Category Tags
(CCT) should be quickly available to promote the CCF framework.

==========
4. Details
==========

Acronym and Extension Key
=========================

The acronym for the Common Category Framework is CCF.
The basical CCF extension gets the key "ccf".

Definition of terms
===================

category type
	Own page type with an own page type number. Category types differ by
the fields that can
	be used to describe the category.

category set
	The set of categories from wich the user can choose by a single or
multiple selection,
	to categorize a data entry. The datastructure of this set is a single
folder or a branch
	of the category tree.

Using the page tree
===================

The categories will be implemented as page type within the page tree.
The main motivation is to
reuse differnt features the pagetree already offers:

* parent child relations
* internationalization
* pagebrowser
* fields like title, image, description
* display in the pagetree frame
* generation of HMENU in the frontend
* tree functions in the libraries
* moving, renaming
* import, export

Configuration of the default category type
==========================================

TCA configuration of the new pagetype follows the common rules of TCA
configuration.
We choose following fields for $TCA[pages][types][900][showitem] for the
default category.

title    	
	categorie dispaly title
subtitle 	
	aditional title
alias		
	useful if the category occurs in urls
media 	
	image for the category
description	
	category description
deleted 	
	a category can deleted

For the first version hiding in the different forms will not be supported.


Reservation of numberspace for public page types (900 - 990)
============================================================

The range of page type numbers from 900 to 990 is reserved for public
category types. Category
types can be published as public extensions.

User defined category types have to use a page number above 1000.

The range form 991 to 1000 is not reserved. It is likely that a lot of
existings installations
already use the numbers 998, 999, 1000 for user defined page types.


Multiple relations (table tx_ccf)
=================================

Conntecting datasets to categories by a M:M relation table has the
advantage that it can be
done from outside without the need to extend or alter existing
extensions. So every data table
of an installation easily be included into the CCF. Logically the use
will still be limited to
common tools, as the connected extensions still haven't implemented the
relations.

uid		
	standard in TYPO3
pid		
	folder(s) where the relations are managed in
category	
	the page id that defines the relation
table		
	the table that is related
entry		
	the uid of the related dataset or an alternative key (hash for cache_pages)


Single relations  (table tx_ccf)
================================

Categories that are meant to be used as single selections, would usually
be done by a field
within the related table. But again we use the table tx_css because we
can add single relations
from outside to an existing extension. The only difference to M:M
relations is that we can only
do a single entry.


Integration into extensions
===========================

.. note::
	It would be nice to select categories directly within the form of a
dataset. Currently
	there seems no direct way to do this. The Core documentation says about
selections:

	"Notice: Using MM relations you can ONLY store real relations for
foreign tables in the
	list - no additional string values or non-record values."

	So we couldn't fill the additional fields that are required by tx_ccf
with the standard
	selection type of the TCA.

.. admonition::TODO
	Find a solution for this.


Common Category Manager (CCM)
=============================

The manager has two mayor tasks. In the first place it is a manager for
the categories. In the
second place it is a fallback solution to map categories for extensions
that haven't implemented
CCF.

In the beginning general part of the CCM consists mainly of the TCA form
for page administration. It offers all features that are necessary to do
all adminstration tasks for a category.

The mapping part requires a backend module. In the first step a table is
selected that
should be mapped. The table entries are listed alphabetically orderd by
the label configured in the TCA for them. Below each entry the mapped
categories are listed. They can be removed by
pressing an "unmap link".  When pressing an "add category" link of the
entry a popup window
occurs that enables the selection of new categories from a tree.

A third part is a simple tag creator. See CCT->CCM Tag Creator.

Common Category Search (CCS)
============================

The Common Category Search consists of the form with select inputs for
categories, the result
list and  a result browser for larger result lists. This is a very
simple but usefull tool.

Enhanced versions of such a category search could include a searchword,
ajax dynamic for the
select inputs and other usefull components.

The common category search requires some TS configuration:

* The categories that should be offerd as selections.
* The tables; that should be included into the search.
* The necessary parameters to link to the details views of extensions.

Common Category Tags (CCT)
============================

A tag is like a subject or category. Tags are a technic of dynamic
categorization that assists
the user to find content of his interest. It can be regarded as an
alternative way of
navigation. Tags dynamically implement the mental traks that the users
of a site want to follow.

Tags need an object to tag. Such an object can be a dataset from
tt_content or any other table.
The object could also be cached versions of a page. The cHash should be
taken as identifier so
that the tags survive even if the cache is cleared.

----------------------------
Creation and mapping of tags
----------------------------

Tags are a collection of categories within one single node. Different
ways to contribute tags are
possible:

1. common definition of tags for the whole site
2. definition of tags by the authors of content
3. definition of tags by the visitors

Creation and mapping should by the same process from perspective of
usibility. The user enters words into a form. If that word doesn't exist
as category it will be created.

* Tags are beeing creted case insensitive. Only the lower case form is
stored.
* A tag can consist of several words.
* The maximum length of a tag is limited to 255 characters by the DB.
* The maximum length of a tag can be configured by TS.


1. CCM Tag creator
------------------

The CCF implements method 1. into the CCM. All the Administrator needs
to do, is to select a
node and to put a list of words into a text area. After submit the tags
are created. But they
still need to be mapped with the common CCM mapping tools.

This module could be extended to a tag editor in a later version. It is
not planned for the first
version of the CCM.


2. Definition of tags by the authors of content
-----------------------------------------------

A content author needs to map his content to existing tags or to tags he
newly creates.
If the author is limited to existing tags can be configured, maybe on
user base in a future
version.

.. note::
	How can this be done? The best would be a TCA form element that is
specialized on this
	task. It could be added to the TCA definition of different tables.

.. note::
	Plugins for frontend editation could be supported by a little library
that assists in
	implenting this functi<onality in frontend forms.

.. admonition::TODO
	Find a solution for this.


3. definition of tags by the visitors
-------------------------------------

For now it is not planned to support this option.

------------------
Related tags lists
------------------

A related tags list is a kind of `automatic context menu`. It is a list
of links, that occures
above, below, or beside the object that is tagged. This list contains
the tags related to the
object. Clicking on a tag leads to a view, where other contents are
listed that are tagged with
the same tag.

.. _`automatic context menu`: http://t3flyers.wordpress.com/

The functionality of related tags lists can be added by typoscript to a
content type or directly
integrated into a frontend plugin. The related tags list needs as
identifier a table and a key.
The key is usually the uid of the dataset. It may be an alternative key.
An example for the latter
would be the hash key for the table cache_pages, because it is the
identifier that stays constant
even if the cache table has been cleared.

------------------
Tag clouds
------------------

A `tag cloud`_ (or weighted list in visual design) can be used as a
visual depiction of content tags used on a website. Often, more
frequently used tags are depicted in a larger font or otherwise
emphasized, while the displayed order is generally alphabetical. Thus
both finding a tag by alphabet and by popularity is possible. Selecting
a single tag within a tag cloud will generally lead to a collection of
items that are associated with that tag.

.. _`tag cloud`: http://en.wikipedia.org/wiki/Tag_cloud

The tag cloud is is a plugin that displays the most popular tags
optically wheigted and in
alphabetical order. Several TS configurations will be possible. The
popularity of a tag is
measured by the amount of clicks in a period. The clicks are counted by
the script that displays
the collection of items that are associated with that tag.

Table tx_cct (Tag calls)
------------------------

* uid		standard in TYPO3
* pid		node where the tag calls are stored
* tstamp	moment of the call
* category	ID of the tags category

Tag calls are stored within the same node as the tags categories that
they are traking.

A SQL query to generate the a tag cloud contains in the where condition:

* the node ID
* the minimal tstamp for the time range

It is grouped by the category and counts the entries per group.

=============
5. Discussion
=============

=================
6. Implementation
=================

=============
7. References
=============

==============
8. Attachments
==============