Item2336: BuildContrib should automatically set topic parents

Priority:	CurrentState:	AppliesTo:	Component:	WaitingFor:
Enhancement	New	Extension	BuildContrib

Related: Item2293.

Motivation

Navigation mechanisms based on topic hierarchy expose Foswiki's extremely poor usage of topic parents.

SvenDowideit has already gone some way towards cleaning up parentage of topics shipped with the core distribution, but the situation with non-core plugins in the System web can only realistically be cured by automating it in BuildContrib.

Implementation

BuildContrib should call a new tool, /tools/autoparent, which it would apply to all topics shipped in Contribs, Plugins and Add-Ons.

/tools/autoparent would also be useful for deployment of hierarchies to existing webs, such as the proposed hierarchy of Web* topics in Tasks.Item2293. -- PaulHarvey - 10 Nov 2009

Plugins

These rules would apply within any web where the rules are being applied (all webs containing topics shipped with a plugin).

• System.Plugins should be the parent of ThePlugin topic .
• !ThePlugin topic should be the ancestor of AllOtherPluginTopics:
  • So topics that were descendants of a topic that has now been automatically parented to ThePlugin topic should not be modified.
  • Any topic after the !noautoparent directive in the MANIFEST file should not be auto parented

Contribs & Add-ons

Same policy as for Plugins

Example

• Plugins
  • ThePlugin
    • ThePluginFAQ
    • ThePluginCookbook
    • ThePluginExamples
    • ThePluginSimpleExample Changed -- Main.PaulHarvey - 10 Nov 2009
    • ThePluginBigExample Changed -- Main.PaulHarvey - 10 Nov 2009
    • SomeForm
      • SomeViewTemplate
      • SomeEditTemplate
      • SomeTemplateTopic

It's not necessary for BuildContrib to enforce a complex hierarchy. The only things it should do:

1. Ensure that the ThePlugin topic is parented to Plugins
2. Other topics shipped with the plugin are descendants of ThePlugin topic...
3. ... except for topics below !noautoparent in the MANIFEST

-- Main.PaulHarvey - 10 Nov 2009

Exclusions

As with !noci, there should be a directive in the MANIFEST that allows prevention of autoparenting when building a release.

Proposal: !noautoparent

Web* topics

Web* topics which may or may not be shipped with a contrib/plugin should be parented to WebThis, see Item2293

• WebHome
  • WebTopics Changed 10/11/2009
    • WebSearch
      • WebSearchAdvanced
    • WebChanges
      • WebNotify
      • WebAtom
      • WebRss
    • WebStatistics
    • WebIndex (? these ...
    • WebTopicList ... two need rethinking ?)
    • WebPreferences
    • WebCreateNewTopic
    • WebLeftBar

The placeholder topic (WebTopics) should be a "dashboard" area that should present the range of functions available to the user in a logical manner. This might mean re-thinking the content and purpose of some of our existing topics (Eg. WebIndex vs WebTopicList). For 1.1, I think it is reasonable to kill/rename/re-purpose some of these topics. But I would like to apply some sort of solution for 1.0.x as well. -- Main.PaulHarvey - 10 Nov 2009

---

More to come, as I work on this. See Development.CleanUpTopicParentage

-- PaulHarvey - 07 Nov 2009