The list of categories, and the edit and display templates should be a page or pages on the TWiki. They should be over-ridable like WebPreferences
You may want to have edit privelidges on that page, or you might want to allow users to add/refactor them at will..
- 27 Feb 2001
- each web has a CATEGORIES variable, listing the topic names that define the categories for that web
- use fully qualified topic names (web dot topic) to recycle categories from other webs
- each category topic contains:
- a CATEGORYTYPE variable (text | choice | radio | select )
- a CATEGORYOPTIONS variable (size, initial value, ...)
- a CATEGORYVALUES variable listing all values (topic names, if you like)
- we move the information contained in the
wikicatitems.tmpl file in an editable set of topics.
- we can use twiki tags to fill part of the category definitions (I am thinking to a mix of ACCESSTOPICCHANGE and categories to do PoorManWorkFlow)
- we can rename (move) category definitions (or values) around
- 09 Apr 2001
I would simplify this and specify the whole category table in the WebPreferences
. This is for parsing speed and code simplicity. It also does not require category items to be WikiNames
radio|UseCategory|0|Yes|No, delete this category table
Same example, brainstorming on preferences:
* Set CATEGORIES = UseCategory, TopicClassification, OperatingSystem, OsVersion
* Set CATEGORYITEM1 = UseCategory|radio|0|Yes|No, delete this category table
* Set CATEGORYITEM2 = TopicClassification|select|1|Select one...|NoDisclosure|PublicSupported|PublicFAQ
* Set CATEGORYITEM3 = OperatingSystem|checkbox|true|3|OsHPUX|OsLinux|OsSolaris|OsSunOS
* Set CATEGORYITEM4 = OsVersion|text|16
Hmm, may be
is redundant? Hmm, any better idea for syntax?
- 09 Apr 2001
- ) have Category Items just point to a topic.
- ) componentise every Topic to have multiple fields.
- 10 Apr 2001
Please, keep the CATEGORIES variable.
I propose we implement it this way:
- WebPreferences contains always the CATEGORIES list
- for each category name if there is a corresponding CATEGORYITEMn then use it
- else get the definition from the corresponding topic
- categories without definition are dropped
- 11 Apr 2001
Good idea. The only problem I see with this is the dependencies of many searches on those categories (this web included). Everytime the categories are changed, the main search page, and many other pages would have to be changed as well.
So the solution would probably be:
- Use the category variables (arrays of some sort?) in the search definitions
- Be able to format pull-down menues from category variables
But please, this change should probably happen alongside the GenericMetaDataStoreForTopics
as both would require the reformatting of all the searches (and personally I wouldn't want to reformat that any more often that I already do).
- 11 Apr 2001
and I exchanged some e-mail on category table editor spec and CategoriesAndParents
Now is a good opportunity to work on this since we need to change the TWikiCategoryTable
code anyway because of the GenericMetaDataStoreForTopics
The goal is KISS and to make an easy upgrade of existing installations.
First some terminology:
- Category table:
- The table with category items
- Category item:
- One table row with category item name and category item value.
- Category item name:
- The name of an item in a category table
- Category item value:
- The value an item in a category table. Is an <INPUT> widget when editing a topic.
- Category table definition topic:
- The topic that defines the category table. Is currently the
I propose this spec for replacing the template based category table definition by a topic based one:
1. Enable a category table:
defines the Category table definition topic name:
2. Define the category table:
- Set CATEGORYTABLE = CategoryTable
Any topic can be a Category table definition topic. The
preference variable points to the CategoryTable topic. This topic has descriptive text mixed with the category table defined as a TWiki table: (taking the category table of the Know web as an example)
|radio|UseCategory|0|Yes|No, delete this category table|
A Category table definition topic can also contain any documentation, including tables as long as it does not conflict with above syntax.
This format allows you to define category items with / without WikiNames
, depending on your needs.
The topic can be protected in the usual manner so that not everybody can change the category table.
3. Category table definition topic name stored in meta data:
Store the category table name in the meta data, so you know in which category table format the topic is (needed for edit and save).
4. Multiple category tables per web:
Currently only one category table can be defined per web. For WorkFlow
systems it makes sense to allow more then one category table. I.e. we have a set of template topics like expense report, vacation request etc. Each template topic is of a certain category table. When you create a new topic based on SelectableNewTopicTemplates
you basically instantiate a new expense report, vacation request etc.
Question is how to initiate a template topic of a specific category table, kind of a chicken and egg problem.
Need to figure out how/if to switch to a different category table. Actually, may be better not to offer that from the GUI since it can be confusing and also damaging, i.e. loosing values of current category table.
For the TWikiReleaseSpring2001
we should shoot for 1.
. Item 4.
could be done later.
Ideas, comments on this new spec?
- 16 Jun 2001
I suggest we drop table from the WebPreferences
variable as table is just one possible output format. So how about:
- Set CATEGORIES = BugCategory, FeatureCategory
These category pages then just lists the items that make up the category e.g.
Contents of BugCategory
| *CategoryDefinition* |
| BugType |
| BugPriority |
These are in turn topics, e.g.:
Contents of BugType
| *CategoryItem definition* |
| BugReported |
| BugAssigned |
| BugFixed |
Type could default to select box, alternative choice could be given, if no Category Item given, it is text
A topic could be in zero or more Category Definitions, which could share CategoryItem
This idea does mean more topics, but you usually have a topic per category item, so might as well make good use of it and have an easy on the eye format.
A thought on names. Would it be better to have TopicClassification
that are made up of categories?
The edit window would show the category items for the defined Categories. I think it would be cleanest for category changes to be done elsewhere, so there would be no UseCategory
As mentioned above, searches will clearly have to change. Dealing with migration from an earlier installation could be tricky. As always, we want to make this as easy as possible. With attachments the upgrade is done when a page is edited, but can also be done via a script. With categories a mixture of old and new makes searching more complex; so upgrading all the topics would make life a lot easier. Alternatively, the .tmpl file could be read to provide automatic compatibility. Thoughts?
- 18 Jun 2001
Splitting up the category table into multiple topics is flexible and might be powerful, but I see a danger in doing so: Point of failure. Edit one of many topics defining a category table and you are out of synch with all existing topics. Category tables need to be stable, especially if used to implement a knowledge base.
Also, IMO it is important to think of category tables as sets; a workflow system uses sets of category tables, one for each form. Each set should be fixed, or evolve in a controlled manner (programmatically or manually). The Category table definition topic
defines one set as described above. I was not very clear before, so I updated my previous posting.
If we split up a set into several topics we would require WikiWords
for category table items. At work I had one group that specifically asked to have non-WikiWords for category table items (but one link in the category header with help on the items)
So for the upcoming release I suggest that we have one category table set defined by a category table definition topic. (KISS, and does not deviate too much from the existing definition by template topic.)
Regarding search, it should work out of the box without any change if we plan for it. Currently we
by a regexp like "TopicClassification.*FeatureToDo". We need to make sure that this regexp does work also for the new meta data format, i.e. we are fine if we do meta data like
- 18 Jun 2001
I agree with Peter on much of this - it's important to be able to define the 'schema' for a category table in one place, as is done now, and the ability to have non-WikiWords is also important (though I'd like to see a way of automatically linking them, using the
[[ ... ]]
As John points out, the category table visible on forms today is just one rendering of the data. It's worth trying to clarify the terminology a little, since what's being done here is adding structured database-style fields to the free-text Wiki pages. I found the term 'category table' quite hard to understand initially, but a category-table-enabled TWiki web can be viewed as a database file, with records and fields. (I'm avoiding the relational terms of table, rows and columns since they conflict with TWiki terms.)
Mapping the terminology above onto database terminology, you get:
- Category table:
- A data record held in a specific table, including several field names and corresponding values
- Category item:
- A data field name and value (e.g. Status field, value Draft)
- Category item name:
- Category item value:
- Data field value. Is __manipulated via__an <INPUT> widget when editing a topic. (In the current HTML implementation, anyway - other implementations could be used in the future of course, e.g. for WAP, without altering the logical structure.)
- Category table definition topic:
- The database schema details defining the record structure, including the field names and data types (i.e. allowed values or types of values). Currently implemented by the
In addition, the other parts of the topic can be described in the same way:
- Topic contents
- This is really a special (unnamed) field containing an arbitrary amount of text, input via the TEXTAREA widget
- Topic metadata
- This is really a special set of fields, normally hidden from the end user, with a similar structure to the visible fields defined by the category table system.
The reason for phrasing things like this is that many people understand how databases work, and many useful lessons can be drawn. For example, the issue of converting from existing topics when the category table definition is changed is the well-known challenge of schema evolution.
The problem of designing a CategoryEditor
is really the problem of implementing a schema editor, which has been done many times in the relational world of course. Most schema editors just define, for a given record type (category table), the field names (category table item names) and data types (e.g. text, choice, etc.) - the PC-oriented ones include the UI details, like TWiki does, which is probably a good idea in order to make it easy to define category tables.
Some non-relational DBs, such as PICK, allow you to define multiple values in a single field - this is exactly what TWiki does today when you define a checkbox field, and is very powerful even though relational purists would shudder. There is some rationale for separating out into a separate topic the list of allowed values in a field (e.g. the radio box or check box fields today) - a separate topic can more easily be maintained by someone else without disturbing the actual schema of the category table (e.g. to add a new classification for a question/answer knowledge base).
So - I would like to see the category items (fields) all defined in a single category definition topic, but with any multiple-value fields (e.g. radio button or check box or drop down) having their allowed values defined in a per-field (category item) topic, as suggested by John. Any UI details for these multiple-value fields would be defined in the central category definition topic (e.g. use of drop down field vs radio buttons), as should the choice of radio buttons vs check boxes (which is really defining whether the field can contain a single value or multiple values, a la PICK).
Finally, having more than one category table per web would be very useful, if not essential for WorkFlow
- I guess that's not in the immediate plans, as it's part of step 4 above. However, all that's needed is to plan for this from the beginning, by giving a name to the category table (aka record type) that is being defined in the category editor, and then defining some way of assigning a specific record type to new topics as they are created - e.g. using the topic name or perhaps a template selected by the page used to create the topic.
Hope this makes sense!
- 18 Jun 2001
I've implemented some of the above and put into CVS. The comments say it's experimental, perhaps not the best choice of words, but an indicatation that it is not complete, nor has the specification been agreed, so things are likely to change. Some details on what's in CVS:
- A special topic (
WebTopicClassifications) defines the possible category tables. I will soon change this to a variable in WebPreferences.
- Each category table (or classification - might need a name change here) is defined in it's own topic, a format similar to InterwikiPluginEarlyDev is used.
- These individual category items (or categories) are then defined in their own topics if multiple selection is required (similar in relational terms to having a foreign-key e.g. to a pick list). This allows a multiple item selection to be explicitly shared between category tables.
- This new category system works in parallel to the existing one - this is of course temporary.
- I've changed links on edit page to definitions to pop up a new window, in the same way that GoodStyle and TextFormattingRuels do (as an aside - we lack visual clues for these links being different to normal ones).
- I've dropped UseCategory - I agree with Peter's concerns about this, I'm keen to address these. The reason I did this was to allow for changing the category table, without use of DHTML I couldn't see a way of chaning category table and hence fields (category names) within the edit window. Instead you can select classification change range than edit, you get to choose category, before doing an edit. More thoughts on this below.
I shared Richard's confusion when I first looked at categories, now I use them a lot, but there is something about the current system, whether it's the terminology, the templates or the examples I don't know, that confuses. I'd be interested in other people's thoughts on this. Also, does anyone want to see the retention of the view and edit templates for categories? Attachment formatting currently lacks this, my initial meta based category system also lacks this.
On searching, Peter made a very good point about that the current system would work as is. I suggest there also a more explicit search that only checks the meta variables, but use of this would of course be optional.
A minor implementation point. At some point it was suggested that meta variables were sorted before storage (this simplies the addition of new variables). However, I think it's important that the order of category items is use controlled (as at present). For now I have added an order
field (I didn't want to have to read the category definition when rendering a topic for view, always want viewing to be quick), but this is a rather crude approach.
A few thoughts on not having UseCategory
- There's no confusion of having fields (items) displayed that have no meaning and of setting them but forgetting to mark UseCategory as yes.
- If create via GO (edit, no existing topic) is done on a Web with categories, the user can first be asked for the category, at the same point choice of template could be done. In fact the two could be linked. Create from forms could clearly allow for setting of the category as well as the template e.g. template (topic) could contain the category.
This is the last item for TWikiReleaseSpring2001
that really needed doing before beta release. It will be good to get this in as all the meta information in topics will then be handled in a consistent way. The UseCategory
and location of definition are not finalised, so input in these areas would be very helpful. Given the need to get the beta release out, I'll keep close to current system if no concensus emerges for changes in the next couple of days.
- 19 Jun 2001
- "I shared Richard's confusion when I first looked at categories, now I use them a lot, but there is something about the current system, whether it's the terminology, the templates or the examples I don't know, that confuses. I'd be interested in other people's thoughts on this."
I agree that there is something about the current system that confuses. I don't know for sure, but I think it has to do with several things:
- The terminology -- calling it a "category table"
- The default display -- as a table -- it's big and cumbersome if you add a few categories, and I can't split it into pieces to show a little bit here and a little bit there (I'm a newbie -- see below)
- Maybe others
- "Also, does anyone want to see the retention of the view and edit templates for categories? Attachment formatting currently lacks this, my initial meta based category system also lacks this."
I want to keep the view and edit templates for a newbie reason -- I wouldn't know how to deal with categories without them, except manually. (I made extensive use of categories on the c2 and clug wikis, but handled them manually.)
Once I understand how to create, use, and display the TWiki "built in" categories (as opposed to anything manual I might create) in other than a table, I probably won't care (although maybe a way to get me to that point is to provide an alternate set of templates that displays (selected) categories as something like a bulleted list (that can wrap appropriately if the name or value of the category (or comments!
make it exceed the normal line length -- a display something like:
- optional Category name: Category value (optional comment)
Or, avoiding the options, just:
An alternate format I can see being useful would be displaying several categories on the same line (paragraph), comma delimited. I might use this for checkbox items (where several values are not unusual) or to make a "list" of several categories in a condensed space.
- 19 Jun 2001
On category definition can I suggest the following:
Example of classification definition, multi-value defined in category definition topic:
Example of classification definition, multi-value defined within it:
- Classification - a set of categories for a topic
- The possible classifications for a topic are given by the WebPreferences variable %CLASSIFICATIONS%
- A classification is defined in a topic (given by WebPreferences)
- This topic has an InterwikiPluginEarlyDev style table (see example below).
- A multi-value category can be defined in a category definition topic, or in the classification topic (which takes precedence).
- A multi-value category defined in category definition topic can be used in more than one classification
- I'm suggesting going for both ways of doing the pick list as both have advantages and complexity of doing both is low - as long as it's clearly documented I don't think they'll be much problem in usage.
- Classification seemed cleaner than category table. However, I guess classification and category might have the same meaning to most people, in which case this naming convention isn't a good way forward ...
- I've not used the | separator used in current template as this gives a rather strange looking table
- Type and Size are optional, as well as Items being optional
- Checkboxes has an extra option, show check/clear button, I thought this could be considered a separate type e.g. checkbox hasn't got them checkbox+buttons does.
A step in the right direction?
Randy talks about different formats for viewing categories (almost a skin for categories or maybe meta data in general). Do people also want to see the retention of edit template for categories?
- 19 Jun 2001
I think John's overall approach is good - define the categories/fields in one place, but allow multi-valued categories/fields to be defined separately.
My main issue remains the terminology - I really hope we can get away from both 'classification' and
'category', since I find they are both very confusing. The term 'category' is probably derived from the Wiki:WardsWiki
use of 'categories', but this is much less powerful in any case, and I don't think there's a compelling reason to stick with it.
This is really about defining structured fields, which may be used as categories to navigate to topics, but may equally well just store data about the topic (e.g. a future date when it should be reviewed and updated, or the price of a book in a book reviews topic - i.e. not really a category at all).
Everyone is familiar with filling out fields on paper, in web forms, and so on, and many are familiar with fields in databases such as Access. This 'category' feature lets us turn free-text TWiki topics into web forms that support structured data alongside the unstructured text. Hopefully everyone would agree with this?
So... We are defining 'form fields' of some sort - why not stick with this metaphor and define 'form = classification', i.e. a set of fields [category items currently], such as Author, Title, and Status, for use in a given topic). Specific topics would be linked to a given form, allowing multiple category tables per TWiki web.
Since this terminology is all so confusing (on first writing this response I mistook 'classification' for 'field'), here's a first cut at this terminology, mapping from John's earlier terms (shown with overstriking
onto suggested new ones:
Classification Form (or Form Template?) - a set of categories fields for a topic
- The possible
Classifications Forms for a topic (do you mean web?) are given by the WebPreferences variable %CLASSIFICATIONS% %FORMS%
- This makes sense but the use of 'topic' instead of web is confusing - the key is that any given topic can only use one form, although a web may have number of forms
Classification Form is defined in a special form definition topic (given by WebPreferences)
- This form definition topic has an InterwikiPluginEarlyDev style table.
- A multi-value
category field can be defined in a category field definition topic, or in the classification form definition topic (which takes precedence).
- A multi-value
category field defined in category field definition topic can be used in more than one classification form
Also, an 'item' in the definition tables above should probably be renamed to 'value' (as in 'field value').
I think this terminology is a lot clearer - just the phrase 'form definition topic' makes it reasonably clear what is going on even to a newcomer, and it ties in naturally with explaining that this feature makes it possible to include structured 'form-filling' data input as well as free text.
As a relatively recent adopter of TWiki, I can still remember the time when the whole 'category table' thing seemed very hard to understand, though really it's quite simple. It remains quite hard to explain to colleagues... If others agree that we should change this terminology, the best thing is to bite the bullet and do it soon.
To get away from terminology (phew...), I'd like to see that the Type of each field/category item is mandatory. It's easier to read the form definition topic if all types are explicitly specified, and the saving in typing is not much.
- 19 Jun 2001
Ah, yes, good! It's starting to sink in. Yes, we are adding "structured" data to the free-format data already in TWiki. And, we are putting that structured data into fields! And Category, Classification, and Topic are just three possible field names!
Yes, I sure like it, and think it will be much easier to understand and explain! (And it's getting more and more like AskSam
-- see http://www.clug.org/cgi/wiki.cgi?AskSam
So exactly which terms do I like? field, form, structured-data, free-form data, ??
Also, in response to John's question about edit templates -- again, since I don't know how else to edit the data, until I learn more, the edit template is useful. (Aside: I assume we'll always have the option to use combo boxes and check boxes to enter the field data -- just so we all spell "FeetYourUnderConstruction" the same way.)
- 19 Jun 2001
Excellent idea! A "category table" is nothing else then a "form". Lets follow up in FormTemplateSystem
All refinement of the spec should be done in FormTemplateSystem
. Add to this CategoryEditor topic only if you want to comment on the old spec and terminology!
- 19 Jun 2001