TWikiFns and Macros

_ The proposal to include TWikiFns support triggered the following discussion._

-- MeredithLesly - 03 Jul 2006

Discussion

Imho, the current amount of tags needs to be revised with regards to their coding quality and their usefulness. Am I the only one thinking that for example the TitleTag is completely dispensable.

• Indispensable, yes if you want to copy current TWiki capabilities. But I do hope you will see the value in referencing topic by title. If not, please review TopicDisplayName. This is the feature that will solve usability problems, improve findability and lift TWiki out of geekyness. -- ArthurClemens - 28 Jun 2006
• So far as I've looked at the code of the TitleTag it is not matching TopicDisplayName, besides being feature incomplete and plain buggy. I really do like TopicDisplayName and will comment there furtheron. -- MichaelDaum - 28 Jun 2006

• I probably shouldn't have uploaded TitleTag, as it was experimental and, as noted, incomplete. I was hoping to get some feedback, but shrug. And, as should be obvious, adding syntax will require a full-blown plugin anyway. (I dunno who suggested extending TitleTag, but it wasn't me.) I'd still rather have the topic name alone in the titlebar than what appears there now.
  • Normally Dev topics are created for the purpose of collecting feedback (i.e. TitleTagDev) - are you considering another mechanism for collecting feedback on the tags? If this is the case you should case mention it in the tag topic (it says Feedback: http://TWiki.org/cgi-bin/view/Plugins/TitleTagDev at present) -- SteffenPoulsen - 29 Jun 2006
  • No, I wasn't considering another mechanism since, AFAIK, there isn't one and I'm not inclined to invent one (even though it might be sensible for not-ready-for-prime-time plugins/tags). That's why it was put on twiki.org instead of just going into svn. -- MeredithLesly - 29 Jun 2006

There are a handful of TWikiTags I use extensively. One very nice thing about about them is that they provide a quick way to add user-friendly features with little or no cost, thereby lowering the geekiness threshold considerably. For example, %CHILDTOPICS% is a lot easier to use than whatever the hideous SEARCH equivalent would be. My extended MetasearchTag is a lot more useful than the TWikiVariable since, generally speaking, one has to do a SEARCH to get usable results. (Although in this case it should replace the existing METASEARCH module.) I wrote FallbackPlugin largely due to the complex solutions being offered to Lynnwood but, as it only implements a tag, has beeen redone as FallbackTag.

I suspect there's a ton of useful but barely comprehensible idioms, such as arcane search strings, that would be much better done as tags. To a large extent it comes down to whether people really care about making things easier for ordinary users.

-- MeredithLesly - 28 Jun 2006

Now that you speak about CHILDTOPICS being more friendly than the equivalent search... can anybod spell "MACROS"? It's mentioned somewhere as something that TWiki is lacking.

• What should MACROS do? -- ArthurClemens - 29 Jun 2006
  • Not require perl programming, for one. -- MeredithLesly - 29 Jun 2006

-- RafaelAlvarez - 29 Jun 2006

It would certainly be nice to not have to write perl to create easy-to-use tags for users, which is what is required now. At least tags don't carry the overhead that plugins do, but it still requires more knowledge than most people have. The closest I have to anything approaching a macro is a bunch of code fragments in a Lib web that I can include (sometimes with parameters) in other topics.

Unfortunately, I doubt this is coming along very soon, if ever.

-- MeredithLesly - 29 Jun 2006

MACROS (I call them TopicFunctions) are nothing more than parametrized INCLUDEs of topics containing reusable TML fragments. You can also think of them as "stored procedures" where topics are database records. Right now you type %INCLUDE{"RenderChildTopics" TOPIC="Foo.Bar"}% to "call" the function RenderChildTopics that might contain a parametrized SEARCH expression searching for the child topics of topic Foo.Bar. Note, that this is far more flexible than having to write/fix a perl module, whether it is a tag or a plugin. If you are concerned about performance then use DBCachePlugin and call the function typing %DBCALL{"RenderChildTopics" TOPIC="Foo.Bar"}% .

So far the status quo. What would make things a lot userfriendlier is to be able to write %RenderChildTopics{"Foo.Bar"}% omitting the INCLUDE/DBCALL tag name. Maybe all topics that are tagged to be TopicFunctions could be added to TML automatically. Albeit this is an interesting thing usability-wise, it would be complicated to get efficient practically.

-- MichaelDaum - 30 Jun 2006

yep, and If you want to see and example of TopicFunctions that use only inbuilt TWiki calls - take a look at the reports generated on our Bugs system. or the ones on http://www.home.org.au (use view raw to see them)

-- SvenDowideit - 30 Jun 2006

%INCLUDE{"RenderChildTopics" TOPIC="Foo.Bar"}% is also far less flexible, unless you also expect users to be able to pass in other variables such FORMAT and EXCLUDETOPICS (which ChildTopicsTag supports), which makes the resulting TML excessively complicated, assuming it's possible at all.

Snippets have their place: I use them myself. They also require someone -- usually someone fairly sophisticated -- to write them and often wind up being far more trouble than they're worth (thus in part motiving the creation of ChildTopicsTag). Also, they are not distributed with TWiki, making them far less useful to the TWikiCommunity.

-- MeredithLesly - 30 Jun 2006

What Michael describes (omitting the INCLUDE/DBCALL) is what i was refering to.

It's true that sometimes is "better" to write a Tag or a Plugin, but this requires a developer. But "Power Users" can start to create macros and distribute them to the other users (much like they create TWikiApps). The advantage in the corporate enviroment is that you don't need to wait "The Programmers" to be able to have the functionality you need (that's why Excel and Access became so popular as a development platform among business users).

-- RafaelAlvarez - 30 Jun 2006

This is quite true. It's also true that packaging up a lot of useful tags (with doc, obviously) would add a lot of value.

-- MeredithLesly - 30 Jun 2006

MACROS and Tags are not mutually exclusive features. Tags are, as you described them, "lightweight plugins". MACROS are useful and clever uses of TWikiTags that Power Users can package in a more palatable way for TWikiUsers to use them, without knowing perl.

-- RafaelAlvarez - 01 Jul 2006

Currently the only way to have "macros" is to do a parameterised INCLUDE, which I don't believe is what you're talking about. I'm not arguing against having macros, just pointing out that including topics is not the same thing as a macro and so if macros are to be added, they need to be spec'ced out.

-- MeredithLesly - 01 Jul 2006

I've been trying to create CMS-like macros using INCLUDEs, but this failed because INCLUDE does not accept newlines in its parameters (of course). For example: to have a news item teaser with image left and a few lines of text plus link to full article, all inside a styled div container. We call this a CMS module: fixed design, variable content. It would be great if Macros could support this.

• Arthur, try the GluePlugin. Used excessively by the BlogPlugin. CMS modules, that's what the BlogPlugin is all about. -- MichaelDaum - 03 Jul 2006

-- ArthurClemens - 01 Jul 2006

Arthur - thats why I pointed you to http://www.home.org.au/ I use INCLUDEs to put variable content content into the Snazzy Curved Boxs

-- SvenDowideit - 02 Jul 2006

There's no clear guidance when to use TML and when you are better off inventing/extending existing perl modules.

Most of the time you go for perl if TML does not support a function that you'd like to integrate into TML. If you can to the same in TML as in perl then there must be strong reasons to do it in perl IMHO. Inventing yet another language extension should be avoided if possible. Sometimes the tradeoff between a TopicFunction and a perl implementation doing the same resolves clearly when the former does not perform the speed you need in your TWikiApplication. Note, that this is the most technical argument you can come along with. Usability, that is how the TopicFunction gets called, is nearly the same as calling a tag (let's forget about omitting INCLUDE/DBCALL for a moment which is a nice-to-have only). Maintainability of TopicFunctions can be a pain if you don't take care as they tend to get lost somewhere in your application. That's why I proposed the TWikiWorkbench approach. See the TopicClassificationAddOn for a similar approach to manage TWikiApplications. But in general writing/enhancing/fixing TopicFunctions is easier and more accessible than writing perl. Nevertheless, the fundaments of a TWikiApplications are TML+plugins written in perl. If you write them to be flexible right away, then you can stay in TML-land for a long time.

I think we should be more focused on TWikiApplications in a broader picture than on a specific technical detail: let's leverage maintainability, configurability, modularity and reusability in TWikiApplications.

-- MichaelDaum - 03 Jul 2006