ikiwiki (3.20130711) unstable; urgency=low
[ikiwiki.git] / doc / plugins / contrib / album / discussion.mdwn
1 thanks for this plugin.  it might help me in my application, which is to provide album/galleries which can be edited (ie. new images added, taken away, etc.) through web interface.
2
3 > That's my goal eventually, too. Perhaps you can help to
4 > design/write this plugin? At the moment I'm mostly
5 > waiting for a design "sanity check" from [[Joey]],
6 > but any feedback you can provide on the design would
7 > also be helpful. --[[smcv]]
8
9 i have two challenges: firstly, for installation, i'm not sure what all the files are that need to be downloaded (because of my setup i can't easily pull the repo).  so far i have Ikiwiki/Plugins/album.pm; ikiwiki-album; and 4 files in templates/  any others?
10
11 > Those are all the added files; ikiwiki-album isn't strictly
12 > needed (IkiWiki itself doesn't use that code, but you can
13 > use it to turn a directory full of images into correct
14 > input for the album plugin).
15 >
16 > You probably also want the album plugin's expanded version of
17 > style.css (or put its extra rules in your local.css).
18 > Without that, your albums will be quite ugly.
19 >
20 > There aren't currently any other files modified by my branch.
21 > --[[smcv]]
22
23 secondly: barring the CGI interface for editing the album, which would be great, is there at least a way to use attachment plugin or any other to manually add images and then create viewers for them?
24
25 > Images are just attachments, and viewers are pages (any supported
26 > format, but .html will be fastest to render). Attach each image,
27 > then write a page for each image containing the
28 > \[[!albumimage]] directive (usually it will *only* contain that
29 > directive).
30 >
31 > The script ikiwiki-album can help you to do this in a git/svn/etc.
32 > tree; doing it over the web will be a lot of work (until I get
33 > the CGI interface written), but it should already be possible!
34 >
35 > The structure is something like this:
36
37 > * album.mdwn (contains the \[[!album]] directive, and perhaps also
38 >   some \[[!albumsection]] directives)
39 > * album/a.jpg
40 > * album/a.html (contains the \[[!albumimage]] directive for a.jpg)
41 > * album/b.jpg
42 > * album/b.html (contains the \[[!albumimage]] directive for b.jpg)
43 >
44 > Have a look at ikiwiki-album to see how the directives are meant to
45 > work in practice.
46 >
47 > --[[smcv]]
48
49 >> In the current version of the branch, the viewer pages are
50 >> generated automatically if you didn't generate them yourself,
51 >> so `ikiwiki-album` is no longer needed. --[[smcv]]
52
53 i'm new to ikiwiki, apologies if this is dealt with elsewhere.  -brush
54
55 > This plugin is pretty ambitious, and is unfinished, so I'd recommend
56 > playing with  a normal IkiWiki installation for a bit, then trying
57 > out this plugin when you've mastered the basics of IkiWiki. --[[smcv]]
58
59 ----
60
61 You had wanted my feedback on the design of this. I have not looked at the
62 code or tried it yet, but here goes. --[[Joey]] 
63
64 * Needing to create the albumimage "viewer" pages for each photo
65   seems like it will become a pain. Everyone will need to come up
66   with their own automation for it, and then there's the question
67   of how to automate it when uploading attachments. -J
68
69 > There's already a script (ikiwiki-album) to populate a git
70 > checkout with skeleton "viewer" pages; I was planning to make a
71 > specialized CGI interface for albums after getting feedback from
72 > you (since the requirements for that CGI interface change depending
73 > on the implementation). I agree that this is ugly, though. -s
74
75 >> Would you accept a version where the albumimage "viewer" pages
76 >> could be 0 bytes long, at least until metadata gets added?
77 >>
78 >> The more I think about the "binaries as first-class pages" approach,
79 >> the more subtle interactions I notice with other plugins. I
80 >> think I'm up to needing changes to editpage, comments, attachment
81 >> and recentchanges, plus adjustments to img and Render (to reduce
82 >> duplication when thumbnailing an image with a strange extension
83 >> while simultaneously changing the extension, and to hardlink/copy
84 >> an image with a strange extension to a differing target filename
85 >> with the normal extension, respectively). -s
86
87 >>> Now that we have `add_autofile` I can just create viewer pages
88 >>> whenever there's an image to view. The current version of the
89 >>> branch does that. -s
90
91 * With each viewer page having next/prev links, I can see how you
92   were having the scalability issues with ikiwiki's data structures
93   earlier! -J
94
95 > Yeah, I think they're a basic requirement from a UI point of view
96 > though (although they don't necessarily have to be full wikilinks).
97 > -s
98
99 >> I think that with the new dependency types system, the dependencies for
100 >> these can be presence dependencies, which will probably help with
101 >> avoiding rebuilds of a page if the next/prev page is changed.
102 >> (Unless you use img to make the thumbnails for those links, then it
103 >> would rebuild the thumbnails anyway. Have not looked at the code.) --[[Joey]]
104
105 >>> I do use img. -s
106
107 * And doesn't each viewer page really depend on every other page in the
108   same albumsection? If a new page is added, the next/prev links
109   may need to be updated, for example. If so, there will be much
110   unnecessary rebuilding. -J
111
112 > albumsections are just a way to insert headings into the flow of
113 > photos, so they don't actually affect dependencies.
114 >
115 > One non-obvious constraint of ikiwiki's current design is that
116 > everything "off-page" necessary to build any page has to happen
117 > at scan time, which has caused a few strange design decisions,
118 > like the fact that each viewer controls what album it's in.
119 >
120 > It's difficult for the contents of the album to just be a
121 > pagespec, like for inline, because pagespecs can depend on
122 > metadata, which is gathered in arbitrary order at scan time;
123 > so the earliest you can safely apply a pagespec to the wiki
124 > contents to get a concrete list of pages is at rebuild time.
125 >
126 > (This stalled my attempt at a trail plugin, too.) -s
127
128 >> Not sure I understand why these need to look at pagespecs at scan time?
129 >> Also, note that it is fairly doable to detect if a pagespec uses such
130 >> metadata. Er, I mean, I have a cheezy hack in `add_depends` now that does
131 >> it to deal with a similar case. --[[Joey]] 
132
133 >>> I think I was misunderstanding how early you have to call `add_depends`?
134 >>> The critical thing I missed was that if you're scanning a page, you're
135 >>> going to rebuild it in a moment anyway, so it doesn't matter if you
136 >>> have no idea what it depends on until the rebuild phase. -s
137
138 * One thing I do like about having individual pages per image is
139   that they can each have their own comments, etc. -J
140
141 > Yes; also, they can be wikilinked. I consider those to be
142 > UI requirements. -s
143
144 * Seems possibly backwards that the albumimage controls what album
145   an image appears in. Two use cases -- 1: I may want to make a locked
146   album, but then anyone who can write to any other page on the wiki can
147   add an image to it. 2: I may want an image to appear in more than one
148   album. Think tags. So it seems it would be better to have the album
149   directive control what pages it includes (a la inline). -J
150
151 > I'm inclined to fix this by constraining images to be subpages of exactly
152 > one album: if they're subpages of 2+ nested albums then they're only
153 > considered to be in the deepest-nested one (i.e. longest URL), and if
154 > they're not in any album then that's a usage error. This would
155 > also make prev/next links sane. -s
156
157 >> The current version constrains images to be in at most one album,
158 >> choosing one arbitrarily (dependent on scan order) if albums are
159 >> nested. -s
160
161 > If you want to reference images from elsewhere in the wiki and display
162 > them as if in an album, then you can use an ordinary inline with
163 > the same template that the album would use, and I'll make sure the
164 > templates are set up so this works. -s
165
166 >> Still needs documenting, I've put it on the TODO list on the main
167 >> page. -s
168
169 > (Implementation detail: this means that an image X/Y/Z/W/V, where X and
170 > Y are albums, Z does not exist and W exists but is not an album,
171 > would have a content dependency on Y, a presence dependency on Z
172 > and a content dependency on W.)
173 >
174 > Perhaps I should just restrict to having the album images be direct
175 > subpages of the album, although that would mean breaking some URLs
176 > on the existing website I'm doing all this work for... -s
177
178 >> The current version of the branch doesn't have this restriction;
179 >> perhaps it's a worthwhile simplification, or perhaps it's too
180 >> restrictive? I fairly often use directory hierarchies like
181 >> `a_festival/saturday/foo.jpg` within an album, which makes
182 >> it very easy to write `albumsection` filters. -s
183
184 * Putting a few of the above thoughts together, my ideal album system
185   seems to be one where I can just drop the images into a directory and
186   have them appear in the album index, as well as each generate their own wiki
187   page. Plus some way I can, later, edit metadata for captions,
188   etc. (Real pity we can't just put arbitrary metadata into the images
189   themselves.) This is almost pointing toward making the images first-class
190   wiki page sources. Hey, it worked for po! :) But the metadata and editing
191   problems probably don't really allow that. -J
192
193 > Putting a JPEG in the web form is not an option from my point of
194 > view :-) but perhaps there could just be a "web-editable" flag supplied
195 > by plugins, and things could be changed to respect it.
196
197 >> Replying to myself: would you accept patches to support
198 >> `hook(type => 'htmlize', editable => 0, ...)` in editpage? This would
199 >> essentially mean "this is an opaque binary: you can delete it
200 >> or rename it, and it might have its own special editing UI, but you
201 >> can never get it in a web form".
202 >>
203 >> On the other hand, that essentially means we need to reimplement
204 >> editpage in order to edit the sidecar files that contain the metadata.
205 >> Having already done one partial reimplementation of editpage (for
206 >> comments) I'm in no hurry to do another.
207 >>
208 >> I suppose another possibility would be to register hook
209 >> functions to be called by editpage when it loads and saves the
210 >> file. In this case, the loading hook would be to discard
211 >> the binary and use filter() instead, and the saving conversion
212 >> would be to write the edited content into the metadata sidecar
213 >> (creating it if necessary).
214 >>
215 >> I'd also need to make editpage (and also comments!) not allow the
216 >> creation of a file of type albumjpg, albumgif etc., which is something
217 >> I previously missed; and I'd need to make attachment able to
218 >> upload-and-rename.
219 >> -s
220
221 >>> I believe the current branch meets your requirements, by having
222 >>> first-class wiki pages spring into existence using `add_autofile`
223 >>> to be viewer pages for photos. -s
224
225 > In a way, what you really want for metadata is to have it in the album
226 > page, so you can batch-edit the whole lot by editing one file (this
227 > does mean that editing the album necessarily causes each of its viewers
228 > to be rebuilt, but in practice that happens anyway). -s
229
230 >> Replying to myself: in practice that *doesn't* happen anyway. Having
231 >> the metadata in the album page is somewhat harmful because it means
232 >> that changing the title of one image causes every viewer in the album
233 >> to be rebuilt, whereas if you have a metadata file per image, only
234 >> the album itself, plus the next and previous viewers, need
235 >> rebuilding. So, I think a file per image is the way to go.
236 >>
237 >> Ideally we'd have some way to "batch-edit" the metadata of all
238 >> images in an album at once, except that would make conflict
239 >> resolution much more complicated to deal with; maybe just
240 >> give up and scream about mid-air collisions in that case?
241 >> (That's apparently good enough for Bugzilla, but not really
242 >> for ikiwiki). -s
243
244 >>> This is now in the main page's TODO list; if/when I implement this,
245 >>> I intend to make it a specialized CGI interface. -s
246
247 >> Yes, [all metadata in one file] would make some sense.. It also allows putting one image in
248 >> two albums, with different caption etc. (Maybe for different audiences.)
249 >> --[[Joey]]
250
251 >>> Eek. No, that's not what I had in mind at all; the metadata ends up
252 >>> in the "viewer" page, so it's necessarily the same for all albums. -s
253
254 >> It would probably be possible to add a new dependency type, and thus
255 >> make ikiwiki smart about noticing whether the metadata has actually
256 >> changed, and only update those viewers where it has. But the dependency
257 >> type stuff is still very new, and not plugin friendly .. so only just
258 >> possible, --[[Joey]] 
259
260 ----
261
262 '''I think the "special extension" design is a dead-end, but here's what
263 happened when I tried to work out how it would work. --[[smcv]]'''
264
265 Suppose that each viewer is a JPEG-or-GIF-or-something, with extension
266 ".albumimage". We have a gallery "memes" with three images, badger,
267 mushroom and snake.
268
269 > An alternative might be to use ".album.jpg", and ".album.gif"
270 > etc as the htmlize extensions. May need some fixes to ikiwiki to support
271 > that. --[[Joey]] 
272
273 >> foo.albumjpg (etc.) for images, and foo._albummeta (with
274 >> `keepextension => 1`) for sidecar metadata files, seems viable. -s
275
276 Files in git repo:
277
278 * index.mdwn
279 * memes.mdwn
280 * memes/badger.albumjpg (a renamed JPEG)
281 * memes/badger/comment_1._comment
282 * memes/badger/comment_2._comment
283 * memes/mushroom.albumgif (a renamed GIF)
284 * memes/mushroom._albummeta (sidecar file with metadata)
285 * memes/snake.albummov (a renamed video)
286
287 Files in web content:
288
289 * index.html
290 * memes/index.html
291 * memes/96x96-badger.jpg (from img)
292 * memes/96x96-mushroom.gif (from img)
293 * memes/96x96-snake.jpg (from img, hacked up to use totem-video-thumbnailer :-) )
294 * memes/badger/index.html (including comments)
295 * memes/badger.jpg
296 * memes/mushroom/index.html
297 * memes/mushroom.gif
298 * memes/snake/index.html
299 * memes/snake.mov
300
301 ispage("memes/badger") (etc.) must be true, to make the above rendering
302 happen, so albumimage needs to be a "page" extension.
303
304 To not confuse other plugins, album should probably have a filter() hook
305 that turns .albumimage files into HTML? That'd probably be a reasonable
306 way to get them rendered anyway.
307
308 > I guess that is needed to avoid preprocess, scan, etc trying to process
309 > the image, as well as eg, smiley trying to munge it in sanitize.
310 > --[[Joey]] 
311
312 >> As long as nothing has a filter() hook that assumes it's already
313 >> text... filters are run in arbitrary order. We seem to be OK so far
314 >> though.
315 >>
316 >> If this is the route I take, I propose to have the result of filter()
317 >> be the contents of the sidecar metadata file (empty string if none),
318 >> with the `\[[!albumimage]]` directive (which no longer requires
319 >> arguments) prepended if not already present. This would mean that
320 >> meta directives in the metadata file would work as normal, and it
321 >> would be possible to insert text both before and after the viewer
322 >> if desired. The result of filter() would also be a sensible starting
323 >> point for editing, and the result of editing could be diverted into
324 >> the metadata file. -s
325
326 do=edit&page=memes/badger needs to not put the JPG in a text box: somehow
327 divert or override the normal edit CGI by telling it that .albumimage
328 files are not editable in the usual way?
329
330 > Something I missed here is that editpage also needs to be told that
331 > creating new files of type albumjpg, albumgif etc. is not allowed
332 > either! -s
333
334 Every image needs to depend on, and link to, the next and previous images,
335 which is a bit tricky. In previous thinking about this I'd been applying
336 the overly strict constraint that the ordered sequence of pages in each
337 album must be known at scan time. However, that's not *necessarily* needed:
338 the album and each photo could collect an unordered superset of dependencies
339 at scan time, and at rebuild time that could be refined to be the exact set,
340 in order.
341
342 > Why do you need to collect this info at scan time? You can determine it
343 > at build time via `pagespec_match_list`, surely .. maybe with some
344 > memoization to avoid each image in an album building the same list.
345 > I sense that I may be missing a subtelty though. --[[Joey]] 
346
347 >> I think I was misunderstanding how early you have to call `add_depends`
348 >> as mentioned above. -s
349
350 Perhaps restricting to "the images in an album A must match A/*"
351 would be useful; then the unordered superset could just be "A/*". Your
352 "albums via tags" idea would be nice too though, particularly for feature
353 parity with e.g. Facebook: "photos of Joey" -> "tags/joey and albumimage()"
354 maybe?
355
356 If images are allowed to be considered to be part of more than one album,
357 then a pretty and usable UI becomes harder - "next/previous" expands into
358 "next photo in holidays/2009/germany / next photo in tagged/smcv / ..."
359 and it could get quite hard to navigate. Perhaps next/previous links could
360 be displayed only for the closest ancestor (in URL space) that is an
361 album, or something?
362
363 > Ugh, yeah, that is a problem. Perhaps wanting to support that was just
364 > too ambitious. --[[Joey]] 
365
366 >> I propose to restrict to having images be subpages of albums, as
367 >> described above. -s
368
369 Requiring renaming is awkward for non-technical Windows/Mac users, with both
370 platforms' defaults being to hide extensions; however, this could be
371 circumvented by adding some sort of hook in attachment to turn things into
372 a .albumimage at upload time, and declaring that using git/svn/... without
373 extensions visible is a "don't do that then" situation :-)
374
375 > Or extend `pagetype` so it can do the necessary matching without
376 > renaming. Maybe by allowing a subdirectory to be specified along
377 > with an extension. (Or allow specifying a full pagespec,
378 > but I hesitate to seriously suggest that.) --[[Joey]] 
379
380 >> I think that might be a terrifying idea for another day. If we can
381 >> mutate the extension during the `attach` upload, that'd be enough;
382 >> I don't think people who are skilled enough to use git/svn/...,
383 >> but not skilled enough to tell Explorer to show file extensions,
384 >> represent a major use case. -s
385
386 Ideally attachment could also be configured to upload into a specified
387 underlay, so that photos don't have to be in your source-code control
388 (you might want that, but I don't!).
389
390 > Replying to myself: perhaps best done as an orthogonal extension
391 > to attach? -s
392
393 > Yet another non-obvious thing this design would need to do is to find
394 > some way to have each change to memes/badger._albummeta show up as a
395 > change to memes/badger in `recentchanges`. -s
396
397 Things that would be nice, and are probably possible:
398
399 * make the "Edit page" link on viewers divert to album-specific CGI instead
400   of just failing or not appearing (probably possible via pagetemplate)
401
402 * some way to deep-link to memes/badger.jpg with a wikilink, without knowing a
403   priori that it's secretly a JPEG (probably harder than it looks - you'd
404   have to make a directive for it and it's probably not worth it)
405
406 ----
407
408 Hi smcv, great plugin. I am an ikiwiki newbie but so far I've had success using your plugin.
409 I've integrated the jquery masonry plugin into the albumitem template and it works great.
410 But is there a way to create thumnails of different sizes? I've passed thumnailsize option
411 and value to album directive and while it does create the new thumbnail sizes it doesn't use them,
412 The 96x96 thumbnails still appear on the page no matter what I do. - jaime
413
414 ----
415
416 Hi, the plugin looks great, but I am probably too dumb to use it ;( here is what I did:
417 created page gal.mdwn with just \[\[!album\]\] directive (no arguments) and subdirectory gal/ with images in form img_1234.jpg
418
419 when I run ikiwiki, I get something completely wrong though:
420
421 generated gal/index.html page contains following code repeated for every image:
422
423     <div class="album-viewer">
424       <div id="album-img">
425         <div class="album-finish">
426           <a href="./"><span class="album-arrow">↑</span></a>
427         </div>
428       </div>
429     </div>
430
431 So no links to any images, etc.
432
433 The pages for individual images are generated though, but also not correct. Trails section is perfect, but the main part is wrong:
434
435     <div class="album-prev">
436       <a><span class="album-arrow">â†<90></span></a><br />
437       <div class="album-thumbnail">
438         <span class="selflink">
439           <img src="./96x96-img_2913.jpg" width="96" height="72" alt="img 2913" title="img 2913" class="img" /></span>
440       </div>
441     </div>
442
443 This really seems like this should be in the album page and not individul page. It is only thumbnail and not full image. Also the full image is not in the generated html tree at all!
444
445 I am using ikiwiki 3.20130518, and got the album sources from the links of [this page](http://ikiwiki.info/plugins/contrib/album/) (part manual installation)
446
447 Any hint about what do I do wrong?
448
449 Thanks Lukas
450
451 > This plugin is not really finished. I probably need to update it for
452 > current ikiwiki. I'll try to update it (and also update my demo
453 > and installation instructions) at some point. --[[smcv]]
454
455 >> I have to appologize, I accidentally copied the template wrongly and that caused all the issues ;(
456 >> So now after two days debugging and tracing, I just fixed that and it works. Well, at least a learnt
457 >> a lot about ikiwiki internal ;-)
458 >> Thanks for all the work you did on the plugin! --Lukas