Documentation Suggestion: next_image

nateomedia

Every once in a while, when I'm trying to figure out something in ZenPhoto, I am stymied by the template function documentation.

Since I know that these problems can't be fixed without someone pointing out what needs to be improved, here's what I'm currently wrestling with:

I'm am trying to configure next_image using the template function documentation. The problem? No definitions are given for $sorttype or $sortdirection. I understand that $sortdirection is either ascending or descending — but what's the proper code for those two options? Ascend? Descend? ASC or DESC? And what are the sort types?

I mean, am I being dense? I looked at some of the other functions to see if these parameters had simply been defined elsewhere, but I didn't get anywhere with that. I also dug into ZenPhoto's code to try to find the functions that do the sorting, but after chasing them down to getImages() and then sortImageArray() I gave up. It shouldn't be this hard to figure out how to use a function. I would really appreciate it if someone would update the documentation to include the options each Parameter can take. Or at least create a "key" where common parameter options are defined. Thanks!

sbillard

You are not dense, but also it is not possible to enumerate the values for sorttypes.

BTW, the way to approach your delima is to, as they say, "follow the money". In this case the `next_image()` loop passes this parameter to the `getImages()` method of whatever object is involved. This method in turn passes it to the `sortImageArray()` method which in in turn looks up a field with the function `lookupSortKey()` via the `getImageSortKey()` method.

if you examine `lookupSortKey()` you will see that it mostly uses what is passed as the parameter directly as a database table field id.

So, the short answer would have been that you pass a database table field name.

Once there was a user here on the forum who was going to write the users guide to Zenphoto. That never happened. We have in the passed volunteered to help anyone wishing to provide more detailed documentation for the project and we still hold that promise open. But we will probably not ever get around to providing the detail level documentation you desire. We don't need it and don't really want to spend our efforts on that rather than enhancements.

Besides, all programmers know that the documentation is never correct and the only way to know what really happens is to read the code. Hopefully there will be sufficient hints in the code commentary to guide you.

nateomedia

Thanks for the reply. I really think ZenPhoto is great, and I know how it is to work on a volunteer project — there's only so much that you can do. I still would respectfully suggest that maybe when someone takes the time to point out where there's a weakness in the documentation of a function, that maybe 5 minutes could be taken to try to flesh it out a little bit more. Every theme uses next_image() after all.

acrylian

And we appreciate any kind of input. Why don't you just give it a try yourself since you are at it anyway? Your chance to contribute..;-)