ikiwiki (3.20130711) unstable; urgency=low
[ikiwiki.git] / doc / forum / Howto_add_tag_from_plugin_code / comment_1_c61454825874a6fe1905cb549386deb0._comment
1 [[!comment format=mdwn
2  username="http://smcv.pseudorandom.co.uk/"
3  nickname="smcv"
4  subject="comment 1"
5  date="2013-07-01T09:13:51Z"
6  content="""
7 (If you want to branch from my version of album, please add my git repo
8 as a remote and merge or cherry-pick the album4 branch: pasting from my
9 gitweb seems to have given you some incorrect UTF-8.)
10
11 The problem you have here is that for this plugin, the correct order
12 for IkiWiki to do things is quite subtle. Am I right in thinking that
13 the feature you want goes something like this?
14
15 > To add a set of tags to every \"viewer\" page in the album, you can add
16 > the tags parameter to the album:
17 >
18 >     \[[!album tags=\"holiday hawaii\"]]
19 >
20 > The individual viewers will all be tagged \"holiday\" and \"hawaii\",
21 > for instance. These tags cannot be removed by editing the viewers.
22
23 `preprocess_albumimage` runs twice: once in the scan stage, and once in
24 the render stage. In the render stage, it's too late to add tags, because
25 tags are a special form of [[ikiwiki/wikilinks]], and wikilinks have to
26 be added during the scan stage to work correctly.
27
28 The part of `preprocess_albumimage` after the line
29 `return unless defined wantarray;` only runs in the render stage, which
30 is too late. You'd need to set up the tags further up: just after the
31 calls to `IkiWiki::Plugin::meta::preprocess` would be a good place.
32
33 I would also suggest checking for
34 `IkiWiki::Plugin::tag->can('preprocess_tag')`,
35 like I do for meta - if you do that, you won't need to force the tag plugin
36 to be loaded.
37
38 Unfortunately, I'm still not sure that this is fully correct. Pages
39 are scanned in a random order. If the `\[[!album]]` is scanned before
40 a \"viewer\" page, then everything is fine: the tags are present when
41 the \"viewer\" is scanned. However, if the \"viewer\" is scanned first,
42 then it will get the tags that the `\[[!album]]` had in the *previous*
43 IkiWiki run (if any), which are still in the index, because the
44 `\[[!album]]` hasn't been re-scanned yet...
45
46 Are you sure this form of the feature is what you want? You'll end up with
47 a *lot* of pages with those tags. If it's what you want, it might be
48 clearer how it works if you changed the syntax to something like this,
49 perhaps?
50
51 >
52 >     \[[!album tag_all=\"holiday hawaii\"]]
53
54 Another possible syntax would be to have the feature be more like this:
55
56 > If you use the `tag_default` parameter to the `\[[!album]]` directive,
57 > each \"viewer\" page created for images will have those tags by
58 > default. Changing the `\[[!album]]` will not affect any \"viewer\"
59 > pages that have already been created, and editing the \"viewer\"
60 > can add or remove those default tags.
61 >
62 >     \[[!album tag_default=\"holiday hawaii\"]]
63
64 which I think removes the ordering problems? If you go this route,
65 you'd want to either add e.g. `[[!tag holiday hawaii]]`
66 to the generated viewer page in `create_viewer`, or add a `tag`
67 parameter to `\[[!albumimage]]` that's a shortcut for the
68 tag directive, in the same way that author is a shortcut for
69 `[[!meta author]]`).
70
71 The purpose of the \"shortcut\" parameters in `\[[!albumimage]]`,
72 like title, author and date, is that I eventually want to add
73 a specialized CGI interface to this plugin so you can edit
74 all the images of an album in one go; when I add that,
75 it'll probably only be able to process something as
76 machine-readable as `\[[!albumimage]]`.
77 """]]