UUGALLERY MANUAL
UUGallery builder is WordPress-based plugin which creates SEO optimized galleries within a few clicks automatically and integrates them in a blog post. It resizes thumbnails, links them to full-sized viewer, uses sharpening for creation great-looking galleries, has manual cropping and more than 30+ features.
If you have questions and feel they should be added to the Manual/FAQ please post them below.
Table of Contents
Requirements
- Linux/Unix/FreeBSD platform with Apache;
- PHP4.3.3 or better, PHP5.x is also great. UUGallery is designed to meet mininum requirements so it works on all PHP4.3.x and better;
- either libCUrl or fopen library for grabbing galleries from FHGs. UUGallery automatically chooses the one you have;
- GD2.0 library for thumbnails creation;
- Memory limit is at least 64 Mb (128 Mb is recommended for handling large images from modern 20Mpx cameras);
Memory limit is a maximum amount of memory a script may consume while resizing, sharpening images and building a gallery. UUGallery manipulates images using GD library and it is highly recommended to set php 'memory_limit' setting to at least 64Mb or even to 128Mb for resizing and cropping job which covers all image sizes. Ask your hosting to increase 'memory_limit' for PHP scripts up to 64MB. This should be changed in php.ini or via cpanel, which changes php.ini indirectly for you. You can use this formula to calculate amount of memory you need: Width X Height X 5. For example: 800x600 image would require: 800x600x5 = 2,400,000 bytes = 2.4Mb of memory; 1024x768x5 = 3.9Mb; 1949x2895x5 = 28Mb; 2912x4368x5=64Mb; Add 10Mb on top of this value for php run-time interpreter and you will get the final figure. If you are going to grab large images, it is great to set the 'memory_limit' to 128Mb;
- Max_execution_time is at least 1 minute (10 minutes is recommended for handling large videos).
This is important because galleries grabbing process can take from ten seconds up to a minute or more which depends on a number of photos and their sizes. If you grab videos from internet it can take longer time which depends on amount of videos, connectivity speed between your server and the server where you grab videos from and if you want to convert videos to FLV format at your the server it will also take time and depends on your server's processor speed. The recommended setting which would cover all cases successfully is 10 minutes. If UUGallery halts and produces no error it usually means that the execution process was stopped by the server due to small execution_time allowed; Such a limitation mostly happens at rare shared hosting accounts which resources are strongly limited.
- Zend Optimizer installed;
Optional requirements:
- FFmpeg (SVN-r10891 or newer )
FFMpeg is required for converting videos to various formats such as FLV, MPG, AVI, etc, and for generating custom thumnails from the videos. If you don't have ffmpeg uugallery will use the existing thumbnails which are available at video-FHG when grabbing and a slider for selection a custom frame as a preview will not be available;
- either UNZIP or ZZIPlib extention for PHP. For unpacking galleries in zip files. UUGallery automatically chooses the one you have;
- FTP extention for PHP. If you want uugallery to upload the files to some static ftp server, you need this extension installed;
- shell_exec enabled in order to run ffmpeg and unzip;
Quick start
Step1: Select and Insert your customized template to the Wordpress writer...
Step2: Specify an URL to grab a gallery from FHG (or upload photos to in ZIP file)...
Step3: Click Publish!
The main thing to know about the templates is that UUGallery needs #thumb# tag to be placed in the post body and the tag will be replaced by actual html image link automatically when gallery is created. For instance, if your gallery has ten images you need to place ten #thumb# tags. You can also use loop tag which is described below in Post Textarea section. The #thumb# tag can be wrapped by all possible html code. If the post body contains no #thumb# tags, UUGallery will not process the post and the post will be treated as a usual wordpress post.
Templates Bar
This is how gallery templates bar looks:
By default uugallery has 6 predefined gallery templates. Templates store all setting of the following tabs: 'Basic settings', 'Additional', 'Video Player' and the actual template code of the post area (the big text area where you write your posts).
When you click 'Save' button the settings from the specified tabs and the post area are saved to the selected template.
To quickly recall all the settings you just need to click 'Insert' at the top.
To create a new template you need to click 'New' button. TIP: In order to create a template quickly we suggest you to 'Insert' any existing template first, customize it according to your needs and then click 'New'. In this case you will not have to fill all the fields by hands. After you Inserted a template, changed its settings, you can click 'New' button to give the template new name.
Predefined templates
contains 3x5 fixed table and looks like:
contains a table with 3 columns and #STARTLOOP# tag (described below) and a predefined setting for grabbing a gallery from URL. The #STARTLOOP# makes number of rows flexible and adds as many rows as many photos you have in your gallery. Looks the same like simple template.
contains 1 big thumb and a few smaller ones beneath it.
contains 2 big thumbs in the corners of the template. The first big thumb is contained in the left-top corner and the second thumb at the right-botton.
- Videos embedded on ext. page
contains two videos which are converted to FLV format and linked to the external page which are linked to the external page with flash player.
- Videos embedded on blog page
contains two videos which are converted to FLV format and embedded right on your blog page. The option where to embed the videos can be set in the «Additional» tab in «Convert videos to:» and «Embedded:» drop-down menu;
List of tags
«Path at this server» field
#id# - all posts and pages in Wordpress have their unique id. You can specify #id# tag as a part of folder name so you will not need to enter unique folder name each time. For example: galleries/BestCarsGallery#id#
«#thumb# format» field
Allows you to fully customize the appearence of #thumb# tag, add your styles, css-classes and borders around the thumnail to make it look like you need. This field contains the following subtags:
#LINKTO# - url where the thumb will be linked to (directly to big-photo, to full-sized viewer, or to a sponsor url, this can be set in 'Link thumbs to' field);
#ALT# - an alternative description for SEO purposes from 'SEO Thumbs Alt' field;
#THUMBURL# - url of the thumnail;
#WIDTH# - width of the thumnail;
#HEIGHT# - height of the thumnail;
«Custom Field1», «Custom Field2», «Custom Field3» fields
Allows you to specify descriptions, additional banner codes, 2257 info of the gallery. These fields are displayed in the full-sized viewer and their location can be easily changed inside galleries/viewer.php
You can fully customize the player appearence for video files or even use your own player.
«Player code» field
#WordPressDir# - URL to your wordpress main page;
#WIDTH# - width of video clip;
#HEIGHT# - height of video clip;
#VideoURL# - URL to the video clip;
#PreviewURL# - URL to a jpeg-frame which is showed until user clicks the play button (it is showed in FLV player only);
#UniqueID# - javasript unique id for players. Required for technical purposes to display several video players on a page when when each player has to have unique id to avoid interfering with another player;
This is the place where you actually create the shape of your gallery. You can fully customize your gallery using full power of HTML language which can be editied in any HTML editor and then copy-pasted back to the Post Textarea. The list of tags you can use in the Post Text area shown below:
#thumb# - displays a thumbnail with the default width and height defined in 'Additional' tab 'Thumbnails height and width' fields.
#thumbWxH# - you can set different sizes for every thumb. It overrides the default sizes. For example: #thumb400x300#
#STARTLOOP##ENDLOOP# - loop tag. Enumerates all the photos in a gallery and displays as many thumbs as you have automatically. The advantage of #STARTLOOP# is that you don't have to know how many images in your gallery as #STARTLOOP# creates as many #thumb# rows as you need. This makes template flexible and allows using it for different amount of photos. For example, if you have 15 photos in a gallery and the following template:
#STARTLOOP#
#thumb# #thumb# #thumb#
#ENDLOOP#
will produce this output:
#thumb# #thumb# #thumb#
#thumb# #thumb# #thumb#
#thumb# #thumb# #thumb#
#thumb# #thumb# #thumb#
#thumb# #thumb# #thumb#
to display 15 thumbs.
#linker# - displays a contact form with 'tell to a friend' feature, UBB and HTML linking codes which allows your surfers to share your galleries to each other on boards. Appearence of the linker form can be fully customized and its code is stored in /galleries/icons/linkertemplate.txt
Manual Cropping mode
It allows you to crop thumnails right in your browser and change the cropping area using your mouse. No other difficult settings or operations. The manual cropping page can contain both videos and photos simultaneously.
If you work with videos it allows you to select a frame-preview for the video player by dragging a slider using your mouse.
You can reorder the thumbs/videos right in your browser simply using drag-n-drop.
You can also select what images will be used for the gallery by checking/unchecking the checkbox 'use for gallery'.
You can click Preview button at the bottom and the gallery will be built and opened in the new window. You can close the new window, reorder/crop thumbs and see the preview again.
Full-sized Viewer
The viewer displays full-sized photos of the gallery when one clicks at the thumb. The viewer can also display embedded videos.
The file is open-source and its appearence can be fully customized. It is located in /galleries/viewer.php
You can use the following php variables in the viewer.php because it is php file:
$PrevLink = displays link to the previous full-sized image. If it is the first image, the link will be inactive.
$NextLink = displays link to the next full-sized image. If it is the last image, the link will be inactive.
$TopBanner = displays 'Big top banner' field;
$BottomBanner = displays 'Big bottom banner' field;
$GotoGallery = displays go to the post link;
$GoToMainPage = displays go to the blog main page;
$BigLink = the link of full-sized photo. If surfer clicks full-sized photo he will be sent to this link. It can be next image or sponsor url which is set in 'Advanced' tab in 'Big pic redirect';
$Custom1 = displays info of the custom fields, if any
$Custom2
$Custom3
Moreover, the appearence of the $PrevLink, $NextLink and $BigLink can be customized right in the full-sized viewer in the first 10 lines of the file.
FAQ
- How to edit a template?
- How to edit an existing post and parameters of full-sized viewer?
- How to specify different thumb sizes?
- How to display first few images on the main pages and the rest of the images in the actual post?
- How to create a gallery with a few thumbs on the main page and have other thumbs splitted by pages?
- How to create multiple galleries in one post?
- How to display mailto form at my blog?
- How to customize full-sized viewer?
- How to backup the templates?
- How to edit a template?
You need to select a template in the drop-down menu and click "Insert" button. Then you can change all possible setting and click "Save" button at the top and your settings will be saved and available when you click "Insert" next time.
How to edit an existing post and parameters of full-sized viewer?Go to Manage->Edit_Pages or Manage->Edit_Posts, simply change fields and click Save Post below.
How to specify different thumb sizes?Use #thumb200x300# to display thumb with 200 pixes width and 300 pixels height.
How to display first few images on the main pages and the rest of the images in the actual post?You don't want to display all the thumbs at the main page? No problem! You can display just a few at the main page and all other thumbs in the post. All you need is to use <!--more--> tag which will allow you to split the gallery. This tag is internal Wordpress tag which is available in Wordpress by default. You can find more details about the <!--more--> tag in WordPress manual:
http://codex.wordpress.org/Customizing_the_Read_MoreThere is one nice trick you might want to use. You can define custom text for more tag like <!--more Your custom text -->.
Sample:
Great gallery
#thumb# #thumb# #thumb#
<!--more-->
#thumb# #thumb# #thumb#
#thumb# #thumb# #thumb#
#thumb# #thumb# #thumb#
#thumb# #thumb# #thumb#
will display 3 thumbs only at the main page and a link below "Read more" will be added below automatically. When surfer clicks the link he will see the post which has all thumbs of the gallery.
Multiple Galleries in a Post Sample (click on it to see actual post)
To avoid unclosed tags keep in mind that the segment before <!--more--> tag must have all its opening and closing tag like this:
Correct sample
<div>
Segment shown at the main page of the blog
#thumb# #thumb# #thumb#
</div>
<!--more-->
<div>
Segment shown when user click More link
#thumb# #thumb# #thumb#
#thumb# #thumb# #thumb#
#thumb# #thumb# #thumb#
#thumb# #thumb# #thumb#
#thumb# #thumb# #thumb#
</div>
You cannot open the tag in the first segment and close it in the second because the second segment is not displayed at the main page so the closing tag will be hidden as well and it can make the page look incorrect.
Wrong sample
<div>
#thumb# #thumb# #thumb#
div tag should be closed here
<!--more-->
new div tag should be opened here
#thumb# #thumb# #thumb#
#thumb# #thumb# #thumb#
#thumb# #thumb# #thumb#
#thumb# #thumb# #thumb#
</div>
How to create a gallery with a few thumbs on the main page and have other thumbs splitted by pages?All you need is just to combine the previous techniques and <!--nextpage--> which is also buildin WordPress tag. More info you can find there:
http://codex.wordpress.org/Styling_Page-LinksThe following template will create a post splitted on 4 pages with page numbering which is also can be customized right in Wordpress theme:
Thumbs displayed at the main page
#thumb# #thumb# #thumb#
<!--more-->
<!--nextpage-->
Page 2
#thumb# #thumb# #thumb#
<!--nextpage-->
Page 3
#thumb# #thumb# #thumb#
<!--nextpage-->
Page 4
#thumb# #thumb# #thumb#
Please note again, if you use html tags you must be opened and closed in each page segment to avoid unclosed tags.
<div>
segment1
#thumb# #thumb# #thumb#
</div>
<!--more-->
<!--nextpage-->
<div>
segment2
#thumb# #thumb# #thumb#
</div>
<!--nextpage-->
<div>
segment3
#thumb# #thumb# #thumb#
</div>
<!--nextpage-->
<div>
segment4
#thumb# #thumb# #thumb#
</div>
It looks like this:
Gallery with a preview and splitted on pages (click to see actual post)
The same gallery can be done with #startloop##endloop# tag to make the template shorter:
<div>
Thumbs displayed at the main page
#thumb# #thumb# #thumb#
</div>
<!--more-->
#startloop#
<!--nextpage-->
<div>
#thumb# #thumb# #thumb#
</div>
#endloop#
How to create multiple galleries in one post?You can create POSTS and PAGES in wordress using "Write->Write_Post" and "Write->Write_Page". The main idea to understand that POSTS are shown at the main page and PAGES are hidden.
All you need is to build several galleries as PAGES and then insert a few thumbs in POST and link them to the PAGES. Follow these steps:
1. Go to "Write->Write_Page" and create several galleries like you usually do using UUGallery.
2. Go to "Manage->Edit_Pages" and click Edit to open posted gallery for editing.
3. Once PAGE is saved it has URL which you can see in the "Manage->Edit Pages".
4. Go to "Manage->Edit_Pages" and copy one thumb from post body to clipboard.
5. Go to "Write->Write_Post" and paste a thumb to post body. Repeat this step for all PAGES you posted at the step 1. TIP: you can open a new post in the new window and paste the thumbs there in order switch less between windows.
6. Once you pasted the thumbs you need to link them to appropriate PAGE url which contains full galleries. That's all. Click Publish.
Done! You have posted a POST with thumbs which are linked to different to PAGES (or galleries in other words). Here is how it looks:
Multiple Galleries in a Post Sample
How to display mailto form at my blog?Use #linker# tag anywhere in your post body. It looks like this:
How to customize full-sized viewer?Login via ftp and go to /galleries/viewer.php file which is open-source and can be fully customized according to your needs. You can change design, header, footer, add your own custom sidebars, everything.
How to backup the templates?Templates are stored in /galleries/data/templates.txt file which you can backup. Please remember to set writable permission for this file after you restore it from backup to allow UUGallery to write to this file.
Common problems
- I create and add new template but it doesn't appear in the templates bar.
- "Fatal error..." - not enough memory
- How to install and configure ffmpeg properly?
- When I click "Publish" nothing happens. Why?
- The demo gallery published each time even though I enter a my own URL, what I do wrong?
- Full-sized page looks incorrect, why?
- I create and add new template but it doesn't appear in the templates bar.
Check if you are using "wp-super-cache" plugin. This plugin doesn't cache wp-admin files because they are added to exceptions. But it caches the page which shows you uugallery templates. So when you save templates via /wp-admin/ area it is saved, but you retrieve and see an old, cached version.
To fix this you need to add templates bar to cache exceptions:
1. Go to "Options->WP Super Cache".
2. In "Accepted filenames, rejected URIs" section find field named "Rejected URIs";
3. Add "ShowTemplateBar" without quotes to that field and click "Save Settings".
- "Fatal error..." not enough memory
You need to set memory_limit setting for you php to at least 64 Mb (128 Mb is recommended for handling large images from modern 20Mpx cameras);
Memory limit is a maximum amount of memory a script may consume while resizing, sharpening images and building a gallery. UUGallery manipulates images using GD library and it is highly recommended to set php 'memory_limit' setting to at least 64Mb or even to 128Mb for resizing and cropping job which covers all image sizes. Ask your hosting to increase 'memory_limit' for PHP scripts up to 64MB. This should be changed in php.ini or via cpanel, which changes php.ini indirectly for you. You can use this formula to calculate amount of memory you need: Width X Height X 5. For example: 800x600 image would require: 800x600x5 = 2,400,000 bytes = 2.4Mb of memory; 1024x768x5 = 3.9Mb; 1949x2895x5 = 28Mb; 2912x4368x5=64Mb; Add 10Mb on top of this value for php run-time interpreter and you will get the final figure. If you are going to grab large images, it is great to set the 'memory_limit' to 128Mb;- How to install and configure ffmpeg properly?
This info is intended for system administrators or it can be helpful for you if you have linux configuration skills.
You need to have root access and login to your server via SSH.
The main ideas you need to achieve when installing ffmpeg are:
1. make sure that ffmpeg is seen in default PATH at your server so uugallery is able to call it;
2. make sure that ffmpeg is compiled with --enable-libmp3lame setting to have sound in FLV video when converting.
So let achieve these two requirements.
Check first if you have ffmpeg already installed at your server. Type in SSH:
ffmpeg -i
You should get either "bash: ffmpeg: command not found" or the following:
FFmpeg version SVN-r10891, Copyright (c) 2000-2007 Fabrice Bellard, et al.
configuration: --cc=/usr/bin/gcc4 --enable-libmp3lame
libavutil version: 49.5.0
libavcodec version: 51.47.2
libavformat version: 51.17.0
built on Nov 1 2007 02:34:57, gcc: 4.1.1 20070105 (Red Hat 4.1.1-53)
ffmpeg: missing argument for option '-i'
You must have ffmpeg not older than this SVN-r10891 version otherwise you need to reinstall it.
Lets do the installation:
1. type in SSH:
svn checkout svn://svn.mplayerhq.hu/ffmpeg/trunk ffmpeg
latest ffmpeg snapshot will be downloaded from their web site. If you get "svn: ffmpeg: command not found" you need to install svn. For additional information, see http://subversion.tigris.org/.
2. type in SSH:
./configure --enable-libmp3lame
make
make install
If you got an error after ./configure line you need to install libmp3lame before configuring ffmpeg. You can download libmp3lame there: http://lame.sourceforge.net/download.php. You don't need any sophisticated configure line, you only need to enable libmp3lame. If you get an error in v4l module, try to disable it and use this configure line instead (also you can disable ffserver and network protocols which were added in the latest ffmpeg version):
./configure --disable-indev=v4l --cc=/usr/bin/gcc4 --disable-ffserver --disable-protocols --disable-network
Done, now you have the latest ffmpeg installed. You don't have to configure UUGallery as it finds ffmpeg automatically.
- When I click "Publish" nothing happens. Why?
Check the textarea contains at least one #thumb# tag. If you have no #thumb# tags there your gallery will not be processed and the post will be treated like usual text post with no galleries.
- The demo gallery published each time even though I enter a my own URL, what do I do wrong?
Check the you Select a template and click "Insert" first and only then enter an URL. If you enter your URL first and click "Insert" afterwards, your URL will be replaced by the default one and you will get a demo gallery.
- Full-sized page looks incorrect, why?
This means your theme header and footer are not separated correctly. Every wordpress theme has it's own header and footer which are different files. UUGallery Full-sized viewer is displayed by /galleries/viewer.php file and calls theme header and footer and places a big photo between them. According to Wordpress theme standard the header and footer of your theme must be designed separately to allow inserting any content between them.
If your page looks incorrect:
1. Ask your designer to make header and footer logically independent so that any content can be placed between them.
2. If you cannot figure out in theme files and don't know how to change header and footer, you can completely remove the header/ footer calls from the full-sized viewer and place your own, actual html code there. This will allow you to customize the page and make it look correct, exactly how you like. Because viewer.php is completely customizable.
