Forum OpenACS Q&A: XOWiki and Categories

Posted by Carl Lemp on 01/28/21 05:44 AM

I've started looking into XOWiki and the possibility of adding metadata to pages using categories. I see that categories from the site-wide category trees can be added to Pages, PageTemplates, and Forms. However, I could not select categories from the entry form for PageInstances or FormPages.

Is this the intentional design of XOWiki or is there some setting that will enable categories on individual PageInstances and FormPages?

If I create a FormPage to provide a blank template for the entry of some type of information (a news article for example), the template probably does not need any category metadata assigned. I was expecting that it would only be FormPages with the individual news articles that would need categories assigned since they are the pages with news content and a topic to be categorized.

If the current design is intentional, am I misinterpreting the intent of either categories or Forms/FormPages?
Thanks,
Carl

2: Re: XOWiki and Categories (response to 1)

Posted by Gustaf Neumann on 01/31/21 11:56 AM

The old-style ad_form-based category handling (as used for ::xowiki::Page) has several shortcomings: These categories are inserted in every edit page, on every page, the same categories are used, the display style and position can't be changed, when multiple category trees are used, this is a pain.

Therefore, form pages don't follow this hard-coded approach, but allow to include arbitrary categories from arbitrary category trees. The control for category mappings is per-form, and not by xowiki instances. By creating instances of form with category mapping, only these pages of an xowiki instance will have these categories included. The display style is controlled via the form-field class (can be subclassed by applications), it allows the developer to show the category mapping as well in the view mode, etc. When exporting pages to different OpenACS instances, the categories trees will be created at the target machine, when not available there, etc.

Assume we have a category tree "audience" defined. One can use this category tree for form-field classes derived from "enumeration" (having options, i.e. label /internal value pairs), such as such as "checkbox", "radio", or "select") by setting "category_tree=audience" in the form constraints. In these cases, the category tree is used as a source for filling the options. When saving such a page, the usual category mapping / notification etc. will happen. One can certainly use several of these category fields per page.

Example:

Form:

<form>
@myselect1@
@myselect2@
</form>

Form constraints

myselect1:select,default=advanced,category_tree=audience
myselect2:checkbox,horizontal=true,default=advanced,category_tree=audience
@cr_fields:hidden

When more control is needed, one can use this approach as well in xowf, where e.g. the display of categories can be different per state in the life-cycle of the page, or per role of the user, etc.

Does this help?

3: Re: XOWiki and Categories (response to 1)

Posted by Carl Lemp on 01/31/21 05:26 PM

Thank you Gustaf.
That definitely helps and is even better than the original XOWiki use of categories for my purposes. I have not looked at the form constraints yet but I will now.

In your post, what does the @cr_fields:hidden do? I looked in the documentation and found this:

    The form constraints refer not only to form.fields, but use a few 
    special field names starting with an at-sign for  other purposes as 
    well.

    @cr_fields: assign properties to all content repository fields
    For example: @cr_fields: hidden is a short form of
    _name:hidden _creator:hidden _title:hidden _description:hidden nls_language:hidden

    @fields: symbolic name for all user fields
    @categories: turn categories optionally off for form entries of  this form
    @table: specify, which form fields should be included in the summary table

but I'm new to OpenACS so that didn't help me understand it. The only use I found in the XOWiki source was in:

  form-usages instproc generate_voting_form

and that didn't help either.

Thanks, Carl

4: Re: XOWiki and Categories (response to 3)

Posted by Gustaf Neumann on 01/31/21 08:06 PM

Dear Carl,

i've reformatted your posting lightly to increase readability.

Concerning @cr_fields: The term refers to the fields of the content repository, which are part of every content repository entry ("name", "title", "description", "nls_language", and also the "creator" field, which is defined in xowiki::Page). Since form pages extend these pages with arbitrary additional attributes, these native names of the content repository are prefixed with an "_" to allow same-named fields for extending as well. So, instead of defining in the form_constraints attributes for all of these fields, one can use the short-form @cr_fields. This is just a convenience for the developer.

The meaning of "hidden" in this case is, that when one edits such a page, the edit page does not render input fields, but hidden fields. If "omit" is specified, these fields will be omitted.

if you look for the source code, see e.g. "xowiki-www-procs.tcl", where the value of this entry is passed in `-field_spec`. Typically, this value is set in user-level forms.