Developer Documentation
|
bharat
Joined: 2002-05-21
Posts: 7994 |
Posted: Mon, 2010-12-20 18:02
|
|
After reading the forums for a while I'm realizing that the biggest thing holding us back right now is a lack of clear documentation on how Gallery 3 works under the covers. I'm going to spend today today writing developer docs. Want to play along? Here's the auto-published version of what I've got in the works: It's in a Google Doc for now, and if you refresh you can see my progress. If you'd like to leave comments/notes, etc click the [edit] link and request access and I'll be happy to grant it. |
|
Posts: 7994
Ok, I spent a day writing docs. I'm making progress but there's still a lot to do. Please read and comment, this is for you!
---
Problems? Check gallery3/var/logs
file a bug/feature ticket | upgrade to the latest code! | hacking G3? join us on IRC!
Posts: 693
As a new user with some limited programming background I appreciate the docs and am reading them as best as I can while travelling. I will try to post some comments in the near future, but all this Kohana stuff is new to me. I guess the challenge in writing the documentation is how much to rely on Kohana documentation, and how much to explain here. Examples are good.
U-G
Posts: 8339
Examples were always what the G2 docs needed as well. Probably the single most helpful aspect of documentation - Teach by example.
-s
FlashYourWeb and Your Gallery with The E2 XML Media Player for Gallery2
Posts: 8
I could help with you by adding some REST/API examples/documentation for additional languages (Java,C#,Ruby, etc., etc.). As someone who just spent a couple of days writing an Android app utilizing the G3 REST calls I can say the docs could be fattened up a bit (by no means nit-picking what you have already generated; which is amazing.). Anyway, offer it open and I have been developing in many languages for over 10 years.
Posts: 7994
@emittee: it would be awesome if you'd work on improving http://codex.gallery2.org/Gallery3:API:REST -- I'm planning on just referring to that in the doc that I'm writing now since there's already a fair amount of content there. Let me know if you have any questions I can answer!
---
Problems? Check gallery3/var/logs
file a bug/feature ticket | upgrade to the latest code! | hacking G3? join us on IRC!
Posts: 8
@bharat: I added an additional java-android example to the WiKi. As you know, many times, "the devil is in the details". I will add whatever I can, when I can, to the existing wiki; which is already fantastic.
Posts: 79
Slightly offtopic, but filenames with "'s in them would rain slightly on the parade, no?
Posts: 8
I must be pretty thick. ;-) Are you referring to an error in the example I provided or are you asking an actual question?
Posts: 79
Issue (unless I'm missing something obvious) in the example code. If the file name contains a ", it seems that it won't get escaped properly.
Posts: 1642
Great idea to write up some docs.
I took a look at the kohana stuff once and was totally confused ... didn't even look like php so would be a great help to many I think.
--
dakanji.com
Posts: 34
thanks for the doc!
Posts: 28
Woo hoo! Yay for developer docs! I also, though proficient in PHP, was confused by the Kohana stuff.
Ⓑ˳® bromide
⎵
Posts: 27
Thanks.
I have now played with G3 for a couple of weeks, and I am very impressed. It seems like a very extensible platform.
The weakest link, however, is Kohana's documentation. I've practically had to reverse engineer the whole framework to learn about it. That's a serious waste of development time and, from Kohana's perspective, a serious barrier to adoption.
I learnt more from your explanations than their 'knowledge base'.
Cheers for sharing.
----
http://retroguy.org
Posts: 693
Retroguy has echoed my experience, although I suspect that I haven't gone as far as him. Having spent a couple of weeks I'm also impressed, but even after successfully hacking simple modules I still don't understand enough of the implementation of the Model / View / Controller (MVC) architecture to do anything advanced, and the Kohana docs are not that much help.
U-G
Posts: 27
@undagiga
I have found an excellent article discussing the benefits of the HMVC model as used by Kohana and G3. It has certainly helped me get my head around the concept.
http://techportal.ibuildings.com/2010/02/22/scaling-web-applications-with-hmvc/
You may have already seen it, but, if not, its well worth the read.
----
http://retroguy.org
Posts: 18
Dear Bharat,
Thank you very much for you excellent documentation. I am reading through it now. I have a task at hand which is difficult as I am completely new to PHP. My goal is to build a virtual museum for a friend of mine. Of course gallery 3 based. The main challenge is to augment the system with more 'page types' - at least I think that is the preferred solution.
These are the adjustments I would like to implement:
homepage : an album which does not show pagination and slideshow button.
informational page: basically an album without sidebar and pagination. It should show 1 photo (which I will place in it) and have a text block next to it (or wrapped around it). The text can be hard-coded as it will be static.
Questions:
- Should I introduce extra page subtype for my needs? I can see that the page subtype is checked in numerous places, but I don't know where it is set. I could then filter out layout elements based on page subtype to realize my informational page.
- I have tried to switch off the paginator, when there are no more than 1 pages by setting auto_hide = TRUE. But this does not work alas. What am I doing wrong?
Much obliged to whoever can help out! Thanks in advance.
Posts: 1857
@measwel:
Not sure I'm clear on the goal, but seems that you can accomplish it without a new page type.
For homepage: Just take the pagination and slideshow code and wrap it in an if statement that doesn't display if the current item/album doesn't have a parent (or you could use if id is 1).
http://gallery.menalto.com/node/99272
For informational page: Could you use the about menu item to do this? (Just don't call it "about.")
http://codex.gallery2.org/Gallery3:Modules:about
May want to start a new thread for this.
Posts: 51
hello bharat
wow its awesome... ^^
Posts: 7
Great docs. I'm new to PHP and definitely clueless on the Kohana framework, but it seems this might need correction:
To match the previous example, should the file be "modules/example/views/foo_bar.html.php"? Not nitpicking, but for a noob it might cause some confusion =)
Posts: 2
thanks for the docs. it's helpful!
Posts: 25
Thank you for the docs, they are really interesting. Some details are still missing but it gives a good overall view of the architecture and the requisites to develop new modules.
Posts: 34
Still waiting the "Embedding" doc..
xD
Posts: 573
Embedding / integration is not available in 3.0.x. That feature will be available in 3.1.
--
For Gallery 3 modules and themes, visit GalleryModules.com.
For PHPNuke, phpBB2, and phpBB3 integration help, visit NukedGallery.net.
Posts: 34
Wow really.. whos idea was it to leave that out? id consider it a major feature that should be standard.
Posts: 225
Oh I see. You're the one developing this software for free right? No? Huh. My mistake.
FAQ: Where's feature X? It's really important to me!
Tomek
FWIW, I'm not a dev either. Just a happy user.
----
Publish on Gallery 3 (WLPG Plugin) | XMP Module
Posts: 1857
Quick fix to @tkott's link: http://codex.gallery2.org/Gallery3:FAQ#Where.27s_feature_X.3F_It.27s_really_important_to_me.21
Posts: 34
--
I'm just saying that so many people used the embed feature in G2 as did I, just seems a bit silly not to include it. I've been using G2 for years.. no need to get defensive about it.
Posts: 7994
@Burnouts: If it didn't cost anything, I'd agree with you. But creating a good embedding system is very hard and takes a lot of time. We opted to put out a good standalone product first, and we'll work on a good embedding system second. Sorry if this isn't the priorities that you'd like to see, but there are only 2 core developers right now and we're pretty busy. If you'd like it to go faster, encourage more folks to come help us with the code.
---
Problems? Check gallery3/var/logs
file a bug/feature ticket | upgrade to the latest code! | hacking G3? join us on IRC!
Posts: 28
This is helpful, but I'm looking for the event reference... that's what I'd really like right now. Not sure you could crank that one out or not. I've hired someone to make some personalized modules for me and she really needs this.
Posts: 96
This is great! I really hope to see it fleshed out more, as I am a novice with PHP, but would really love to be able to contribute by making modules or something. So a bit more depth on a tutorial to creating modules would be fantastic.
Thanks!
Jon Reynolds
www.jcrdevelopments.com
Posts: 42
I have taken a stab at adding some documentation on the current event hooks in G3.
It is available at: http://codex.gallery2.org/Gallery3:Developer_Handbook:Event_Hooks
I would greatly appreciate any feedback on this. I gathered most of the information by digging through the code and via a module which trapped of these event hooks and displayed the passed arguments. I am sure there are errors and omissions that should be fixed.
I have added some links to this page in the Modules overview page http://codex.gallery2.org/Gallery3:Developer_Handbook:Gallery3_Modules