How to use WikiWorkbenchContrib

I am confused on how to use the https://foswiki.org/Extensions/WikiWorkbenchContrib.

I understand the value of using this but it isnt obvious how to to even use the Classification App.

Can some outline how to create a simple App , for example a ContactsApp (Name, Address,Telephone, Email etc)

Or point me to an example?

-- LlewelynJones - 09 Jan 2021

I can give a short intro on how I use it and perhaps that would be enough to get you started. First off, I would go to Applications/WebHome and use the form to create a new WikiApplication. Personally, I usually create one called LocalApps where I store a number of applications used by the site (rather than creating a separate application web for each application).

Next, using your example of a Contacts app, I would create a new TopicType called "Contact" in my LocalApps web. The topic template for TopicType topics will include a basic data form definition which you would modify to suit your needs. (BTW, don't forget to check MoreFormfieldsPlugin for field types that might be useful in your application.) Once you save the topic, you'll see that it includes a form to install your new application into one of your working webs (where you'll create content). Edit the topic again and take a look at the "Details" tab. You'll see options to select an icon for you app, plus a edit template and template for new Contact topics (neither of which we've created yet). You'll also find option to define how new Contact topics are named (the default being to generate a WikiWord name from the TopicTitle form field). In the case of your Contact topic type, you might want to define a "derived" name that combines FirstName and LastName fields.

You may or may not need to create a custom view and/or edit template for your Contact topic type. This depends on whether the default view for your new topics display things to your liking and whether you have some special requirements during editing that the default edit template doesn't provide for. If either are these are the case, then go to Applications/LocalApps/TopicView and create a view or edit template using a name like ContactViewTemplate. Assuming you have AutoTemplatePlugin enabled, this view template would automatically be used to display any topics using the Contact data form. If you want to create a special template for new Contact topics, go to Applications/LocalApps/TopicTemplate and create your topic template there. If you do create a custom edit template for topic template, go back to your Contact topic, edit it and select your Edit and topic templates in the "Details" tab.

After you've installed your new Contact TopicType into a web, you'll see that the Contact topic includes a form to create new Contact topics. The form calls upon Applications/RenderSimpleTopicCreator and if you look at the documentation on that page, you'll see that there are quite a few options or parameters for customizing that form without needing to create your own form. You can change these parameters by editing Applications/LocalApps/Contact and adding/modiying the parameters in the INCLUDE macro that points to RenderSimpleTopicCreator.

Finally, I will often create a topic to define special page elements used in Contact-related topics. This would be a Applications/LocalApps/TopicFunction topic called RenderContact. For example, perhaps I want to define a block that displays topics edited by that Contact. I might create a named section in RenderContact call "contacts_topics" and then add a INCLUDE referening that topic/section in Applications/LocalApps/ContactViewTemplate. This would require some understanding of how Foswiki skin/view templates work which is more than I want to go into here but I hope this give a direction to start.

One more little detail: I ususally add a search under documentation in the Applications/LocalApps/Contact topic to list the other topics associated with this application. Here's a simple search for that:

%SEARCH{"name ~ '*%TOPIC%*'"
   type="query"
   nonoise="on"
   header="*See also:* "
   excludetopic="%TOPIC%"
   format="[[$web.$topic]]"
   separator=", "
}%

I hope this is enough to get you started. Please feel free to ask for additional clarification & guidance. If you would like to see an example, please contact me and I could point you to an example from one of the public sites I manage.

Good luck! I think you'll find WikiWorkbenchContrib to be quite a powerful frameword to rapidly create Foswiki-based custom applications.

-- LynnwoodBrown - 09 Jan 2021

Reading your question again, I notice your comment about being unclear about how to use ClassificationApp so let me make a few comments about that. The easiest option for using the features defined by that application is simply to create a new web using the _ClassificationTemplate web template. This creates a web that has pre-installed the TopicTypes (and other components) that incorporate the special "Tag" and "Category" fields provided by that application.

If you want to add the ClassificationApp features to an existing web you can do that also pretty easily. What you would do is go to the Applications/ClassificationApp/ClassifiedTopic topic type and use the form provided there to install this topic type into your existing web. You would then need to add "Tag" and/or "Category" fields into any data forms used in that web. If you went this route, you might need to add some other special topics that are included by default in the _ClassificationTemplate web template but let's leave that for later discussion.

-- LynnwoodBrown - 09 Jan 2021

Hello Thank you for your reply. It is very helpful. Yes I would like to have a look at some of your examples if possible.

I followed your instructions and here is what I experienced

• Created a new web LocalApps of type WikiApplication
• Created a new TopicType called "Contact" in my LocalApps web.
• Added fields : FamilyName, FirstName, TelephoneNumber to the new Contact page
• In Details added an icon
• In Details added ContactAUTOINC0 as Topic Name Prefix:
• Installed the new Contact TopicType into a test web

In the TestWeb I now have the topic Contact

• This has a New button and a table with fields Title,Summary,Application,Changed
• If I click on New I am asked "Create a new Contact", I give a Title JohnDoe and Submit
• Now I get an empty edit session for JohnDoe and I can add text. The Form tab shows the form fields (FamilyName, FirstName, TelephoneNumber)
• On Save the topic JohnDoe is created and is achild topic of Contact
• There is no reference to the prefix in the topics created (like JohnDoe)

If I now go to Contact page I still see the empty table with fields Title,Summary,Application,Changed

1. What is this table in the context of Contact page?
2. Is it possible to use the incremental AUTOINC0 in all this?
3. Am I supposed to see a list of users that I have entered?
4. Is there an option to offer the user a form for a New contact directly rather than going to the Edit text area?

Thanks again for your feedback

-- LlewelynJones - 11 Jan 2021

Apologies for delay in following up on your questions. Looks like your making good progress. Here's my notes/responses on the points you posted above:

• On the point describing use of ContactAUTOINC0 for naming convention (under "Topic Naming Mode"), I think you want to use the 2nd option labeled "Template" and put your naming pattern there. It should work correctly then.
• In your LocalApps/Contact page, did you modify the INCLUDE parameters passed to RenderSimpleTopicCreator to select the fields you want to provide when creating new topic? You would add something like FIELDS="FamilyName, FirstName" . Again read the docs in RenderSimpleTopicCreator to see all the options you have for modifying the form for adding new Contact records.
• To modify the table displaying all your contact records, note the INCLUDE that points to Applicaitons.RenderTopicsOfType. Again, look at the documentation on that page to see options for modifying what's displayed in that table. The most basic change you'd probably want to make is specify the fields to to be displayed. You'll probably want to add a parameter something like Fields="FamilyName, FirstName, Changed, Author" . Note that there also provisions for changing the displayed name for these fields so, for example, the "FamilyName" column header could display simply "Last" by adding parameter FamilyName_title="Last" .
• In order to disable the text area when editing your Contact records, you need to create a very simple Edit template. So as I described previously, go to LocalApps/TopicView and create a new edit template called ContactEditTemplate. When you first create that topic, it will contain a single template include that says %TMPL:INCLUDE{"view"}%. Change that to %TMPL:INCLUDE{"editform"}%. This is the base template that defines the edit for without the text editing part. After you've created this template, go back and edit LocalApps/Contact and under the "Details" tab, select your new edit template for the "Editor" field.
• Let me make one more point about your new edit template to point you the direction of how you can use these templates to easily customize other aspects of that screen. On your server, go to the templates folder of your Foswiki installation and look for the editform.natedit.tmpl (I'm pretty sure that's the one but it depends on your skin setting which the edit form will inherit). By default, your new edit template simply includes this base template but you can over-ride any page elements that are defined therein (or in other templates this base template points to) but adding your own TMPL:DEF element to your custom edit template. For example, let's say you wanted to modify the title displayed in the window tab when your editing a contact. editform.natedit.tmpl contains a line that reads %TMPL:DEF{"title"}%%TOPIC% (%MAKETEXT{"edit form"}%) %TMPL:P{"titlesep"}% %WIKITOOLNAME%%TMPL:END%. Copy that line into LocalApps/ContactEditTemplate and modify it to read read something like %TMPL:DEF{"title"}%%MAKETEXT{"Editing Contact")%%TMPL:END%. Perhaps not a very useful change but I just wanted to demonstrate the idea. Also note the verbatim html tag surrounded by %<nop{...}% in the template. These don't have any effect in the template but simply make the display look better in your view template.

Let me know how it goes. If you'd like to view some of my private examples, drop me an email

-- LynnwoodBrown - 14 Jan 2021

Thanks for the feedback, I've made some progress. I am almost there for my app and will share my fulle experience when ready.

I have a couple of further questions

If I create the topic name like ContactAUTOINC00 is it possible to use the topic name in the Applications.RenderTopicsOfType ? Or somehow make TopicTitle to be the same as the topicname?

I would like to include the AUTOINC00 number in the form (TopicID) in order to allow the navigation to next or previous pages. So if Im on the page Contact02 the previos and next page links would point to Contact01 and Contact03 . I tried as follows in the form but the values of TopicID remain empty. Is this the right approach?

| *Name:*| *Type:* | *Size:* | *Values:* | *Description:* | *Attributes:* | *Default:* |
| TopicType | label | 1 | Contact| topic type  | | |
| TopicID | text| 3 | AUTOINC00 | topic id | h | |
| TopicTitle | text | 75 | ContactAUTOINC00 | title of this topic | h | |
| LastName | text | 75 | | family name | c | |
| FirstName | text | 75 | | first name | c | |
| Summary | text | 75 | | short description or tagline | c | |
| Status | select+values | 1 | Pending, Under Revision, Approved | Various status |
| Author | text | 75 | | application author | h | %WIKINAME% |

-- LlewelynJones - 21 Jan 2021

Regarding using the topic name in Applications.RenderTopicsOfType, I believe you can use "Topic" in the FIELDS parameter. Take a look at JQDataTablesPlugin#Special_column_names for the list of special field references which could be used in the FIELDS parameter passed to Applications.RenderTopicsOfType.

In regard to using AUTOINC for an extra field, let me first correct a misconception you seem to have. It does nothing to include ContactAUTOINC00 in the data form you presented above. The only time that convention is used is within an html form used for creating a new topic (see TemplateTopics#AutomaticallyGeneratedTopicname for more info).

So then, let see what other options there would be to capture the incremental number used in your topic name. One option I see would be to use the autoinc field type provided by MoreFormfieldsPlugin. However, I suspect that you might run into a situation where these numbers get out of sync with the topic numbering since they are completely separate mechanisms even though they serve superficially similar functions.

A better option, I think would be to extract the number from the topic name directly as you need it. You can do this with either SpreadSheetPlugin or FilterPlugin. Personally, I prefer FilterPlugin to do this kind of thing. The marcro would look something like this:

%EXTRACT{text="%TOPIC%" pattern="Contact([0-9]+)" format="$1"}%

You could use this within a larger macro that could be included in your Contact topics which renders links to the previous and next contact topics however I think this is getting past the scope of the question at hand.

Good luck!

-- LynnwoodBrown - 22 Jan 2021

Have a look at the id formfield type of MoreFormfieldsPlugin. It does exactly that: extract the autoinc number of the topic name.

-- MichaelDaum - 22 Jan 2021

Thanks for the feedback, the EXTRACT option works very well as do the fields of the MoreFormfieldsPlugin.

Concerning the "Tag" and "Category" fields are these only available in the ClassificationApp ? I mean how do you suggest these be incorporated into a Contact Application if, for example, it is necessary to categorize a person belonging to one category: ("Teacher","Student",Ex Student","Administrator") ?

Or if tags are to be used for teaching subjects (biology, math, chemistry etc )

Thanks again

-- LlewelynJones - 28 Jan 2021

To utilize the Tag and Category features of ClassificationApp, just add Tag and/or Category fields to your Contact data form. (See Applications/ClassificationApp/ClassifiedTopic for examples for these field definitions.) Your examples of use of each field make sense to me. Generally, the way I think about it is that Categories are useful for "top-down" organization via pre-defined categories (you examples on known categories like Teacher and Student are good example). Tags, on the other had, are useful for "botton-up" organization where the groupings might not be clear up front, so you just add the tags as you go and let things sort themselves out.

-- LynnwoodBrown - 28 Jan 2021

I have been away and just got back onto this. I made some progress and was able to get the TAG to work but Im still struggling with the Category option.

I have a question about the VIEW template for each Contact entry. By default the topic text is shown and then underneath the Data Form. Above you mentioned that Its possible to create a custom view in Applications/LocalApps/TopicView . If i create the ContactViewTemplate it includes %TMPL:INCLUDE{"Applications.WikiTopicView"}% and if left like this I just see the Contacts topic text and no longer the Data Form for each entry. Im not sure what is going on here.

Could you explain how to change the Contact views?

I have added a small summary in the Sandox for how to create a simple contacts application ContactAppExample. It may be of use to others

Thanks again

-- LlewelynJones - 25 Feb 2021

To change the way the Contact is viewed I created a ViewTemplate as described above by Lynnwood. When this is created is contains a line Applications.WikiTopicView. The problem I had was that this topic contains the line

%TMPL:DEF{"form"}%%TMPL:END%

And this removes the form from the Contact view.

So to change the View as I wanted I removed the line Applications.WikiTopicView but used its content in my own ViewTemplate.

Other %TMPL:DEF can be overridden in this topic to change the view as needed.

-- LlewelynJones - 10 Mar 2021

Llewelyn - I think what you want to do is in the TMPL:INCLUDE macro that references Applications.WikiTopicView, simply change that to view which will reference the base view template for whatever skin you're using. Then you can over-ride any specific page template elements you want by adding %TMPL:DEF to your view template. For example, you could copy any of the definitions you find in Applications.WikiTopicView and add them to your template.

-- LynnwoodBrown - 10 Mar 2021

Thanks for the feedback

For the question of the having previous and next contact buttons assuming that all the topics of the Contacts are named ContactAUTOINC0 then the next and previous buttons can be created as follows

[[Contact%CALC{$INT(%EXTRACT{text="%INCLUDINGTOPIC%" pattern="Contact([0-9]+)" format="$1"}% - 1)}%][%ICON{arrowleft}% prev]]

[[Contact%CALC{$INT(%EXTRACT{text="%INCLUDINGTOPIC%" pattern="Contact([0-9]+)" format="$1"}% + 1)}%][%ICON{arrowright}% next]]

Now how to include these?I tried to create a new %TMPL:DEF{"mybuttons"}% above code goes here%TMPL:END%

and then TMPL:P{"mybuttons"} but I dont see them

What would be the correct way to include this in the ViewTemplate ?

Also when an App is created it can be installed on a web. Following this how can several instances of the App be used in the same web, for example if several users want to have their own Contact DB?

-- LlewelynJones - 12 Mar 2021

You need to figure out where you can insert your TMPL:P{"mybuttons"}. There are template elements called "beforetext" and "afternext" which might be good prospects. Take a look at TMPL:DEF{"beforetext"} in Applications/WikiTopicViewTemplate to see how that one is used. You could put that same definition in your custom view template and add TMPL:P{"mybuttons"} at the end. That would place your prev and next buttons right above the topic text.

-- LynnwoodBrown - 12 Mar 2021

Thanks for that, I will check it out

The Summary table allows for sorting on each column. However this does not seem to work.

For example on Applications/ClassificationApp/DocuTopic if you click on the Summary column the sorting is random Have you noticed any issues with sorting ?

-- LlewelynJones - 15 Mar 2021

I'm not seeing that problem in a couple of installations I checked. Check in configure {JQDataTablesPlugin}{DefaultConnector}. I have mine set to dbcache. If you have it search to search, then perhaps it's not providing the correct sort/order parameter.

-- LynnwoodBrown - 15 Mar 2021

I had it set to search (default). The sorting was corrected when I set it to dbcache.

Many many thanks again.

-- LlewelynJones - 15 Mar 2021

Is it possible to have several instance of the same App in one web? For example if several users want to have thier owen Contact App ?

-- LlewelynJones - 15 Mar 2021

Without knowing exactly how your Contact App is set up, I suspect that they any search for that form or topic type would show all the results. I think what I'd probably do in that case is add a field in the Contact data form to identify who's contact it is and then modify the form for posting new contacts to add the current user to that field. I can envision a "MyContacts" page that automatically filters for the current user's contact records and automatically assigns any new contacts created to them as well.

-- LynnwoodBrown - 15 Mar 2021

If I create contact entries for a user in the form % WIKIUSERNAME%Contacts , what should be the entry in the FILTER as defined in the TopicType. For example here I define a FILTER but I don't get any output. However if I use the FILTER in the form text box then I get the correct results.

---++ Topics of type '%TOPIC%'
%STARTINCLUDE%
%DBCALL{"Applications.RenderSimpleTopicCreator"
  LABEL="%TRANSLATE{"Title"}%"
  BUTTONTEXT="%TRANSLATE{"New"}%"
  TEXT="%TRANSLATE{"Create a new [_1]" args="%TOPIC%"}%"
  VALUES=""
  FILTER="%WIKIUSERNAME%Contacts"
}%

%DBCALL{"Applications.RenderTopicsOfType"
   FIELDS="TopicTitle, Summary, Status, Created, Creator, Changed, By"
}%

-- LlewelynJones - 25 Mar 2021

First, I'm assuming you meant to put the FILTER paramter under the DBCALL to RenderTopicsOfType since RenderSimpleTopicCreator doesn't use that parameter. Next, you'll need to provide a TYPE parameter to RenderTopicsOfType. Take a look at the query parameter in RenderTopicsOfType which starts with TopicType=~'\b%TYPE{default="%BASETOPIC%"}%\b'. If you don't define TYPE, it defaults to the BASETOPIC which you don't want in your case.

Next, you're got a couple of options for linking the contact to it's "owner". You could identify's a users contacts by filtering for the Creator field or else the parent field (since RenderSimpleTopicCreator defaults to making the base topic the parent of new topics). Again, looking at the query in RenderTopicsOfType, you'll notice that FILTER (if defined) is simply tacked on to the base search, so it requires a complete search string in the syntax of DBCachePlugin. So the two filtering options I mentioned above would be something like Creator =~ '%WIKINAME%' or parent =~ '%WIKINAME%Contacts'. So, all together, your call to !!RenderTopicsOfType might look like this:

%DBCALL{"Applications.RenderTopicsOfType"
   TYPE="Contact"
   FILTER="parent =~ '%WIKINAME%Contacts'"  (NOT %WIKIUSERNAME% since that macro includes the web reference.)
   FIELDS="TopicTitle, Summary, Status, Created, Creator, Changed, By"
}%

BTW, you'll also need to add the TYPE parameter to your call to RenderSimpleTopicCreator so that it assigns the correct TopicType.

You'll also want to consider how your contact topics are named. By default RenderSimpleTopicCreator uses the TopicTitle field and creates a wiki word topic name. However, you can modify this behavior by editing the Contact topic type (where the data form is defined) and change the "Topic Naming Mode" under the "Details" tab. You'll need to do this since your Contact data form doesn't even use the TopicTitle field. You'll probably want to put there [name=FirstName],[name=LastName] which will combine the first and last name to create the wiki word topic name.

Finally, you might consider adding some string to the topic name that links it to the creator. Otherwise, two users who tried to create contacts with the same first and last name would conflict. You can do this using the "Topic Name Suffix" under the Details tab in the Contact topic type (right below "Topic Naming Mode" mentioned above). My first thought would be to define an INITIALS preference in each %WIKINAME%Contacts topic with that users initials. Then put %INITIALS% into "Topic Name Suffix" field. Then the topics would be named using first and last names plus the creator's initials.

Keep in mind that all of this will automagically be picked up by RenderSimpleTopicCreator!

-- LynnwoodBrown - 26 Mar 2021

Commenting is disabled while not logged in