TEP: Common Category Framework (CCF)

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

Copyright (c) 2006 Elmar Hinz, elmar.hinz@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”.

• • 1. Abstract
  • 2. Introduction
  • 3. Motivation
  • 4. Details
    • Acronym and Extension Key
    • Definition of terms
    • Using the page tree
    • Configuration of the default category type
    • Reservation of numberspace for public page types (900 – 990)
    • Multiple relations (table tx_ccf)
    • Single relations (table tx_ccf)
    • Integration into extensions
    • Common Category Manager (CCM)
    • Common Category Search (CCS)
    • Common Category Tags (CCT)
      • Creation and mapping of tags
        • 1. CCM Tag creator
        • 2. Definition of tags by the authors of content
        • 3. definition of tags by the visitors
      • Related tags lists
      • Tag clouds
        • Table tx_cct (Tag calls)
  • 5. Discussion
  • 6. Implementation
  • 7. References
  • 8. Attachments

 

 

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 module 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 module to organize the categories. Categories can be created, deleted, moved and edited. Additionally 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 clouds and related tags lists.

 

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 category 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 which 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 different 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 existing 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.

 

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 usability. The user enters words into a form. If that word doesn’t exist as category it will be created.

• Tags are being created 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 edition could be supported by a little library that assists in implementing this functionality in frontend forms.

 

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 occurs 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.

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.

The tag cloud is is a plugin that displays the most popular tags optically weighted 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 tracking.

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