How to use ClassificationPlugin with a WikiWorkbench app.

Hi, I'm playing with WikiWorkbenchContrib, and getting to grips with how it works and the best practices for developing apps with it. I'm also playing with ClassificationPlugin and wanting to use it as part of apps that I'm working on.

First, what is the best practice for using ClassificationPlugin with a WikiWorkbench App? Should ClassificationPlugin be installed to the destination Web, or should it be installed to the WikiWorkbench App? Or should it be installed to none of the above, and I integrate it via my TopicTypes?

In some cases I want to use ClassificationPlugin fairly stock, and not change anything. Maybe in some cases I will want to change everything. Does this change the deployment method, or is it the same in both cases? Can I be selective about what I install from ClassificationPlugin etc to a web, and gain the other functionality through my own TopicTypes instead?

From the WikiWorkbench docs, it implies that everything like this is inherited, but I'm struggling to see how. Other than listing each 'parent' TopicType in the dataform, is that all I need to do?

I don't really need to change the UI/functionality of ClassificationPlugin itself, it's just integrating categories and tags into my app, and using them in a structured way. But, if in theory I did want to overwrite functionality, do I just do that via my own TopicTypes (and related dataforms/edit/view) and 'inherit' ClassificationTopic (or Tag/Category if I'm being more specific)?

-- JonMcCoy - 01 Mar 2024

I'm not sure I completely understand your questions here but will give it a shot. First, when you install ClassificationPlugin, it will automatically include the Applications.ClassificationApp. It will also include the template web _ClassificationTemplate which you select when creating a new web and it will include all the features of ClassificationPlugin. You then add your own categories, tags, etc to the web you created.

-- LynnwoodBrown - 05 Mar 2024

Hi Lynnwood,

I'll use acronyms here, as it gets confusing:

So I found that when I 'inherited' the ClassificationPlugin (CP) TopicTypes in my own LocalApps ' TopicTypes (LA), that when I installed CP to the test web, and then LA to the test web, it didn't work. At this stage I just had "ClassifiedTopic" etc in the TopicType definitions in the DataForms. As the topic names were local to the LocalApps web non of the paths to the inherited CP TopicTypes worked.

I considered changing the topic names to the full web/topic address ie ClassificationPlugin.xxxxxx, but it dawned on me that having the stubs within my app is a better architecture? I installed the CP TopicTypes I was using to the LA, and it all started working... This way any of my TopicTypes that reference CP, point to a stub - if in the future I need to change what they point to, I only have to change a single metafielcd in that stub, and they point to the right place...

I just wasn't sure (and still not) as to the best practice. I want access to normal ClassificationPlugin topics within whatever webs I install into, but also want access to my own TopicTypes that build on ClassificationPlugin...

Should it be:

1-- CP > LA > installed webs

2-- CP > installed webs & LA > installed webs

3-- CP > LA & CP > installed webs & LA > installed webs

I went with 3 - install CP into both... and that appears to work in all cases/scenarios.

I will add, as they were all existing webs, I didn't use the template _ClassificationTemplate web, I instead just manually clicked install on each WebTopic and TopicType I wanted (I think only 4-5, plus the "TopCategory" topic).

Hope this makes sense?

Jon

-- JonMcCoy - 05 Mar 2024

You did everything right.

Best practice is to

1. create a web Applications.LocalApps for your custom TopicTypes
2. if your custom TopicTypes are resusing parts of other applications, such as Applications.ClassificationApp then deploy required TopicTypes from Applications.ClassificationApp to Applications.LocalApps
3. only deploy those TopicTypes to the target webs that you realy want to create content for, i.e. if you don't want to create ClassifiedTopics in some web, then you won't need to deploy it

Note that there is no inheritance in the WikiWorkbench Framework. Inheritance creates particular problems in lots of common cases where TopicTypes inherit from multiple parents which brings in conflicts. Instead we use "mix ins". This basically means that the author resolves any conflicts manually. You basically list all formfields common in all TopicTypes that a custom TopicType is derived from. The formfield TopicType then lists all the "contracts" that your custom TopicType fulfills with regards to the data model it implements.

So far for the data modelling part. The other side of the story is the view and edit templates. These form a hierarchy of their by means of TMPL:INCLUDEing templates from derived TopicTypes. An application of that kind basically is a bundle of the TopicType definition, a ViewTemplate, EditTemplate and maybe a PrintTemplate for it. For example theses are:

• Applications.LocalApps.DocumentationPage
• Applications.LocalApps.DocumentationPageViewTemplate
• Applications.LocalApps.DocumentationPageEditTemplate

Let's say DocumentationPage is a ClassifiedTopic and adds some more custom formfield as in:

Name	Type	Size	Values	Description	Attributes	Default
TopicType	type	1	DocumentationPage, ClassifiedTopic, CategorizedTopic, TaggedTopic, WikiTopic
TopicTitle	text	75		enter a title for this topic
Summary	text	75		short description or tagline	c
Tag	tag	30		keywords for this topic	c
Category	cat	1		categories this topic is field to
Responsible Person	user	30
Review Date	date2	20

The DocumentationPageViewTemplate will look like this:

%TMPL:INCLUDE{"Applications.ClassificationApp.ClassifiedTopicView"}%

%TMPL:DEF{"beforetext"}%%TMPL:PREV%
%RENDERFORDISPLAY{
   exclude="^(TopicType|TopicTitle|Summary|Tag|Category)$"
   editable="on"
}%

%TMPL:END%

The DocumentationPageEditTemplate follows a similar pattern:

%TMPL:INCLUDE{"Applications.ClassificationApp.ClassifiedTopicEdit"}%

%TMPL:DEF{"formfields"}%%TMPL:P{"detailstab"}%%TMPL:PREV%%TMPL:END%

%TMPL:DEF{"detailstab"}%%TAB{"Details"}%
%RENDERFOREDIT{
   form="%TMPL:P{"formdefinition"}%"
   exclude="^(TopicType|TopicTitle|Summary|Tag|Category)$"
}%
%ENDTAB%%TMPL:END%

Once that is in place in your Applications.LocalApps go to DocumentationPage and deploy the new TopicType using the "Install" button. From there on you should be able to create new topics of type DocumentationPage in the target webs.

Next best pracice for TopicFunctions and queries on TopicTypes is to always filter by TopicType, i.e. not by data form name.

For example, say you want to list all tags of all topics in your web then use:

%DBQUERY{
   "TopicType=~'\bTaggedTopic\b'"
   header="..."
   format="   * [[$web.$topic]]: $displayValue(Tag)"
   separator="$n"
   footer="..."
}%

This will include all topics whose type implements the TaggedTopic contract, like your custom DocumentationPage or any other TopicType that is going to materialize in your target web in the future.

-- MichaelDaum - 10 Mar 2024

Thanks Michael!

And thanks for the full explanation, very useful!

1) I've found that the TopicType Values have to also be in the Default column, otherwise they're blank when I save the topic. Is that correct?

2) I think I've figured it out, but is the "c" attribute just to show the fields on the "New Topic" wizard form? Are there any other attributes, other than "h" for hidden?

3) In regards to mixins, is there any mechanism or concept that would work to actually merge multiple data forms automatically? I've tried DBCalls, Filter, Include etc, and whilst I can see the table viewing the topic template, it doesn't work when used as a dataform. I'm assuming that data forms are not rendered TML topic content, but are extracted (Regex?) from the topic.

I like the idea of using the Dataform topic type to store the data forms in, and then mix them into the different topics that use them. Sadly it doesn't work at present, but would be nice.

I am using DataformAttributes to ensure options are kept DRY and I minimise the chance of inconsistent editing/creation. Though, it does of course open the possibility to have common fields but with differing attributes based on the topic type itself.

4) On the basis of mixins, what is best practice; to have one topic type that uses a field to identify what kind it is, or multiple topic types with identical data forms, but one for each kind? I have some topic types that differentiate based on hierarchy, but are just the same thing with the same data models. It seems to make sense that there is a prototype topic and each kind is its own topic type "inheriting" from the prototype, though it seems wasteful as they're the same thing, and just need identifying as such. The frustration of course is the repetition of the dataforms and chance for mistakes. Much of what I'm doing is evolving and isn't a finalised upfront design.

5) You mentioned a PrintTemplate - is that setup to work? Will a print template be selected by AutoViewTemplate for print views? I need to generate various PDF forms using Weazy so that'll be useful to have.

6) To confirm, Render... objects are basically reusable widgets related to the TopicTypes, that can be used within the View/EditTemplates, but also any other topics that might want to (ie dashboard pages)?

Thanks Jon

-- JonMcCoy - 11 Mar 2024

On (1): please use the formfield type "type" instead of "label". Then the redundant values in the default column can be spared.

On (2): there is M for mandatory fields

On (3): for now the easiest way is to copy&paste manually and resolve duplicates as you see them. Low tech I know but sometimes the best

On (4): only create new TopicTypes if they differ in terms of data model; if they are the same but only a different document type of some sort, then differ them otherwise. TopicTypes are only there to differ types of topics have a different set of formfields. For example, you may very well differentiate topics by using categories. That way they are located in different subject matter areas of sorts.

On (5) Yes. Disable AutoViewTemplatePlugin and replace it by AutoTemplatePlugin, i.e. do not use both.

On (6) Correct. Think of them as reusable macros.

-- MichaelDaum - 11 Mar 2024

Thanks Michael!

1) aha!! brilliant!

2) so just c, h and M?

3) no problem - not knowing if there is a method I was overlooking is much worse! if I know that's the only way, then that's the only way.

4) okay, that's good logic. Using categories is a nice solution too... I'm using multiple categories for some topics (for example classifying using two or three hierarchies). Got me thinking now... I may need to create some custom CategoryTopic TopicTypes so I can have custom category views to show dashboard style overviews of child topics...

5) Will check!

6) Great! Are there any other components or things I've missed out? I'm aware of WikiTool pages, that I understand are prebuilt tool pages, such as indexes, or stats.

A) With regards to Dataforms, are there any reliable methods of storing multi-line data? If not, is there any reliable or inbuilt method of splitting the main body content into multiple editable/easily parsed sections?

Similar to how there are tabs with the View/Edit templates you used as demos above, it would be useful to have multiple body section tabs (maybe as simple as splitting each H2 into it's own tab, or using a line break etc). In reality they don't need to be actual fields, but just rendered in different ways on the final page, whilst keeping it simple to end users and not requiring any HTML.

B) Do CategoryTopic 's and ClassifiedTopic 's use the TOPICPARENT value to determine their parent category topic, or do they just purely use the Category Meta field for that? Is the TOPICPARENT field 'safe' to use for other structures (like question 4 above)?

C) How do Sub Categories work? I thought I could have a template structure that might get repeated under other categories... It works, but then the ViewTemplates don't work as they link back to the wrong places... Breadcrumbs look right, but links are wrong...Is that fixable by me creating a custom Category TopicType and ViewTemplates, or is that very much not going to work as I scale up?

As an example of what I did, if I have a few standard sub-categories like "Unit", "Character", "Vehicle" (their parent category something like "TemplateCategory", I had those within the App itself. Then for each Category that had those sub-categories, I added that category tree as a Sub-Category. It shows up perfectly but the links don't work for navigating between the category views.

Am I better off just having a dashboard style Category ViewTemplate that splits off the types of child topics into different lists etc, or is implementing sub-category templates like this the right way, albeit with some fixes required to the template links?

C) As I learn more and more, I want to try and document this information... What's the best way to improve the documentation, is that via Github and submitting a pull request? Assuming that the Foswiki.org site is just a mirror of the core Github and not the source of docs etc?

D) Where's the best place to have more flowing discussions? I've joined the email threads and haven't seen any traffic...

-- JonMcCoy - 11 Mar 2024

Hmmm, also, "type" as form field type doesn't work. It just gives a red error "MISSING TYPE type".

Maybe you have a newer version/patched version? The Github version is 5 years old. I've searched the code, and can't find any new field definitions in WikiWorkbench...

-- JonMcCoy - 11 Mar 2024

Commenting is disabled while not logged in