T3glossary/project plan

Introduction

Create an on-line glossary of Typo3 terms as part of the Context Sensitive Help system.

Scope (Project objectives, context, limits)

This project will create a cross linked glossary for the TYPO3 system including:

• TypoScript objects and properties
• Backend form fields
• General TYPO3 concepts

Glossary entries will be catagorized by knowledge area and user type. Each entry will have subsections for links, examples and procedures. Because of the number and complexity of the entries creating the Glossary will be an ongoing process which is never completely finished. Entries will be created, edited and approved by Typo3 experts in some open collaboration process. The entire glossary must be easy to install on any TYPO3 system, ie it won't exist only on one server.

Requirements

Use Case Analysis

Actors

• FE User: looks up words and suggestes new words
• At Large Editor: user at large who wants to contribute to definitions
• Approved Editor: has proven Typo3 knowledge
• Glossary Admin: administers glossary system

Use Cases

• FE User
  • Looks up words by ...
  • Suggests new words ...

• At Large Editor
  • Adds/edits unprotected definitions ...

• Approved Editor
  • Protects definitions ...
  • Adds/edits protected and unprotected definitions ...

• Glossary Admin
  • Creates Approved Editors ...
  • Accepts or rejects suggestions for new words ...
  • Notifies appropriate Approved Editor of new undefined words ...

Other Functional Requirements

• Each definition will include subsections for the
  • Definition(s)
  • Procedures which might be relevant to the definition
  • Links to other Typo3 documents
  • Similar terms
  • Catagories, areas of knowledge and types of user
• There will be a system of catagories. Each definition will be catagorized in terms of the areas of Typo3 knowledge it belongs to and the type of Typo3 user (Admin, Developer, FE User, etc.) which might need to know the definition.
• Individual words in any definition may be easily linked to other words in the Glossary
• The Glossary may be exported/imported via some XML format
• The Glossary may be searched
• The Context Sensitive Help system may link to glossary items

Resources

Team Members and their Responsibilities

• Kasper
  • Initial concept
• Ingmar
  • Delegate project to community members
• Sylvain Viart
  • Manage project
  • Develop Regular Expression scripts
• Mark Ravitz
  • Modify extention to meet requirements

Hardware, Software Resources

• "t3glossary" extension
• system extension "context_help"
• Inside TYPO3: CSH

Software Plan

Structural (objects, classes, components)

Having taken a closer at sg_glossary I think it would be an excellent place to start.

Here's a list of requirements we have mentioned along with what it would take to make sg_glossary meet those requirements.

• word lookup

Already works fine

• system for approving and protecting finished definitions

I see two options here. The native Typo3 workflow system should work nicely. It could be configured in simple ways such as have an ‘editors’ group, or complicated ways such as having ‘editors’ and ‘reviewers’ in different technical areas. A simpler setup would be to use sg_glossary’s restriction tools to create ‘editors’ with all rights. Another glossary could be created for newly suggested words and undefined words. When a word was defined and approved it could easily be moved to the protected glossary.

• system to allow anyone to suggest a word which needs to be defined

Either create an additional sg_glossary for new and undefined words, or set up an email form for sending suggestions to the glossary administrator. I kind of like the idea of an email form as it would set up a conversation between a user and the glossary admin., who would learn more about how users are using the glossary.

• additional fields for: examples, procedures, links, similar terms

This should be a fairly simple matter of making a few changes in the tca.php and ext_tables.php . I expect the Rich Text Editor should be enabled for some or all of these fields.

• flexible category functionality (I would like the possibility to have an entry appear in more than one category!)

As I recall, there are provisions in the TCA for many to many relationships. This would mean that setting up multiple categories would require inserting a categories table and a many to many relationship table into ext_tables.php and then making the appropriate additions to tca.php . (Unfortunately this would give us a flat list of categories not a hierarchical one.)

• easy linking to other definitions in glossary

I believe this could be accomplished by creating a mode in sg_glossary which will display the definition of a word which is passed to it in an http get variable, and fooling around with the link processing in the Rich Text Editor. I can't see clearly how to modify the link processing at the moment but I'm sure it's possible and will probably be a headache (at least for me. In other words <glink>blork</glink> would be transformed into 'http://typo3.org/index.php?id=currentPageId&showDefinition=blork').

• import/export functions (XML?)

I think the simplest way is just to write another display mode into the main class (with its own plug-in ‘code’), then insert the plug-in content element on a page with restrictions on who will see it.

• different outputs: one letter per page or all letters on one page. Maybe even the possibility to show the glossary on four pages (like A-E, F-N, O-R, T-X)?

These are more display modes for the main class (see below)

• search functionality

Another display mode for the main class. Needs to create display based on search words in the http get variables.

• • writing extra modes for the main class such as different displays (including XML), responding to search words, responding to links from other definitions

As far as I can see sg_glossary is well written and well documented with one exception. The main display routine is almost 300 lines long and needs to be refactored before new display modes can be added efficiently.