Tags:
archive_me1Add my vote for this tag create new tag
view all tags

Implemented: Templates for Meta Data Presentation

I don't want to overlap with what's been discussed elsewhere, but I have a pressing need to be able to modify the attachments table for a skin. At the moment, attachment tables are defined in the code, and the only way to affect their look is to either get in and change Attach.pm, or post-process the topic with the table in using some fancy footwork in a plugin.

There's a very quick and easy fix for this; use a template to define the table. There is a finite set of data which is actually available to be filled in in the table, specifically, the fileIcon, fileUrl, file, size, date, user and comment. These could be used to replace % fields in the template. The template would have two definitions, TMPL:DEF{ATTACH:header} and TMPL:DEF{ATTACH:row}. These defintitions would be instantiated to fill in the table.

In the spirit of moving templates into user topics I thought about putting this into a user template, but was struck that with the current webs, we don't have anywhere suitable. However a suitable template could be part of the skin definition. That gives another nice feature; by defining the templates as empty, you can exclude the table from certain skins. Very useful for, for example, skin=print. Since macro definitions read later in files override those defined earlier, defaults for the macros could be provided in twiki.tmpl and selectively overridden in skin templates.

In the interim, the attached patch refactors Attach.pm and twiki.tmpl to achieve the stated aim. It is based on the contents of CVS as of 17:00 GMT 18/4/04.

As a further example, the following additional patch disables the attachment table on the print skin.

Index: templates/view.print.tmpl
===================================================================
RCS file: /cvsroot/twiki/twiki/templates/view.print.tmpl,v
retrieving revision 1.9
diff -u -r1.9 view.print.tmpl
--- templates/view.print.tmpl   22 Mar 2003 06:04:45 -0000   1.9
+++ templates/view.print.tmpl   18 Apr 2004 17:11:50 -0000
@@ -30,3 +30,8 @@
 #PageBottom
 </body>
 </html>
+%TMPL:DEF{ATTACH:header}%%TMPL:END%
+%TMPL:DEF{ATTACH:row}%%TMPL:END%
+%TMPL:DEF{ATTACH:header_A}%%TMPL:END%
+%TMPL:DEF{ATTACH:row_A}%%TMPL:END%
+%TMPL:DEF{ATTACH:footer}%%TMPL:END%

Documentation

In TWikiSkins add the following section:

Attachment Tables

Controlling the look and feel of attachment tables is a little bit more complex than for the rest of a skin. By default the attachment table is a standard TWiki table, and the look is controlled in the same ay as other tables. In a very few cases you may want to change the content of the table as well.

The format of standard attachment tables is defined through the use of special TWiki template macros which by default are defined in the templates/twiki.tmpl template using the %TMPL:DEF macro syntax described in TWikiTemplates. These macros are:

Macro Description
ATTACH:files:header Standard title bar
ATTACH:files:row Standard row
ATTACH:files:footer Footer for all screens
ATTACH:files:header:A Title bar for upload screens, with attributes column
ATTACH:files:row:A Row for upload screen
ATTACH:files:footer:A Footer for all screens
The format of tables of file versions in the Upload screen are also formattable, using the macros:
Macro Description
=ATTACH:versions:header Header for versions table on upload screen
=ATTACH:versions:row Row format for versions table on upload screen
=ATTACH:versions:footer Footer for versions table on upload screen

The ATTACH:row macros are expanded for each file in the attachment table, using the following special tags:

Tag Description
%A_URL% URL that will recover the file
%A_REV% Revision of this file e.g. "1.1"
%A_ICON% A file icon suitable for representing the attachment content
%A_FILE% The name of the file
%A_SIZE% The size of the file
%A_DATE% The date the file was uploaded
%A_USER% The user who uploaded it
%A_COMMENT% The comment they put in when uploading it
%A_ATTRS% The attributes of the file as seen on the upload screen e.g "h" for a hidden file

Note: it is easy to change the look and feel for an entire site by editing the twiki.tmpl template file. However, to simplify upgrading, you should avoid doing this. Instead, write a skin-specific template file e.g. attach.myskin.tmpl and use %TMPL:INCLUDE{attach.myskin.tmpl}% to include it in each of your skin files. As long as it it included after twiki.tmpl, your macro definitions will override the defaults defined there.

Contributors:
-- CrawfordCurrie - 18 Apr 2004

Discussions

Crawford, this is a good idea. Note that you are making my point, argued in TWikiWhatWillYouBeWhenYouGrowUp that each application that makes up a twiki topic needs to be able to define its own presentation. The attachment table is one such application.

-- ThomasWeigert - 18 Apr 2004

Please add docco for this here, in a format that will be easy to add to the Documentation in the TWiki Web.

Also, there is another code generated table in UI/Upload.pm (in _listVersions) that needs modification.

-- SvenDowideit - 19 Apr 2004

Sven, _listVersions.I agree it should be done in the same way, but that's outside the scope of this patch.

-- CrawfordCurrie - 19 Apr 2004

This is a useful enhancement.

First I would like to take a step back, looking at these requirements and asking these questions:

  1. Most likely just TWikiApplication need to change the default meta data presentation, probably with the help of Add-Ons/Plugins/Skins; that is, normal use is not affected
  2. What is more likely to be used:
    1. Change presentation per site (e.g. because of additional functionality provided by Plugin like WebDAV access)
    2. Change presentation per web (e.g. for specific TWikiApplication)
    3. Change presentation per topic (e.g. specific topics of a TWikiApplication)
    4. Change presentation per active skin (e.g. for print view)
  3. Out of scope for now, but we should look at the LocalizationIsNeeded aspect of InternationalisationEnhancements, or at least check that we are not building roadblocks
  4. Can we make it easy for all use cases?
    1. Easy to install and upgrade Plugin (avoid manual merge of configurations?)
    2. Easy for skin authors (avoid patching existing skins?)

On point 2, it is difficult to predict what is more likely to be used, I arranged it in the order of probability as I see it.

An alternative solution is to use preferences settings, e.g.

  • Set META_ATTACH_HEADER_FORMAT = ...
  • Set META_ATTACH_ROW_FORMAT = ...
  • Set META_ATTACH_HEADERA_FORMAT = ...
  • Set META_ATTACH_ROWA_FORMAT = ...
  • Set META_ATTACH_FOOTER_FORMAT = ...

-- PeterThoeny - 20 Apr 2004

Hmmm. Yes, it's difficult to predict every use, but I would point out that with the changes, everything in 2. above is supported. If it were possible for a TWikiApplication to change the skin on the fly by setting a variable, then obviously it can pick up the templates associated with that skin, which include these new templates. On the alternative approach; well, I don't think there's any precedent for templating off variables (though I could be wrong). Do we really want to introduce a new template methodology? Remember we now have the ability to have templates in user topics, so templates are already as accessible as variables.

The most general solution, and some will argue best solution, is to support proper templates. Consider it this way. Image the topic data is in a hash, where

{ text => "the topic text", attachments => [ an array of attachments ], parent => ... etc }
Each attachment is itself a hash,
 { name => ..., revision => .. } 
etc. (This is all very much like the way it's done internally at the moment). If the template language supported access to the fields of this hash, the template author could reference whatever they wanted from the hash. Rather than writing %TEXT in your template you would write something like:
%TMPL:FIELD{"text"}%
which would just refer to the hash and get the text. Now, for presenting tables, you need something to filter content and format the table. Well, we already have some of that in the way search tables are expanded. The template author would write something like this:
%TMPL:DEFQUERY{ name="attachment table" "SELECT attachment WHERE attrs != "hidden" }%
%TMPL:SHOWQUERY{ name="attachment table" header="|*Attachment*|" format="|$name|" }%
(format cribbed shamelessly from the FormQueryPlugin, which already builds this kind of hash). In this way all content in views can be defined in the templates, from just a small number of base types such as text, date, number etc. Note how this also relates to FormattedTWikiFormDataInTopicText, FormQueryPlugin, and any number of other topics converging on the same ideas.

Most of the work involved in doing things that way consists of chopping out redundant code currently in places like Attach.pm, Search.pm and Store.pm. Anyway, that's for the future. The way I have done it today is pragmatic, and easy for skin authors, because they simply override the macro definitions in their skin template files.

The attached updated patch, and documentation in this topic, addresses Sven's concerns about listVersions.

-- CrawfordCurrie - 21 Apr 2004

While the purpose of this is pretty straightforward, it did seem to have required a lot of code to change. I'd like to have a decision on whether the current implementation can go in pending any future changes. Perhaps take this diff for Cairo and see what we can do about a query language for Dakar? I'm really tired and not taking much in right now...I just wanted to post that I've looked at this and don't know what to make of it so that perhaps someone else on the team can come in and do a real analysis.

-- WalterMundt - 25 Apr 2004

The original patch (patch.diff below) was tiny, just a handful of lines. The revised patch was a result of Sven's request for refactoring _listVersions from Update.pm, and is much more extensive but still an incomplete solution. Would you like me to produce a third patch that supports SQL queries? That will be even more far-reaching.

As I said at the start I have a direct and pressing requirement for the first, tiny, patch to support an "edit" link in the attachment table for the WebDAVPlugin.

-- CrawfordCurrie - 27 Apr 2004

Third time lucky. After a conversation with PeterThoeny last night, a third and final patch revision is attached in the form of a patch file and a new file for the templates directory, attachtables.tmpl. The difference? Well, this on loads a separate tempate file for the table templates, so existing skins won't be broken by the patch.

-- CrawfordCurrie - 28 Apr

Given that this patch has been sitting here quietly for nearly a month and is not included in the latest Cairo beta - has not even been AssignedToCore - am I to guess that it has been rejected for inclusion in Cairo? Some feedback would be welcome. Thanks.

-- CrawfordCurrie - 23 May 2004

Would someone on the core team please give me some feedback on this? I put a fair amount of effort into this patch, and I find it really frustrating that no-one even bothers to give me feedback for nearly 2 months.

-- CrawfordCurrie - 15 Jun 2004

thsi is now in SVN. I think the only remaining thing is to figure out where the docco should go in the release.

-- SvenDowideit - 17 Jun 2004

This is a candicate for TWiki speed improvement: Change syntax to a single variable with parameters.

-- PeterThoeny - 16 Aug 2004

Topic attachments
I Attachment History Action Size Date Who Comment
Unknown file formatdiff TemplatesForMetaDataPresentation.diff r2 r1 manage 19.1 K 2004-04-28 - 12:55 UnknownUser Needs attachtables.tmpl as well
Texttxt attachtables.tmpl.txt r1 manage 1.8 K 2004-04-28 - 12:56 UnknownUser Needed with rev 3
Unknown file formatdiff patch.diff r1 manage 3.5 K 2004-04-18 - 17:35 UnknownUser The first teeny-weeny patch
Edit | Attach | Watch | Print version | History: r22 < r21 < r20 < r19 < r18 | Backlinks | Raw View | Raw edit | More topic actions
Topic revision: r22 - 2006-03-15 - FranzJosefSilli
 
  • Learn about TWiki  
  • Download TWiki
This site is powered by the TWiki collaboration platform Powered by Perl Hosted by OICcam.com Ideas, requests, problems regarding TWiki? Send feedback. Ask community in the support forum.
Copyright © 1999-2024 by the contributing authors. All material on this collaboration platform is the property of the contributing authors.