Gallery2 and the Drupal gallery module is complex stuff. Especially new users are confronted with a large number of options that are almost impossible to understand without some basic knowledge of Gallery2 and Drupal. We definitely need a comprehensive handbook for the gallery module (and its affiliates) at http://codex.gallery2.org/Integration:Drupal. The main purpose is to lower the barrier for new users and to reduce the number of support requests dealing with the same questions again and again.

Here is a draft of the possible handbook structure I would like to assemble in the codex wiki. Any help would be greatly appreciated.

* Installation : Quick Guide
  * Comprehensive Guide (Gallery2 + Drupal 'Install' tab)
  * URL Rewrite
* Configuration
  * General
  * Filter
  * G2Image
  * Search
  * Blocks
    * Image Block
    * Grid Block
  * User
    * User sync
    * Profile (gallery_profile)
  * Menu (gallery_menu)
  * Content (gallery_content)
* Troubleshooting
* FAQ
  * Tips and Tricks (Snippets / API)

I will start by creating empty handbook pages for these categories and try to fill the gaps over the next few weeks. The 5.x-2.x branch of the module is almost ready for a stable release, but I would like to get the main pieces documented beforehand.

This thread is mainly a placeholder and a central place to coordinate the documentation tasks.

Comments

thumb’s picture

thumb commented

You read my mind :) Count me in. Should version specific heading be added for install (i.e. 4.7, 5.x)? Although I know 'Quick Install Guides' are common place, I think the use of 'quick' might set unreasonable user expectations, especially for new users. I'm throwing out a draft of install step order

@ Installation
* Overview & Requirements (Gallery 2, Drupal)
* Gallery Module Install Steps
1. Enable and configure required/desired Gallery 2 modules (rewrite, block, frame, registration, etc.)
2. Download, unpack gallery.module (recommended locations for single vs. multisite)
3. Enable gallery.module, menu, profile
4. Configure module Site Configuration -> Gallery Settings ('Install' tab)
a. PHP memory
b. Gallery2 locations (automatic vs. manual)
b. Drupal Modules / Gallery2 Plugins
c. Clean URL / URL Rewrite (single vs. multisite)
@ Configuration
* General
* Filter
* G2Image
* Search
* Blocks
- Image Block
- Grid Block
* User
- User sync
- Profile (gallery_profile)
* Menu (gallery_menu)
* Content (gallery_content)
* g2image for TinyMCE
@ Troubleshooting
@ FAQ
@ Tips and Tricks (Snippets / API)

thumb’s picture

thumb commented

Forgot to add a Theme heading. I think a link to the existing codex page on Embedded Theme considerations might work. http://codex.gallery2.org/Gallery2:Themes:Embedded_Theme_Considerations

profix898’s picture

profix898 commented

Did you notice http://codex.gallery2.org/Integration:Drupal:Installation? The old install guide (slightly modified) is now titled 'Quick Start' and I added a more detailed installation tutorial at the above location. There are already some links to the (still missing) 'URL Rewrite guide' (http://codex.gallery2.org/Integration:Drupal:Installation:URL_Rewrite).

Should version specific heading be added for install?

I dont think we need that. We will drop support for 4.7 shortly (with the release of Drupal 6) and the module versions for 5.x and 6.x will be similar enough to follow the instructions. Please also note that all documentation at codex is updated for the 5.x-2.x series of gallery module already.

Forgot to add a Theme heading.

Good point :) But I'm not sure a link to 'Embedded Theme Considerations' is sufficient. I'd actually prefer to take some pieces from that page to create a Drupal-specific one. The text should also mention gallery.css and what it is designed for (Garland+Matrix and as a starting point only). For G2.3 we will have the ability to switch the G2 theme for embedded operation and the D6 version of gallery module will support gallery-g2theme.css (= G2 theme specific css overrides from Drupal). All this will be added to the handbook at some point, so we should have a dedicated page for it.

Configuration (i.e. General, Filter, Blocks, etc.)

I started to think about detailed descriptions for all the options available in gallery module. But the on-page documentation is quite verbose and I'm unsure what else is needed. I guess my point of view is aligned with the Drupal/Gallery way of things too much already.

I'm only little experienced in creating wiki pages and especially in structuring wiki content. Note that the G2 codex has its own guidelines (http://codex.gallery2.org/Codex:Guidelines) and is double-checked by G2 staff frequently. For example they added [[Category:Integration:Drupal]] at the bottom of each page, but the link doesnt point to a valid page e.g. to an overview of pages as I assumed initially. I'm still trying to find my way around the codex (and wikis in general), so it would be great if you could help out.

thumb’s picture

thumb commented

Did you notice http://codex.gallery2.org/Integration:Drupal:Installation? The old install guide (slightly modified) is now titled 'Quick Start' and I added a more detailed installation tutorial at the above location.

Yup, I noticed. I'll take a first pass at the URL Rewrite tonight.

But I'm not sure a link to 'Embedded Theme Considerations' is sufficient. I'd actually prefer to take some pieces from that page to create a Drupal-specific one. The text should also mention gallery.css and what it is designed for (Garland+Matrix and as a starting point only).

Sounds good.

I started to think about detailed descriptions for all the options available in gallery module. But the on-page documentation is quite verbose and I'm unsure what else is needed.

I imagine that we'll have plenty of links to exiting Gallery module docs in the wiki so that the focus remains on gallery.module capabilities.

I'm only little experienced in creating wiki pages and especially in structuring wiki content. Note that the G2 codex has its own guidelines (http://codex.gallery2.org/Codex:Guidelines) and is double-checked by G2 staff frequently. For example they added [[Category:Integration:Drupal]] at the bottom of each page, but the link doesnt point to a valid page e.g. to an overview of pages as I assumed initially. I'm still trying to find my way around the codex (and wikis in general), so it would be great if you could help out.

I've written a bit of Gallery's theme documentation. I can handle linking to relevant pages, etc. to try and let you keep coding.

thumb’s picture

thumb commented

Edited Integration:Drupal to improve the description for folks who have no idea what gallery.module does. Also posted a first draft of the clean url steps. Please review these and either make changes or post comments here. I'll continue to go through and make edits through the next few weeks and add screenshots.

profix898’s picture

profix898 commented

bug report/feature request links on Integration:Drupal

Nice work on the Integration:Drupal 'frontpage'. I really like the block on the right. It nicely structures the page. But unlike you wrote bug reports and feature requests should be handled in the issues tracker and the integration forums are for support requests only.

the focus remains on gallery.module capabilities

Sure. I think we have 2 aspects here:

  1. What's the relation between Gallery2 and Drupal as implied by the gallery module? The bigger picture of everything around the module and the two systems. This can be covered with a few paragraphs and (many) links to existing docs.
  2. How can I utilize the module for my purpose? What does it do for me? How can I install it? What options do I have to customize the embedded gallery? The actual configuration of the module.

The question is how to document the options and stuff gallery module provides. I mean it doesnt help anybody to mirror the on-page documentation (the description text displayed with all the form elements) to the wiki. I think the focus should be on what a settings is good for! Why should I (as a user) touch it and what effect does it have on my embedded gallery? We should try to provide some background information and guidelines for less experienced users (preferable with screenshot, examples, ...).

Edited Integration:Drupal to improve the description for folks who have no idea what gallery.module does. Also posted a first draft of the clean url steps. Please review these and either make changes or post comments here. I'll continue to go through and make edits through the next few weeks and add screenshots.

Thanks for taking this. I skimmed your draft and it has some good points. Here are a few things I noticed:

  • "select Site Configuration->Gallery Settings"
    We should try to make this kind of reference uniform across the pages. I used a syntax as follows on the other pages "... browse to Administer > Site building > Blocks (admin/build/block) ...". I think that makes it very clear for users where to look for an option, even for new Drupal/G2 users. The additional (drupal/path) notation introduces helpful redundancy. We can use a different syntax if you like, but it should be uniform throughout the documentation.
  • "Select the Install tab"
    Everything that can be found literally on the page, i.e. labels for sections, button, etc., should be quoted like this "Select the "Install" tab.". We can (and should) try to find different words to explain certain aspects, but instructions should be as close as possible to the module text to avoid confusion.
  • All in all I think the description of how to manually merge the different rewrite rules is too short. It should be a little more verbose and perhaps it should include example code, i.e. take two fictional sites "firstsite.com" and "secondsite.net" or sth.

I can handle linking to relevant pages, etc. to try and let you keep coding.

That's awesome! Does it mean you plan to help with documentation (and support?) for a longer period of time? Or is it just to get the initial docs done? In either case your help is very welcome and greatly appreciated. Thanks a lot.
Whats your background? Developer, Designer, User? How long have you been using G2 already? I'm just curious why you join in now ;)

thumb’s picture

thumb commented

I think the focus should be on what a settings is good for

Point taken. I'll take this into consideration for the next edit of the rewrite page.

We should try to make this kind of reference uniform across the pages. I used a syntax as follows on the other pages "... browse to Administer > Site building > Blocks (admin/build/block) ..." ... We can use a different syntax if you like, but it should be uniform throughout the documentation.

Yes, consistency is good and I'm fine with the notation for menu paths (>), but not sure about admin/build/block. I'll look around at other standards.

Everything that can be found literally on the page, i.e. labels for sections, button, etc., should be quoted like this "Select the "Install" tab."

How about using bold or italic and reserving quoted text for text to be entered or messages?

...manually merge the different rewrite rules is too short. It should be a little more verbose and perhaps it should include example code, i.e. take two fictional sites "firstsite.com" and "secondsite.net" or sth.

Agreed. I'll expand it.

Does it mean you plan to help with documentation (and support?) for a longer period of time? Or is it just to get the initial docs done?

I can help with the initial documentation effort but probably not much in the way of support after that. I monitor tracker posts during the day but, as you've probably already noticed, I usually can't reply until evenings or weekends.

Whats your background? Developer, Designer, User? How long have you been using G2 already? I'm just curious why you join in now ;)

All of the above. I've used Gallery since 2002 and joined their team as UI developer about 3 years ago (Matrix/Floatrix themes, installer/upgrader). I've been a Drupal user for almost 3 years now and appreciate the work you, Kieran, and Walkah have put into this. I also heard that you were working with valiant to migrate GalleryEmbedded data over to gallery.menalto.com.

Just wanted to say thanks and I must admit I'm anxious for the next gallery.module release :)

thumb’s picture

thumb commented

I forgot to ask if you expect any significant changes to the current gallery.module ui before final release. I'm guessing no, but wanted to make sure before I start making screen shots. Oh, and sorry, I forgot to use blockquotes around the last post's quoted text. I really wish I could edit posts here after the fact to fix that kind of stuff.

profix898’s picture

profix898 commented

I'm fine with the notation for menu paths (>), but not sure about admin/build/block.

In my experience (from doing support work) Drupal users are much more path-oriented than G2 users. I mean (almost) nobody types the path to the a certain admin page in G2, but Drupal users do. And they do the more they are used the Drupal path-pattern. I found it helpful to provide the menu path to a certain setting in addition to Adminster > ... Why do you think its not a good idea?

Everything that can be found literally on the page ... should be quoted. > How about using bold or italic and reserving quoted text for text to be entered or messages?

I'm very uncertain here. I think bold text should be used to emphasize really important lines only (e.g. Do not install G2 at drupaldir/gallery and stuff like that). Italic text might work. What is your preference?

I've used Gallery since 2002 and joined their team as UI developer about 3 years ago (Matrix/Floatrix themes, installer/upgrader).

Aha. So you could probably take a start to build a gallery-matrix.css (or -floatrix.css)? The current gallery.css (although mainly for Matrix+Garland) tries to provide some generic styles to embed a G2 theme into Drupal, but it would be great to have a more sophisticated G2 theme-specific stylesheet for users without detailed css knowledge/experience. Matrix/Siriux + Garland would be great, I guess.

I also heard that you were working with valiant to migrate GalleryEmbedded data over to gallery.menalto.com.

I'm short of time atm, so it might take a few weeks, but yes we will migrate the phpBB forums to GMC.

any significant changes to the current gallery.module ui before final release

No changes. The 5.x-2.x series is almost there. Only some smaller issues have been reported for the latest beta. The major bugs have been fixed with the previous betas, I guess. Several people are using the module for production sites already. I'd expect the final release in about 2 weeks.
Similar to gallery_menu upcoming new modules/features will add an additional tab to the 'Gallery settings' or 'Gallery users' section in Drupal, so we wont have (many) changes to existing forms. New features in G2.3 (such as reviews #402 and #406) will - of course - impact on existing forms as well.

While the older modules provided a pretty thin wrapper around G2, the new module tries to bind G2 closer to Drupal. For that many changes to the internal module structure were needed, so that we now have a more logically structured and API-oriented module. For D6 the first release will be almost identical to the 5.x-2.x series except for the internal changes required to match and take advantage of the D6 API (e.g. batch API, drupal_alter() hook, ...). Sometime at the end of 2007 we will hopefully have a first version of gallery_content (http://drupal.org/node/138400) available for testing.

thumb’s picture

thumb commented

I won't be around for a few days, Halloween costume making tonight and trick-or-treating tomorrow. Just a quick reply, then back to it for me.

Is there a Gallery group at http://groups.drupal.org? Would it make sense to create one, or is the integrations forum on Gallery's site sufficient? I ask because I'm interested in general discussions/announcements with other gallery.module users. An example question I have is what is your Drupal embedded Gallery configuration?

In my experience (from doing support work) Drupal users are much more path-oriented than G2 users. I mean (almost) nobody types the path to the a certain admin page in G2, but Drupal users do. ... Why do you think its not a good idea?

I don't consider the notation to be new-user friendly. I consider myself to be an experienced Drupal-user/admin and am not as aware of all Drupal admin paths as you suggest I might be. Experienced Drupal users can translate menu notation (>) to paths.

I'm very uncertain here. I think bold text should be used to emphasize really important lines only (e.g. Do not install G2 at drupaldir/gallery and stuff like that). Italic text might work. What is your preference?

Good point regarding bold text. I'll use italic for now and am not opposed to going through and changing everything later if we decide on something else.

Aha. So you could probably take a start to build a gallery-matrix.css (or -floatrix.css)? The current gallery.css (although mainly for Matrix+Garland) tries to provide some generic styles to embed a G2 theme into Drupal, but it would be great to have a more sophisticated G2 theme-specific stylesheet for users without detailed css knowledge/experience. Matrix/Siriux + Garland would be great, I guess.

I might have time to work on this, but not until the week after next. I'm working a new Gallery theme and have added my own embedded.css that gets included if $isEmbedded returns true. I think this is a good approach and can probably use those styles for Matrix/Floatrix/Siriux. Do you have a list of CSS issues that need to be addressed in each theme?

No changes. The 5.x-2.x series is almost there.

Great. When I return to work on this I'll start making screenshots for Codex.

profix898’s picture

profix898 commented

Is there a Gallery group at http://groups.drupal.org? Would it make sense to create one, or is the integrations forum on Gallery's site sufficient?

I've thought about that several times, but I always hesitated to create just another place for discussion. Maybe its time to try nonetheless. I also thought about a survey: I'd like to collect a list of sites using Drupal embedded G2, learn about the most common configuration and the usage pattern, etc. I will think about that a bit more as time permits.

Edit: New 'Gallery2 Integration' group at http://groups.drupal.org/gallery2-integration. This also allows us to setup polls, wiki pages, etc.

I don't consider the notation to be new-user friendly. ... Experienced Drupal users can translate menu notation (>) to paths.

Feel free to remove/omit the paths then. I really dont insist on it ...

I might have time to work on this, but not until the week after next. I'm working a new Gallery theme and have added my own embedded.css that gets included if $isEmbedded returns true. I think this is a good approach and can probably use those styles for Matrix/Floatrix/Siriux. Do you have a list of CSS issues that need to be addressed in each theme?

Our current stylesheet (gallery.css) works with Matrix/Garland quite nicely. Some other themes, such as Siriux, dont work at all. Thats why we thought to support theme-specific stylesheets. I think this is a 'nice to have' feature, but we shouldnt focus on that now. Lets discuss it in more detail once the initial documentation is completed ... and maybe you will have time to take a start with it then.

I'm currently working at home, so I can answer questions all the day, but this will change shortly. I still consider Drupal development a hobby, what means things may take a while to complete. Dont put yourself under pressure just because I'm quite responsive atm ;)

RickHonda’s picture

RickHonda commented
Version: 5.x-2.x-dev » 5.x-2.2

It looks like its been a while since anyone posted here. I wonder if anyone is even paying attention anymore but I have some input.

I think documentation is much better now than when I first attempted to do the install. As far as just Drupal 5 and Gallery2 I think its just OK besides the fact that the 'Quick Start' guide lists Drupal 4.7.

Right now I am fairly sure that I am doing a correct install of Gallery2 embedded in Drupal 5 with TinyMCE and g2Image integrated and would like to compare notes.

I have never contributed to any documentation or open source project but I'm itching to. I don't know where I should really start and need to know where to put what. For example, where do I put stuff related to TinyMCE and g2Image? It's related so I'm guessing somewhere in http://codex.gallery2.org/Integration:Drupal.

Right now I'm just going to go ahead and do whatever I think makes sense but any feedback would be appreciated.

profix898’s picture

profix898 commented

Its just wonderful to read that you want to help with documentation. Thanks a lot :) You can simply create an account at the codex wiki and start adding/editing content. There is no roadmap for documentation atm, so feel free to arrange the pages at will. The toc for configuration options is designed after the logical layout of gallery module what has some advantages but is not necessarily fixed. For the TinyMCE+G2Image tutorial I think there is an empty placeholder page for this already, but we could also create a new category "Tutorials" or sth. If you think to contribute to this project in the long term we should probably discuss in more details, especially some important changes in G2.3+D6.

Edit: Have you read http://drupal.org/node/282092?