How-to's for TWG

The numbers of the howto's are the order I have created them. I simply could not change them because there are deeplinks from older TWG installs to this page. I have ordered each section how I think how important the howto is.

Summary Howto - Read this first!

Summary Howto

Because TWG does not have any database a lot of extra configuration can be done by simpy creating a file in a folder which then are used e.g. for folder description or a background image. This howto is a a short summary what you can do (a better description is always in the real how-tos!):

private.txt - protect your gallery; The filename can and should be changed in the config.php - more than one password is possible - see how-to 12
private.png - image of a password protected folder when locked - see how-to 12
folder.txt / folder_<language>.txt - Description of a folder that is shown on the thumbnail and if enabled on the image page - see how-to 7
image.txt (php) / image_<language>.txt - a powerful way to include text (even dynamic) on the image page - see how-to 28
foldername.txt / foldername_<language>.txt - The display name of the folder - is used instead the name on the file system. Very helpful for individual sorting of albums! - see how-to 6
albumr/l.txt / albumr/l<language>.txt - album description like on the first page of the Ajax demo - see how-to 32
folder.png - the image that is shown instead the first/random/collage image of a folder - see how-to 5
watermark.txt - The watermark text - see how-to 13
watermark.png / watermark_big.png - The watermark image for the image view / original - see how-to 13
link.txt - if you want to link to a web site instead downloading the original image by clicking on the image put the <a > tag in this file. - see how-to 16
root.txt - You can add a link back to e.g. your homepage. If this file exists you get a home link (or icon) in the left upper corner! You can define the text in the language file: $lang_back_link. If this is not set an icon is shown! + you can create sub galleries with this file - check how-to 21
url.txt - Link to a remote http directory. fsocksopen has to be available. The url has to start with http:// and end with a / and link directly where the pictures are. For images relative folders are supported as well - check how-to 20
back.png - The background image of the folder where it is stored in - check how-to 22
<directory>.zip - The archive where a whole directory can be downloaded - check how-to 19
style.css – you can set an individual style sheet for each folder - check how-to 9
config.php / config_<language>.php - can be used in a folder for individual settings that only should apply for this folder - check how-to 17
config_sort.php - can be used for individual sorting order for subdirectories - check how-to 6
header.htm, top.htm - A header file that is included - the html in there is already in included in a <td></td> - check how-to 3
footer.htm, bottom.htm - A footer file that is included - the html in there is already in included in a <td></td> - check how-to 3
left.htm/right.htm - A file that is included on the left/right - you can put your navigation there - the html in there is already in included in a <td></td> - check how-to 3
overview.htm/thumb.htm/image.htm - html that is included on the overview/thumb/image page - since 1.7 language dependant too! - see how-to 3
folderlink.txt - you can link e.g. to another gallery when you click on a overview link by placing this file in a folder - simply put an <a> tag in this file e.g.: <a href="http://www.spiegel.de">
video.php - very important file if you want to use videos or mp3's - see howto 34 for details!
menu.htm - (new 1.7) you can extend the menu on the right upper side by something you like. Simply create a file called menu.htm in the main folder and put your menu items there.

Please note: The files do NOT exist yet. You have to create them and place them in the described folder. Please use the html representation in the .txt files of special characters: ä -> ä (exception: watermark.txt !).

Since TWG 1.6: Please store all your text files in UTF-8! Then special characters are displayed properly!

That's it ;)

Have fun!

1. How to secure your TWG data

If you install TWG like the installation site says it is working on all systems very quickly. TWG itself is secured against external attacks (like cross-site scripting) because all input parameters are checked and only valid data is processed.

Delete info.php in the main directory if everything works fine. You get even more information in the administration if you have access there.
TWG generates automatically .htaccess files in the counter and xml folder. This prevents that xml and txt files can be accessed from the web directly. Feel free to add more extensions there. If you cannot use a .htaccess file you can set the counter and xml directory with chmod (check your ftp program) to 700 (770 if too tight, 777 if too tight). Nobody has to read this directories from outside.
Set the cache directory with chmod to 744 (774 if too tight, 777 if too tight). The cache directory has to be accessible from everywhere but not to be listed! Don't place a .htaccess file there because TWG does link directly to this folder!
If you use private folders: If you use private folders you should use the .htaccess from inc folder (prevents external access) or change the name of the password file (config.php: $password_file) to .htprivate (".ht" is the important part!) if you are on a unix/linux system with an Apache web server. All files starting with .ht are protected by default. You can use any extension where your web server does not display the files!
If you use private folders or disable the download of the images and you want 100% that no one can access the images directly you should change the permissions of the picture folder or use a htacess (see 4.). Set the pictures folder and all sub folders to 770 OR you place a .htaccess file in this folder. Use the one from the inc folder. It does not allow any access from the web. $enable_direct_download has to be set to false because all download have to be done by calling the image.php!
If you want to protect the images in the cache folder as well you have to set $disable_direct_thumbs_access=true; and $use_direct_small=false; Then you can protect the cache folder like the pictures folder.
If you use e-mail notification: Make sure that e-mail encryption is turned on in the config.php - encrypt_emails=true. This is NOT the default. Please change the encryption key $encrypt_emails_key. If you leave it like it is, anyone who is downloading TWG with this default key can decrypt your emails by debugging TWG!
If you use the external login: Make sure that the external login is disabled in the config.php - $enable_external_privategal_login=false. This is the default. Only turn this on if you need it and if you use encrypted passwords:
Set the flag $encrypt_passwords to true. Choose the encryption method SHA1 or SHA256 (more secure but slower) with $use_sha1_for_password. SHA1 is enough but you have to have PHP > 4.3 installed. otherwise the SHA256 from TWG is used. Call the password.php in the main directory to generate your passwords! You have to enter this password either in your 'private.txt' file or as the default password in the config.php at $privatepassword. Use the encrypted password only for $privatepassword - the other ones are not encrypted if you set $encrypt_passwords to true!
That's it :).

If you have found some more settings to make TWG more save please let me know.

2. How to include TWG into php sites or a cms system (like mambo, phpnuke).

It is now possible to integrate TWG into existing php sites in different ways: You could include TWG by using an extra frame or an iframe. If you want to do this please check the example_i_frame_include.htm. This is the way that works for sure ;).

1. iframe include

All browser handle iframe include a little bit different and I want to tell you the problems that can show up:
If you include TWG in an iframe it's normally shown very nice in Firefox (1.x, 2.x, 3.x), Opera (8.x, 9.x) and Safari. You can simply use e.g.

<td width="100%"><iframe name="twg" frameborder="0" marginheight="0" marginwidth="0" src="twg/index.php" width="100%" height="100%"></iframe></td>

to include TWG in a table cell of you page. Scrollbars are shown nice and work well.

Check your gallery now. If it's displaying fine in all browsers don't continue to read because it might only confuses you ;). I like to have it perfect. If you like it too continue to read ;).

Don't use header.htm, bottom.htm oder footer.htm when using iframe include because IE does sometimes not render this properly. Normally this is not needed because when using iframe include your content should be places outside the iframe.

The problems does occur with IE (6.x and 7). For an optimal integration only scrollbars should be shown if they are really needed. And here IE has a problem. He reserves the space for the scrollbar and this is not very nice. And here is the tradeoff: You can force IE to either

Reserve the scrollbar area (in the background color of your site) and handle scrolling very nice.
Don't reserve the scrollbar area but then the scrolling is not really working anymore because the content is not updated and only a blank area is shown.

But there are solutions ;):

If you have setup your gallery that everything (detail page - top x...) fits into the iframe (=iframe is big enough) then you should do the following:

Add scrolling="no" to your iframe - this is the easiest way and if look optimal in all browsers!

If you want that your iframe can scroll properly and everything looks perfect you have to do the following:

Set iframe include to false ($iframe_include in the my_config.php or in the administration) = default
The color of the reserved space could be different and can be seen. Set the following styles (in your my_style.css or the <skin>.css):
1. body.twg { background-color to the background color of your site - transparent is a color too if you like the background of your site!
2. td.twg_info { background-color to the color you like in the inner area - transparent is a color too if you like the background of your site!
3. Don't use a background image inside TWG - set allowtransparency="true" in your iframe and use the background of your site because you cannot set the color of the reserved space seperately.
4. I always recommend to make it in the background color of your website. Then no one will see it. And turn the border off - gives you alittle bit more space for the images.
Check the layout in the iframe if ie. As you see you now have a ~ 15px space on the left side which IE reserves for the scrollbar. If you have done the color corrections it should be in the background of your site. If this does not bother you - fine. If it does bother you: Create a file called left.htm in the main folder of TWG and copy the following into it: <?php if ($msie) echo '   '; ?> or make a 15px margin in the left side of the iframe. Then the margin is equal on both sides.

I hope this made everything a little bit clearer and does not confuse you even more (please blame Microsoft for not sticking to the w3c standard).
If you think this howto can be improved - please tell me.

2. php include

TWG can be included directly in existing php sites or cms systems. If you want to use 'include index.php' (see example_php_include.php) you have to set the following 2 settings:

$php_include=true;
$install_dir="<relative(!) path to the twg installation>/"; - The / at the end is important! If you e.g. have twg installed in the directory twg relative to your main file then use $install_dir="twg/". If you have installed TWG in a parallel directoy you have e.g. to use $install_dir="../twg/".

All parameters that don't belong to TWG are added again to the url! If your main php file (e.g. gallery.php) has the parameter &id=3 this parameter is added to all links of TWG and all links from TWG use gallery.php instead index.php. If you open the gallery in a new window the standalone modus ia activated again!
If some parameters should not be added to a link in TWG enter these parameters in the config.php: $ignore_parameter

Please note:

If the gallery does not work properly most of the time the doctype is the problem - please remove the one from the calling page and use
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
If the cmotion gallery on the image page does not work: this is the problem. If you have spaces in the collage in Firefox: this is the problem ;)
Chck the iframes. If they are not at the right position the Javascript cannot analyse your design right. There are the following things you can do:
- If you use div's please make sure that you have a simple surrounding div with width,height=100%
- Add style="padding:0;margin:0;" to your body tag. IE does not return this values properly and a small offset will exist.
- You can adjust the position of the iframes from version 1.5.3 with the parameters $iframe_xoffset and $iframe_yoffset in the config. This only works fine if you have a layout that is not browser size dependant.
- If this does not help: set $disable_frame_adjustment_ie=true. Then the iframes are not automatically positioned. If this is the case the language dropdown is at the wrong position. You can either set $show_languages_as_dropdown=false; and remove the languages you don't like from the language folder or modify the offset of the dropdown with $lang_xpos_lang_dropdown which you find at the bottom of each language file because for each language this will be different.
Round corners are not supported because IE does not support this properly in this mode. I maybe try to get this to work in one of the next versions! Right now round corners are disabled automatically if $php_include=true;
If the bottom part seems to be cut of, your surrounding environment has most likely set a table to a fixed height but no height in the cell where the TWG is integrated. Please add the missing height (in pixel not %) to this <td> in your template.
Check the text in $default_text and $email_bottomtext - there is a %s where the link to the gallery is inserted by default. If you use php include this link is wrong (admin does not know your main page) - you have to insert the right link instead of the %s
If you use a char set: use UTF-8 to have a consistent system. Since TWG 1.6 all language files and used char sets are in UTF-8! If you want to change the charset to TWG please change it in the language files - it's definded at the very top.
If you use php include no body tags are written by TWG - This means no style from the body (background!) is used! The background from your main site is used then!

I have only done basic tests on cms systems - if you have any problems - please let me know !

1.4.1 has an enhanced keyboard navigation (t opens title, c opens comments ... - see user help). If you include TWG and you have an input filed on the page too you should set $disable_enhanced_keybord_navigation to true.

3. How to integrate your own HTML into TWG

You can add additional HTML to many parts of TWG. If you don't want to include TWG into an existing page but add an additional footer or header you should use the files described below.

Please note: The files do NOT exist yet. You have to create them and place them in the described folder.

File name	Style (css)	Location	Description
header.htm	twg_headerhtml	TWG folder	Is included above TWG.
top.htm	twg_tophtml	TWG folder	Is included on the top of TWG (before TWG 1.7.8 top.htm was called header.htm - see below for the small difference!).
bottom.htm	twg_bottomhtml		Is included on the bottom of TWG (before TWG 1.7.8 bottom.htm was called footer.htm - see below for the small difference!).
footer.htm	twg_footerhtml	TWG folder	Is included below TWG.
left.htm	twg_left	TWG folder	Is included on the left side - $left_htm_width defines the width of the column
right.htm	twg_right	TWG folder	Is included on the right side. Can only be used if you have a left.htm. If you need only a right.htm create a left.htm leave it empty and set $left_htm_width=0.
overview.htm	twg_overviewhtml	TWG folder	Is included below the albums on the main page
thumb.htm	twg_thumbhtml	TWG folder	Is included below the thumbnails on the thumbnail page. You should set $thumbnail_offset_y to the heigt of the conent you include. Then the autodetection of thumbs works perfect ;).
image.htm	twg_imagehtml	TWG folder	Is included below the detail image on the image page
topx.htm	twg_overviewhtml	TWG folder	Is included below the thumbnails on the topx page
thumb.htm	twg_thumbhtml	subfolders	thumb.htm can be in the main folder AND in each folder. Makes it possible to e.g. show a pdf download link depending on the folder.

Location overview:

header.htm
left.htm	top.htm	right.htm
	overview.htm, thumb.htm, image.htm, topx.htm
	bottom.htm
footer.htm

TWG folder is where the index.php and config.php is located. All files are included and therefore this are no compete pages! Only put the stuff in there you want to display!

MOST files can be language dependent: overview_de.htm, thumb_de.htm, topx_de.htm, image_de.htm, topx_de.htm

Since TWG 1.6: Please store all your text files in UTF-8! Then special characters are displayed properly!

4. Anzeigen eines Zufallsbildes oder meistgesehenen Bildes auf einer anderen Seite oder in einem anderen frame.

You can setup a random or topx image on an other web site which links to your gallery. The following two lines show the image and the link tag:

The image:
<img src="image.php?twg_album=xxx&twg_random=1&twg_type=random&twg_random_size=200">

The link with image:
<a href ='index.php?twg_random=1'>
<img src="image.php?twg_album=xxx|zzz&twg_random=1&twg_type=random&twg_random_size=200">
</a>

twg_type - you can set this value to random or top. random shows a random image, top shows the most viewed image of a folder (or the subtree if twg_random_subdir=true)
twg_album - Change the album to the album where the image should be picked! (has to be url encoded - go inside the gallery and copy it from the url there!). you can add several albums by separating them with an |
twg_random - Number has to be unique for one page (it is possible to have more than one random image on a page!) - simply start with one and count ... - read the special setting if you set twg_type=top
twg_random_size - Size of the image max x or max y value! - please keep in mind that vertical or horizontal images could be chosen and therefore your layout of the page where the image is show should be able to show this nicely.
twg_random_subdir=true - All unprotected albums below twg_album are integrated
twg_random_display=true - New 1.8 - If you add this to the link (href='...') with index.php then the link does go directly to the displayed image and not to the album. If you use image.php the original image is opened directly. This can e.g. be used to open the random image in a lightbox. image.php can only be used if twg_random_display=true!
This parameter is set at the 'Example random image' while at the 'Example TopX' it is not.

You have to add the path to the image.php and index.php to the example e.g. http://www.mygallery.com/tinywebgallery/index.php

NEW 1.6: TWG can now go recursively through your directories! Simply add &twg_random_subdir=true to the img part e.g.:

Then you don't even have to specify an album. Without album the random images starts from the root! Please note: Only unprotected galleries are included in the search.

NEW 1.7: You can show the most viewed images as well now! set twg_type=top in the url above. If you use twg_random=1 then the most viewed image of the folder is shown. twg_random=2 shows the 2nd most viewed image and so on ;). You should use &twg_random_subdir=true to get the most viewed image of a sub tree and not only of this folder. Please only specify one folder at twg_album. If you leave twg_album empty then the most viewed image of the whole site is shown!
If you would like to show the most viewed images of e.g. 2 different folders on one external site please set twg_random to the value of twg_album. Then always the most viewed image of each folder is picked.

Example random image	Example TopX - most views

5. How to setup a folder image

If you don't have any images in a folder (only other directories) or you don't want that images from this folder are displayed you can set a folder image for each folder. Simply put a png image called folder.png in the directory. Simply rename a jpg to png ;).

If you use a lot of folder images and you don't have specialy caracters please set $direct_folderpng = true; for better performance.

Important: The original size of the image is used here! This makes it possible e.g. to use really big images on the 1st page and for subdirectories smaller ones! If you have protected galleries you have to use a private.png

There are also the following 2 options:

$autocreate_folder_image = false; // (true/false) You can automatically generate a topx folder.png. Once a day the topx views is checked and the most viewed image is used. if a folder.png exists no folder_top.png is generated. If a folder has no images the default folder image is used. See autocreate_folder_image_recursive for more picking the image recursive.
$autocreate_folder_image_recursive = false; // (true/false) if true the most viewed image of the whole sutree is used - if false only the one of the actual folder. This need quite some time. If you want to speed up the gallery set this to false (but it's cached and only done once a day!). If no image is found the first one from the first sub folder is used.

6. How to set a gallery name different from the folder name (e.g. for enhanced sorting)

You can change the name that is displayed for a directory. By default the directory name is used. But sometimes it makes sense to change this:

You want to sort the directories in a way you like and add e.g. 1,2,3 at each directory to get the sorting you like but that does not look good.
You want to use a image or a different font for a folder

Create a file named foldername.txt in the folder you want a different folder name. Then put the text or html for an image into this file. The text can be any valid HTML and is inserted in a <span></span>. See the demo 1 where I have set an image for a folder!

The name can be language dependant as well! By adding the language to the filename you can provide extra translations. e.g. for German: foldername.txt -> foldername_de.txt.

Please note: Please use the html representation in the files for special characters: ä -> ä

Since 1.6 you can simply use a sorting prefix for the directory name on your hard disk as well. If you use a prefix in the following format then this is automatically removed: 001___ 002___ .... Important is that the prefix has 6 characters and the chars 4,5,6 are underscores. You don't need a foldername.txt if this is enough for you.

Since 1.7.4 you can use a file called config_sort.php. This makes it possible to sort a sub directory different then the rest. You only can place the following parameters to this file: $sort_images_ascending, $sort_by_date, $sort_by_filedate, $sort_albums, $sort_albums_ascending, $sort_album_by_date. This file works for image sorting as well. Don't use a custom folder config.php for sorting because settings in there would overwrite settings global during caching. If you use private galleries you have create a config_sort.php in the pictures folder as well. There you store the sorting of the main folder!

New 1.8.5: You can edit foldername.txt direktly in TWG. If you are logged in and you have at least the right "upload" you will get on the detail page the menu "Edit". There you can set the gallery name. Please note that you can only edit the language independent version!

Since TWG 1.6: Please store all your text files in UTF-8! Then special characters are displayed properly!

7. How to add a folder description (shown below the gallery name) or an image "header"

To create an additional text below the bold folder name you have to create a file named folder.txt in the folder the text should appear. Then put the text into this file. The text can be any valid HTML and is inserted in a <span></span>. The style class is twg_folderdescription and can be found in the style.css. The folder description can be shown on the image page as well. By turning the switch $enable_dir_description_on_image to true this description is shown there as well! For different text on the image page image.txt can be used - see howto 28.

The description can be language dependent! By adding the language to the filename you can provide extra translations. e.g. for German: folder.txt -> folder_de.txt.

If you use language dependant versions this is only shown if the language can be detected. If the language version does not exists the normal description is used - if this is not present nothing is displayed!

Please note: Please use the html representation in the description files for special characters: ä -> ä

New 1.8.5: You can edit folder.txt directly in TWG. If you are logged in and you have at least the right "upload" you will get on the main page and the detail page the menu "Edit". There you can set the gallery name. Please note that you can only edit the language independent version!

Since TWG 1.6: Please store all your text files in UTF-8! Then special characters are displayed properly!

8. How to create a language file

Since TWG 1.8: TWG is now using sprites which means that one image has all flags and not each image is loaded separately.
1. Translate one of the existing language files to your language and save it as language/language_<lang>php. Then copy the entires in language_default.php to your language file and translate them too.
2. Open language/language_text.php and add your language the same way as the other languages are defined.
3. Now you need a flag in the size 16x10 and add this with an image program at the end of language_flags.gif in the black area. Then add your new flag to language_flags.css the same way the others are defined. Simply add 16 to the position there.
4. As next step the file language_flags.css hat to be compressed to language_flags-min.css. As alternative you can copy the file language_flags.css to language_flags-min.css.
5. Delete the session cache in the administration. Since TWG 1.8.8 all css files are combined and saved compressed in the cache!
  
  If you have any problems with this please send me the translated language files. I will integrate it and send you everything back.
Before TWG 1.8:
To add a new language you have to translate one of the existing language file (e. g. language/language_de.php - the name of the needed flag is language/language_de.gif) and copy it in the 'language' directory (+ the flag). If you provide a file language/language_<lang>.txt you can specify the tooltip. Please write the language in English and then in the language of the country in Brackets e.g. Germany (Deutschland). If you need a flag - please send me an e-mail.

Please send me the language files if you want to support TWG. Please make sure to use the latest version of TWG and "Welcome to the TinyWebGallery" as title. Please make sure to translate the latest version of a language file.

Since TWG 1.6: Please store all your text files in UTF-8! Then special characters are displayed properly!
Use $charset = "UTF-8"; for the language file!

Please note:
Please use the html representation in the language files for special characters: ä -> ä I use a nice macro "HTML Encoder" for Textpad. Just google for it if you want to save yourself some time ;). Since TWG 1.6 this is not really needed anymore because UTF-8 is used almost everywhere.

9. How to change colors of TWG

All main style settings are located in the style.css. This file is well documented. Every area has its own part in the style sheet. If you change or insert a color and nothing is changing be sure that you define the settings for a link as well! To search for a certain style install the web developer toolbar extension for Firefox!

The color manager in the TWG Admin should help you to configure the colors of TWG. You can

Convert hex in decimal colors and the other way around
Select a color from the color map and click on the preview on the right side to see how it looks
Create a style sheet from your setup and save it al my_style.css

You can select transparent as color for the background of your areas. I have provided a couple of example background images that become visible if you click on transparent and then on one of the background areas of the preview. You have to provide your own background images! Read how-to 22 and 25 for some help.
After creating the style sheet you have to copy the content and save if like described before!

If you create the style sheet with the color manager you get some additional styles for the hovering effect if you use a background color - Please read how-to 27 for details about this!

I recommend not to make any changes in the style.css. Save this settings in the my_style.css.
This makes it easier for you to keep track of your changes and if you update TWG. All changes in my_style do override the settings in style.css. Remove this file if you don't use it because otherwise its transferred to the server! The settings of my_style.css are valid for all galleries.
To change the background and the color of the iframes (login, comments ...) go to i_frame/iframe.css.
Please note - you can only have one style of the iframes. If you use different styles for different folders please select colors that fit to all of them!

Please read how-to 22 if you only want to change the background of a gallery. The borders of the gallery are in the framestyle.css!

Summary - This is the order the styles are loaded:

style.css (main folder) in the main folder is the default style sheet.
framestyle.css (main folder) is the style sheet where the right/left/bottom frame colors are defined.
my_style.css (main folder) is the style sheet where you can put your changes to style.css
If you select a skin (see howto 25) then this style sheet is loaded now.
style.css (album folders) is the style sheet which can be different for each folder. You can define a different style for each folder! If you use different backgrounds you should also create a config.php in this folder where you define the backgrounds of this folder - see howto 25.

If a album folder is read protected from the web you have to use at least TWG 1.8.8 and enable optimized css because this generates only one css which is stored in the cache folder.

10. How to check which php version is available on your server and if TWG likes it

There is a file called info.php in the main directory of TWG. If you call this file instead of index.php TWG is checking some requirements and is printing the php info. If TWG is not running properly or not all features are available it is always nice to take a look there. Then check the FAQ - there are some memory issues already covered.

In the TWG Admin is an enhanced info! It tells you even more about which permissions are needed for which file/folder.

11. How to link directly into a password protected gallery

It is possible to link into a gallery or to a image. Simple copy the link in the URL! But this does not work with password protected galleries! To link directly into protected folders you have to copy the URL from the gallery you want to link to. You have to login to get this URL! After that you have to add the parameter &twg_private_login=<gallery password> to the URL. Please note: the password is not encrypted. This feature will be added by the administration which is coming soon (I hope ;)). If you use encrypted password (see how-to 1.7) you have to add the encrypted password!!
The parameter $enable_external_privategal_login has to be set to true to enable this kind of login. The default is false!

12. How to protect a gallery (and how-to set multiple passwords for one gallery and why ;))

To protect a gallery with a password you have to create a empty file with the name 'private.txt' (or whatever you have set you password file in the config) in the directory you want to protect. If the file is empty the password from the config ($privatepassword) is used. If you want to protect a gallery with a different password you have to enter the password in the 'private.txt' file.

Please read howto 1 how to secure direct access to your data!

This is the description from the config.php. I want to make some more comments at this point because some people asked:

The name of the password file can be changed in the config.php - check the config.php ($password_file) or ask your gallery administrator if he has changed it (maybe because of security issues - see how-to 1
Passwords can be encrypted - see how-to 1 for details!
Important: private.txt files do work recusive since 1.7.4 - this means a private.txt file does protect all sub folders.

You can now use several passwords for each directory. Simply create a normal password file and separate the different passwords with a ','. e.g. test,test2,test3. Make sure that there are no spaces between the commas and the passwords. If $encrypt_passwords=true you have to use the generated password!

By using multiple passwords you can give some friends access to some directories and e.g. your family access to other directories. The advantage is now that these two groups can now have access to the same galleries as well! Or you can protect all galleries with a kind of "super password" and a couple of directories with a 2nd password for access of only an area.

Please note: If you use passoword protected directories please don't use the popup on the detail page because the link in the popup is not protected. Use the fullscreen mode or the lighbox if you images have to be 100% protected.

Folder image for protected galleries

You can also set your individual image for a password protected gallery. Create a file named private.png and place it in the protected folder. The size should be the size you have set in the config.php (default is 120 x 120). Since 1.6 an image is autogenerated if $autogenerate_private_png = true; (=default). private.png files always overwrite a autogenerated one!
Important: If you use another size than the one in the config.php the original size is used - This is because you can use individual folder images which have the same behavior.

New 1.7: You can use a private.txt in the 'pictures' folder! Then a global login window is shown. You have to place all passwords (users for user based galleries) that have to have access in this file.
New 1.7.5: private.txt does now work recursive and protects all subfolders as well.
New 1.8.5: You can now use a private.png in the pictures folder. If you have defined a private.txt in this folder you can use a big image which covers the whole browser. You can create a nice entry page for your protected gallery this way.

New 1.7.6: User based galleries

Since 1.7.6 it is possible that you can switch to a different protection mode. To unlock a protected gallery you can to use your TWG login/password then. In the private.txt you enter the login(s) comma seperated which should have access to this album.
The following two parameters are available:

$user_login_mode - If set to true you enable the user based protected galleries. If you login you then unlock the galleries where your login is specified. Every user that should get access need an account.
$user_login_mode_hide_gal - If set to true proteced galleries are completely hidden if you are not logged in.

So why are there 2 modes? It depends what you need and what you prefer.
These are the pros and cons of the user based protected galleries:

+ Your users have only one login to access all their galleries
+ Protected galleries can be completely hidden because the login is done through the normal login
+ You don't have to send e-mails with passwords to your users (But you still have to inform them somehow)
+ You can disallow access for a single users by removing the login. Removing a password in the other mode would affect other users as well.
- You have to add all users that should have access to the private.txt. In password mode you only have one password in the file.
- In my opinion the user based protected galleries have more administration overhead.
- You need an account for each user.

So pick the mode you like more ...

13. How to configure watermarks and text on an image

Basic:

To configure the watermarks please go to the administration of TWG and select "Configure TWG". Go to the tab "watermark". If you make any changes there you have to refresh the image cache ("Clean Cache" -> Clean image cache). Please clean the browser cache then. Otherwise the old images from the browser cache are used and you don't see any changes.

Advanced:

The description at the watermark section is a little bit short in the config.php file. Therefore I will give some additional explanations:

Read the watermark section in the config.php! There are all settings available. The important ones are already in the administration (in my_config.php too if you don't use the backend)
Text on images and watermarks can be set independent of each other - you can use none, one or both.
Make sure that you have set $enable_direct_download=false if you want some watermarks on the originals!
If you use a random image: The watermark is only printed if the size is < 200 px and the watermark fits on the image!
The text is always on the left bottom corner - the watermark image can have 9 positions!
Your watermark image should have a solid outline and the background color should surround this for best results. See the buttons/watermark.png I use for the demo.

You can use individual watermarks for each folder! You can do this by creating the following files:

watermark.txt - The watermark text
watermark.png - The watermark image for the image view
watermark_big.png - The watermark image for the originals

PLEASE NOTE: There is a flag called $resize_only_if_too_big - If you have images smaller than the small_pic_size and this flag to true no small images are created and the originals are used instead! As a consequence no watermarks are printed on these images. You have either to add the watermark by yourself or set this flag to false. But then you images are enlarged to the small picture size.

IMPORTANT: If you make any changes to the watermarks you have to delete the images from the cache directory because the watermarks are already added to the thumbs and small images!

Since TWG 1.6: Please store all your text files in UTF-8! Then special characters are displayed properly!

14. How to track errors if TWG does not work on your system.

Check if you done all the installation steps (rights and so on...).
Check the FAQ below!
Check the debug file - The location is defined in the config.php and is counter/_mydebug.out by default. Many problems are reported there.
Delete the content of the cache, xml and counter directory
Call the file info.php in the TWG main directory or in the administration - on the top are some internal twg tests. Maybe this helps already :). Below is the php_info call where your php info are show. Interesting are the installed modules like gd (with freetype), and memory limits (see 1st faq). If you get errors in the _mydebug.out: most of the time the php configuration/version makes the problem!
Check the forum
If you have problems with the flash! Read the FAQ for the flash in the TWG Flash Uploader section - There almost all problems are covered!
Contact me. Via forum is preferred because if I answer your problem, there is maybe someone else get help there too. But still feel free to contact me directly!

15. How to change or extend the smilies

TWG shows smilies in comments and captions if the flag $enable_smily_support is set in config.php (=default).
I have only provided a couple of smilies. But you can add your own set or extend the existing set by yourself. Maybe you want to change their size if you changed some fonts ...

The smilies are in the directory <installdir>/buttons/smilies.
All smilies which are copied in this directory are available in TWG. TWG reads the whole directory and matches the filenames with the characters you normally would enter for a smilie - e.g. ;) -> ;).gif. There are some characters that are not allowed on he file system which are heavily used. I have mapped the following:

: -> a
\ -> b
/ -> c
* -> d

e.g. :) is the file a).gif !

If you have a nice set of smilies and want to share them with others please sent them to me. Thanks.

16. Linking to a web site instead of downloading a file

If you have some pictures e.g. from a remote site and want to link to this site if someone wants to download the image you can create a file named link.txt in this directory (Check the Beauties folder of the demo!). The file has to contain the starting <a> tag with the id='adefaultslide' . e.g.

<a href="<your url>" id='adefaultslide'>

The link is valid for all images of this directory! - please don't forget the id - javascript will fail if this is missing!

17. How to use a directory based config.php

You can use a config.php in every folder! This makes is possible to have different configurations in every folder. I do this for all the demo folders. You can even use language dependant configurations like config_de.php. You only have to define the delta in this file. First the config.php in the main folder is read. Afterwards the config.php in the folder does overwrite this settings.

18. How to enable e-mail notification

By default e-mail notification is turned off and sending of emails is disabled. In the config file are two main parameters you have to change: $show_email_notification and $enable_email_sending!

To configure your e-mail set the $show_email_notification and $enable_email_sending to true. If you go to the overview page you can now register and un register on the right upper menu.
E-mail can be sent from the TWG Admin!

Now set the config.php to the following settings:
$encrypt_emails = false ; // for testing!
$youremail="<your e-mail>"; - This is the from e-mail address of the registration!
$default_subject, $default_text and $email_bottomtext are the defaults for the "send emails" screen. You can change them how you like.

Register yourself on the web site and check if you get the registration e-mail - Then login and send a notification message!
go to the counter/subscriber.xml - your e-mail address should be in there. Delete this file and set the following switches in the config.php:
$encrypt_emails=true;
$encrypt_emails_key="A random string- the longer the better - NO special characters here";

Make sure that the counter folder and the subscriber.xml cannot be read from the web (chmod 700 or 770 if possible). You find more information about the parameters on the installation page or in the config.php. If your php does require that 777 is used please use a .htaccess file to protect your folder. The minimum protection is to enable encryption for the stored emails!

You can be notified if someone enters a comment or vote for an image. Enter the e-mail where the notification should be sent to and enable the comment or rating notification. One mail is send for each entered comment or vote!

19. How to enable download of a whole directory

You can provide a .zip file that the user can download instead of viewing/downloading a single image. Create a .zip file with the images you want your users to download. Store it in the directory where the images are located. The file name are the directory names with .zip as extension. e.g. Mexico -> Mexico.zip. Please use folder names without special characters. Some web servers don't allow direct links to this kind of files.
Important: If you are in a subdirectory like pictures/Mexico/Palenque the name of the zip/txt file is not the last directory only. They have to be connected with an _. In the example here this would be Mexico_Palenque.zip!

You have to activate the download in the config.php (default is enabled). If no archive can be found the normal settings for viewing/downloading of an image is used.

If you don't have that much space on your web space (like on funpic where the file limit is only 1 MB) you can create a file <foldername>.txt and put the url to your zip file in there. In the example this would be Mexico.zip. You don't need the Mexico.zip anymore!

20. How to link to pictures in a remote http directory

This a really nice feature. You can link to images which are located on a remote web server. You have to have two things:

The images are located on a remote http server where the directory can be listed
fsocksopen() has to be enabled on your php installation (www.funpic.de does not - therefore I cannot show this in the demo). Please check the info.php or in the administration if this available on your server (this check has been added in TWG 1.8.8)

The directory structure of the images has to be on the local web server. Inside the directory have to specify a file called url.txt where the url of the remote images are stored. Make sure that the url starts with http:// and ends with an /. Inside the local directory you can use all the other settings like described in how-to 17. Even private works but is not really save because the images on the remote directory have to be available (but if no one knows :) ...). This does not work recursive! If you have different directory levels on the remote server you have to create a url.txt for each directory. If you have a space in the path to the images please replace this with an %20. The best way is to navigate with the browser to the directory and copy the url. If you have black images then please check your image names - special characters do not work on all web server (on most they do not!).

e.g. http://<your domain>/<your directories>/

A running example can be found here:

http://mdempfle.md.funpic.de/pictures/2006_06_boas/

simply put it in an url.txt - You can try the url first in the browser. You should get a nice listing there.

The thumbnails and the small web images are still stored in the cache to provide a performance which is only slow at the first access and in full screen mode! Special characters are not supported to be displayed properly as captions because I don't know the encoding on the remote server.

You can now link different images galleries together into a single one :).

If you want to add custom configuration files like config.php or style.css: They have to be in the local directory where the url.txt is. Remote configuration files are not supported.

If a listing is not possible

You can provide a page by yourself (e.g. an index.htm in a folder) that has only full links (e.g. <a href="http://www.123.com/images/image1.jpg">image1.jpg</a>) to your images. It is important that you use the html link syntax because the server does deliver the directory listing in the same way. TWG does detect full links and fetches the images from there. This makes it possible to link to any image you like and put them together in one directory!

NEW 1.7.7 - You can use relative links! This means you can link to directories that are not below the pictures directory. Enter the relative path in the url.txt. The path has to be relative to the main directory of TWG + you have to add one ../ in the front! Only images, external videos like yotube and flv are supported. WMP and DIVX are not supported!
Example: if TWG is installed in the directory /twg and your image folder is at /images/myalbum then you have to add ../../images/myalbum/ in url.txt.

21. How to add a "home" link to the gallery and how to create independant sub galleries

NEW 1.7.0.6 - I have rewritten the implementation of root.txt to make it easier to handle! The howto is only valid from this version and above.

A root.txt can be used for 2 things:

Adding a "Home" link to a gallery - If you like to make a link back to e.g your homepage. This adds a new link on the left upper corner on the main page. Please add $lang_back_link to your language file. I only have added this to German and English. For all other languages a "home" icon is shown! Please add e.g. $lang_back_link = "Home |"; to your language file if you like! The root.txt has to contain a link like http:// ....
The root.txt can be in 3 places:
- main folder of TWG: The "Home | " link is added too ALL breadcrumbs!
- pictures folder of TWG: The "Home | " link is only added to the album overview page
- sub directory: The "Home | " link is added to the directory where the root.txt is + to all sub directories. This file can be empty too - please read the next part because here the file does a little bit more!
Create sub galleries that look like independant galleries - a root.txt defines your new root if you use this file in a sub directory. No path to upper directories are shown then. This file works now recursive. You don't have to define this in sub directories of you new root. If you lease the root.txt empty it simly looks like the root. If you add an URL in this file starting with http:// then the "Home" link is shown too!

New 1.7.6 - Multi root mode. If you only want to have independant galleries this is maybe the easier solution for you. See howto 52 for details.

22. How to use a different background image for each folder

You can use an individual background image for each sub folder. Simply place a png called back.png in the folder where the background should be different. That's it.

If you want to save some disk space and make your gallery a little bit faster - use a jpg as background an rename it to png!
You can turn off background images in the config.php with $show_background_images. There is also a switch called $low_show_background_images that is used in low bandwidth mode. By default background images are not shown in low bandwidth mode.

Please note: TWG does dynamic resizing of your background images unless you disable this in the config - see $use_dynamic_background and $use_resized_background!

23. How to upgrade from older versions from TWG

Deutsche Version -> Deutsche FAQ

You should use the file my_config.php for your configuration or use the administration - For details see here! Save your changes you want to make in config.php to this file. They overwrite all variables from the config.php. I you want to upgrade to a new version or just want to install TWG somewhere else you have all your changes in one nice small file! config.php is overwritten by the patch because new parameters are defined here!

If you want to use the installer for updating please read how-to 31

UPDATE TWG 1.6 or newer:

Since TWG 1.6 the structure has not changed. On the download page is a patch file available where you can simply overwrite all existing files! Your settings and your data are not overwritten.

For a transfer (or a backup) of your setup and data move my_config.php, my_style.css, admin/.config/.htusers.php, the counter, xml and your pictures folder to the new installation. Make sure that the files in the xml and counter folder are writeable!

UPDATE TWG before 1.6:

I recommend that you make a clean installation if you want to update a version before 1.6!

Backup my_config.php, my_style.css, the counter, xml and your pictures folder to the new installation. admin/.config/.htusers.php can be copied too but you should check your users afterward because TWG 1.6 has some new user rights that are set to default for old users.
Install the latest version of TWG.
Copy the saved files my_config.php, my_style.css, counter and pictures back to their old place. admin/.config/.htusers.php goes to admin/_config/.htusers.php. Open the files my_config.php and .htusers.php with a textedit and save them as UTF-8 files! (save as .. and then most editors give the option to store as utf-8. Or use the TWGXplorer - it stores files in utf-8 too.)
The xml files have still the same format but special characters like äöü from xml's of version 1.5 are not encoded properly anymore. You have 3 choices:
1. If you don't have many comments and/or captions recommend not to use these files and let TWG generate new ones!
2. Only special characters are not displayed properly - If you don't have e.g. German chars like öäü. No problem
3. If you want to keep the comments/captions you can change TWG back to the mode used in TWG 1.5! Open the language files your are using in the language folder and remove the $charset="utf-8"; at the top of each language file + change the encoding in the language files of admin/_lang to $GLOBALS["charset"] = "iso-8859-1";
  Then TWG works like it did in 1.5 - If you do this - please do not edit any files like folder.txt in the TWGXplorer because they are stored in UTF-8 (or use e.g. ü instead of ü).
if you choose 2 or 3 you can copy the xml files back in the xml folder.
TWG is now using UTF-8 everywhere. (if you have not changed it in 4-3)
Please store all your text files (like folder.txt, foldername.txt) in UTF-8! Then special characters are displayed properly!
Make sure to set the permissions of the files of the counter and xml folders that php can write them again - on most servers 777 is needed!

UTF-8 should be the preferred encoding because TWG is now available in over 20 languages and this is the only way to have a consistent system that works all over the world!

24. How to show more images in the DHTML thumbnail strip

If you scroll in the DHTML thumbnail strip you can set the numbers displayed at a time with $numberofpics.

You can also configure when the the green arrows at the end of the thumbnail strip appear. The problem here is that all pictures have to be loaded until the strip is moving. To decrease the waiting time I have set a limit of the number of images which are displayed with the following two parameters:

$cmotion_gallery_limit_ie=40;
$cmotion_gallery_limit_firefox=20;

This is the max number of images that are shown in one cmotion gallery. At the end there will be a small arrow to go to the next x images :).

But why are the numbers different? All browsers except IE don't allow to exchange images in this strip on the fly. Therefore an optimization for IE exists: $enable_optimize_cmotion_gallery_limit_ie. If you set this to true only 5 images are loaded each side and all the remaining ones are white first. Because IE does allow me to exchange these images I can do some nice background exchanging of this images - The big advantage: The gallery is moving if the 1st set of images is loaded.

Sometimes some images don't show up in the optimized version. Most of the time this is because the thumbnail had to be generated and was not available in time when IE requested it. If all thumbnails are created this is no problem anymore. (You can use the search to create all thumbnails quickly -> search -> file name -> . -> All). So if you want to reduce the green arrows: increase this values but not that a lot of data is loaded. There are low_ values for this two settings as well!

25. How to use and make a skin!

Using a skin is easy. Look in the skins folder which .css files do exist and use the name of the css (without the .css) in the config.php at $skin like $skin="winter";. If you download one from the website extract it into the skins folder and enter the skin name like before in the config.php - be sure not to create a subdirectory. The skin files have to be in the skins folder.

Please read how-to 9 about colors in TWG!

Making a skin is actually easy too ;). The skin can have 3 components:

a style sheet called <skin name>.css - This is like the my_style.css in the main folder - you can enter all styles TWG known in there! You can use the color manager to create one.
a php file called <skin name>.php - Here are the config.php settings for this skin. Normally you place here if you use dynamic background and the colors of the background of the slide show. You can also disable e.g. the optimized slide show because it does no look that good if you have a background image. Check the elements of he skin section - it makes sense to adopt them for a skin
a background image called <skin name>.jpg - This image has to be entered as the background image in the <skin name>.php. I recommend to use a resolution not larger then 1024x768 and set he dynamic background to true - otherwise the loading time for the background is maybe too long for some users. Like with the back.png the background image is not shown if a slow connection is detected - Therefore always define a background color too.

That's it. If you want to share your skin please check the "Skins" section on the website. You should provide a screen shot and a zip file with the 3 files in it there.

Please don't use special characters or spaces for the skin names. Most web server don't work well with style sheets that contain those characters.

Since TWG 1.6: Please store all your text files in UTF-8! Then special characters are displayed properly!

26. How to include different file formats like avi, mpg ...

You can now include other file formats like mpg, avi, mp3... into TWG like you can see in the demos. TWG does not include the files directly but can provide a download for this files.
If you want e.g. include an avi you have to do the following steps:

Provide a jpg file that should be used as preview image for your avi file.
Rename the two files that way that they have the same file name but with the extension jpg and avi. e.g. mymovie.jpg and mymovie.avi - don't use special characters here because TWG provides a direct download to this file and not all web servers work properly with special characters.
Check the config.php if your extension is already supported: There is an array $other_file_formats where the file extension and an image is defined.
The image that is defined is rendered a watermark on your preview image! You can add file formats or change the watermark in the buttons folder! You can select the position and the transparency of the watermark.
Copy the two files to your web server ;).

If you change a watermark image or any setting for it you have to delete the cache! If you want to use embedded video or mp3 - please read howto 34

27. How to configure the hover effects for ie properly

Internet Explorer 6 (IE 7 is fine) has a problem with the style for a transparent border. Therefore you have to provide a background color if you like a hover effect around the thumbs on the details page. By default the border color for Firefox is transparent and for Internet Explorer it is set to none! If you use a background image I recommend not o use the hover effect but otherwise you should set the following 4 styles!

td.navicon a img{
}

td.html_side_default a img{
}

td.html_side_left a img {
}

td.html_side_right a img{
}

to e.g.

td.navicon a img{
border: 1px solid #0000ff;
}

The color manager provide this settings in the css if you don't use transparent for the main body!

28. How to use the image.txt

Please note:
image.txt is intended to add additional and maybe complex data to each image. It should NOT be used to create a caption below the image. TWG has the caption functionality for this. To add a simple caption below the image login in the right upper corner and on the image page you get the additional menu item 'Caption'. There you can easily enter a caption for each image. You can also add the captions right to your images and extreact them in TWG. Please read howto 38 about IPTC data for details.

The image.txt can be used to provide additional data in the detail page. Since 1.6 are 3 different "modes" possible. Before 1.6 only mode 1 and 2 are possible! Everything below works with the language dependent versions of the files as well - using e.g. image_de.txt, image_en.txt.

Simple text include: The image.txt can be included in 3 positions: $image_txt_position does define it - Possible values are: "top","bottom" and "side". top and bottom are obvious. "side" does include an image.txt and an image2.txt. The image.txt is included on the left side - image2.txt is included on the right side! Be careful about the code you want to show. image.txt and image2.txt should "need" the same amount of space to keep the image centered! Furthermore I recommend to use a div with a fixed width because IE does sometimes bad rendering and moves the image to the left! The "exif" example on the Ajax demo shows this simple include with position = top.
Include as php file: You can change the $image_file_extension in the config to php. Than you can include everything you like in this file - tables or even php code! You can get the image name by using the variable $image! This makes it possible e.g. to include a different file for each image or create a dynamic link to a shopping cart! The "USA 2005" folder from the Ajax demo shows how this is used. Only the english part uses this ways - the german description uses method 3. I only mixed this in the example - normally you only use method 2 or 3 ;).

IMPORTANT: If you use image.php like in the examples folder you have to protect this file by the following line:
defined( '_VALID_TWG' ) or die( 'Direct Access to this location is not allowed.' );

You can use the following variables:
- $image - image name e.g. image.jpg - this value is already urlencoded! If you need it to load e.g. a .txt file you have to use urldecode($image)
- $twg_album - the album names e.g. folder1/subfolder2
- $basedir - the base image folder normally 'pictures'
- $default_language - the current language e.g. de
Since 1.6 it is possible to use the image.txt like a properties file. This means you can have one line of text for each image in this file.
e.g.
image1.jpg=This is the description for image 1
image2.jpg=This is the description for image 2

To enable this mode you have to set $image_file_is_multi = true;
The German (!) example "USA 2005" folder from the Ajax demo shows how this is used (config_de.php + image_de.php + image2_de.php - the php extension is only used because I mix mode 2 and 3 in the example - normally you can use txt files here!).

PLEASE NOTE: If you only want to display a caption simply use the build in caption feature - login at the right upper corner - then you get a menu item call "Caption" and then you can enter a caption for each image! image.txt is intended to display additionally data like I did in the example!

Which mode to choose: If you only want to display a static text for all images - use mode 1. If you need the image name dynamically but the rest is static - use mode 2. If you want to display a different additional text for each picture (not only captions) use mode 3.

Since TWG 1.6: Please store all your text files in UTF-8! Then special characters are displayed properly!

29. How to configure the HTML_SIDE big navigation

If you want to display the thumbs on the image page right and left to the main image you can use the new HTML_SIDE navigation.

Just set $default_big_navigation="HTML_SIDE";

There are 4 more parameter where you can configure the display of this style: $numberofpics_html_side, $disable_nav_big_sel, $html_side_break, $html_side_space_optimization and
$html_side_show_dividor. Please read the documentation behind this settings to configure HTML_SIDE.

If you have $numberofpics_html_side-1 images in a directory a special mode is enabled. e.g. if this is set to 9 4 images are shown on each side! to make this style look good the 8 thumbs are static! The actual thumb that is displayed is only marked by a thin border! (style:html_side_mark)

30. How to use the TWGXplorer and what is the safe mode any why is this a problem ;)

One of the main things of the backend is the TWGXplorer. You can upload, rename, delete, manage the files create users and gives them some rights .....
If the files have the permissions that you can access them with the user php is running you can do many of this things. If not you have to change the file permissions with an ftp program. Most of the time you need 777 for a file or directory you want the edit. This is because php is most of the time not running as your ftp user but a different user (apache, www-run ...)!
Please read the 2nd part about safe mode too - Quite interesting if you are not 100% clear about permissions and restrictions ...

I think this is not problem to understand ;). But there are 2 things I want to mention when using TWGXplorer: user management and restrictions because of the save mode!

User management: You can create users and give them certain rights! If you want someone to be able to upload you should give him at least modify rights! Important is the main directory of the user. You should only use . for administrators because this makes it possible even to modify TWG itself! Normally it is enough to use the pictures directory or a subdirectory of it for the user.
Safe-Mode: "When safe_mode is on, PHP checks to see if the owner of the current script matches the owner of the file to be operated on by a file function or its directory.".
This is the very short description from the php manual but I want to explain this in a little bit more detail ;):
If a php script is executed it is either done by the owner of the script (the ftp user) or the php user like "www-run" or "apache". If the script is executed by the owner the safe-mode is no problem - but most web hosters don't even know how to configure their system this way. Therefore php is normally run by a user like "www-run" or "apache". And if this is the case you have the "www-run" problem. This means that if you want to edit your files or upload files to a directory with the TWGXplorer the permissions have to be set to 777 because the owner of the file is not the same as the one who runs the script! And that means that everyone (who can run a script on this server) can access this files.

And now the safe-mode restrictions apply! Lets assume you upload TWG to a directory on your web server. Then you change the permissions that the TWGXplorer can create a directory below the pictures folder (pictures folder has to be set to 777). This is possible because the main directory belongs to the owner of the script. But if you now try to create a file in this directory this would lead to an error because the directory belongs to the owner "www-run" or "apache" while the script does belong to your ftp user!
TWG tries to detect many of this situations and this is why you cannot create or upload everywhere. But what is the solution?
- If you don't have the "www-run" problem - everything is fine - you can check the user by moving the mouse over the ? next to the owner in the header line - if the user is the same for the ftp and files created by twg admin you are fine - don't care about the safe-mode. Most likely your php is running with phpsuexec (check the last entry of the TWG Admin on the info page - it tries to detect if php is running this way)
- If safe-mode is off and you have the "www-run" problem you can set the permissions to 777 and work with your files almost without restrictions. But you should protect your files with a .htaccess file (there is an example in the configs_demo) if you want to have private albums.
- If safe-mode is on and you have the "www-run" problem you can:
  1. Ask your ISP if he turns off safe-mode (mine did!)
  2. Ask your ISP if he can configure php that way that the www-run problem does not happen - I googled a little bit an this can be done by running php not as module but by including it with cgi (running phpsuexec! - more and more provider do this!)
  3. Some ISP have the possibility in the web interface that you can change the owner of your files to the php owner - but be care full - If you do this you maybe cannot manage your files with your FTP program anymore.
  4. Ask your ISP if he changes the owner for you! (FTP problem like described at 3 can happen!)

If non of this solutions work I do recommend not to upload or edit files with the TWGXplorer and to use a FTP program. TWG does not detect all restrictions of the safe-mode and therefore it is sometimes possible to delete a file or folder even if the actions on the right do not allow this. You can select the checkbox on the left and use one of the commands on the top and try if it works.

Please read this if you want to use the installer version of TWG AND safe mode is on:
The installer version of TWG can be installed only in a subdirectory that is created by TWG. You have full rights with the TWGXplorer. But the safe mode does not allow you to access pictures you have uploaded with your FTP program! Therefore you have to decide what you want! Upload with the TWGXplorer or FTP. If you want to upload your files with an FTP and have safe mode on please use the normal version of TWG (or simply extract the twg_install.zip and upload everything with your FTP program)

If you have read this and have still no idea what i'm talking about please let me know - I want to make this quite hard topic as understandable as possible.

31. How to update TWG with the installer

If you want to update TWG to the latest version you have to have TWG 1.4.x installed already. It is not possible to use the installer if you use an older version. I also recommend not to update any 1.4.x or 1.5.x version to 1.6 with the installer because I have changed some directory structures and your install would get messy! + you have to copy admin/.config/.htusers.php manually to admin/_conifg/.htusers.php.

Then you have to have all your changes to TWG either in the my_config.php, the my_style.css or of course inside the pictures folder! If you have made modification e.g. in the config.php - move them to the my_config.php and do the same with style.css and my_style.css.

And Safe Mode should be off. If it is on the installer will tell and warn you! If you have done the installation with the installer before - go on. If not TWG will not update but install TWG into the sub folder twg. I think you don't like that! Please use the normal zip version then.

Updating itself is very easy

Upload the 3 files from the download that start with 'install'
Check if the twg folder has 777 as permissions - if not please change that!
Start install.php - - READ if anything is red!
Click update an you are done - the installer will keep your pictures folder and the my_config.php and my_style.css. It make a backup if the config.php too. You can delete this after the update! I only make this of security issues because I think there will be some people around who forget to store everything in my_config.php ;).
Save files like folder.txt, foldername.txt .. in utf-8 if you have special characters like öäü!

I have tested the installer on many systems and I never had any data loss (either it worked of it was not working at all because of php security settings!) but I always recommend to make a backup! On some servers the unzip does not overwrite existing files! If your update does not work: use the zip version and make a manual update.

Have fun updating TWG!

32. How to add big folder descriptions like in the AJAX demo - registered version only

You can add folder descriptions to the left and right of the folder images/collage. You can use two files where you can put your html - albuml.txt (for left) and albumr.txt (for right). The files are included in a <td class="albumtxtleft"> ... </td> or <td class="albumtxtright"> ... </td> tag. You can use a div inside to get a nice layout. You can use language dependant files too like albumr_de.txt.

e.g. <div style="width:250px;text-align:right;padding-right:20px;"> your text </div>

If you want to link from your text to the album like before you have to manually add the link to your text (copy it from the link from the images).
You have to set $menu_x to 1 or 2. If you use album.txt files the normal folder description is not displayed anymore!

Since 1.8.2:

You can use 3 variables which are replaced in the file:

{album_name} - The album name (from directory or foldername.txt)
{album_href} - The href string you can use like <a href="{album_href}">xxx</a>
{album_count} - The number of files in the directory when the counter is enabled.

Since TWG 1.6: Please store all your text files in UTF-8! Then special characters are displayed properly!

33. How to use the lightbox feature (new 1.4.2)- registered version only

TWG has integrated the lighbox script and lytebox script (since 1.7.4) for registered users. This feature can be activated at 3 points:

On the thumbnail page
- $activate_lightbox_thumb=true; - activates this feature on the thumbnail page.
- $activate_lightbox_thumb_full=false; - if true the whole thumbnail activates the lighbox script. It's then not possible to get on the image page anymore. If false, there is a small zoom icon in the left upper corner of each thumbnail. If you click on this the lighbox image is shown.
- $use_original_on_thumbspage=false; - Normally the detail image is used on the thumb page for the lightbox - but you can use the original too if you like! Just set the parameter to true! Settings this to true makes everything a little bit slower but the images displayed optimized to the browser resolution
On the TopX page
- $activate_lightbox_topx=true; - activates this feature on the TopX page.
- $activate_lightbox_topx_full=false; - if true the whole thumbnail activates the lighbox script. It's then not possible to get on the detail page anymore. If false, there is a small zoom icon in the left upper corner of each thumbnail. If you click on this the lighbox image is shown.
- $use_original_on_topxpage=false; - like $use_original_on_thumbspage only for the topX page
On the image page
- $activate_lightbox_image=true; - if true clicking on the detail images does not open the image in a new window or a popup but in the lightbox. Download has to be activated to use this feature + you cannot download the lighbox image with "right click -> save image".
  
  On the image page you cannot go to the next image in the lightbox. But actually there is a better way to do this. If you go to "Option -> Maximized view" you can enable the fullscreen mode of TWG. You can automatically use this instead of the lightbox with the following settings:
  $activate_lightbox_image=false;
  $open_as_popup=false;
  $open_in_maximized_view=true;

You can set this parameters in the my_config.php (copy them from config.php) or add them in the additional tab of the TWG Admin configuration. Please do not modify my_config.php if you want to manage TWG with the TWG Admin because otherwise you settings get overwritten! If you want to change the colors of the lightbox script please change the lighbox/css/lightbox.css.

Thanks to Lokesh Dhakar for the Lighbox script + the users from the blog that added some nice features to it (+ me who added some more features ;)).
Since 1.7.4 the lytebox script is the default lightbox because it supports if you have TWG in an iframe.

To use the lytebox in an iframe you have to include the lightbox/lytebox.css into the head section of your main page with e.g.

Please note that the litebox only works for the parent and the gallery is on the same domain because of the same origin policy.

Have fun using the lytebox.

34. How to use embedded video support

There are 2 different basic approaches how this is done. In TWG 2.5 all the old flash solutions where removed. So currently this can be done:

Embed HTML5 videos (mp4)
Embed a streamed video with an iframe that comes from a remote site like youtube.com

To enable embedded video you have to create a file called video.php in the folder where the videos are or should be shown! If the file video.php is empty then the default settings in the config file is used. You can put the settings for this folder in the video.php file too (<?php [your settings] ?>). In the sections below you can see examples settings for each type.

Thumbnails:

You have to have a preview image for each video in the folder! They are needed for the autodetection mode as well!
The name of the thumbnail file is different depending which type your are using (See below). But most of the time it has the same name like the video and instead the extension of the video the needed extension is jpg. You can prodvide this the following ways:

Manually: Create a preview image of the video and put it in the folder with the video.
Generate with ffmpeg: See howto 47.
Generate with a dummy: See howto 41.

Without thumbnail your video will not be shown!

Watermarks on the preview images of videos: By default a watermark is rendered on the thumbnails of videos. They are defined in the variable $other_file_formats. So if you want to change the watermark you can change it there. You can disable this feature by setting $overlays_for_other_file_formats= false; Make sure to clean the image cache after you change this setting.

Autodetection - Please read this part first!

You have 2 options:

Not using a video.php at all! You have to set $video_autodetect = true; (=default). Then $video_php_x_default and $video_php_y_default are used as width and height!
Using a video.php where $video_player="AUTO";
<?php
$video_size_x=320;
$video_size_y=310;
$video_player="AUTO";
$video_autostart=true; // or false - depending what you want
$video_show_dl_link=false; // true or false works
$show_slideshow = false;
$default_big_navigation="HTML"; // should be set if you have images and videos in one folder!
?>

Solution 1 and 2 are treated almost identical internally. Solution 2 is a little bit more flexible because you can do some extra settings like disabling the slideshow.

Using the auto detection makes it possible to mix videos AND images in one folder if the videos are local. Read Howto 39 if you don't have local videos!
You have to use solution 2 and set $default_big_navigation="HTML"; in the video.php!

Since 1.7 it is also possible to generate a video.php and a preview image during the upload of a video! Even automatic conversion to mp4 is possible. Check $use_ffmpeg and $autogenerate_video_php_at_upload and the settings below. This makes it possible that users can upload a video and everything needed is generated automatically. This feature is only available if you have ffmpeg available (check info.php). Please read howto 47 if you want to use this feature!

The best video inclusion can still be achieved by using specialized video.php's like described below because there you can control everything and it's possible to use the DHTML (=Ajax) mode.

Please store all your text files in UTF-8! Then special characters are displayed properly!

1. Embed HTML5 videos (mp4)

HTML5 videos are the way to go right now. TWG uses the video.js HTML5 player which does play mp4 videos directly.

In the demo you see all possible setups of HTML5 videos:

HTML5 videos on the local server
HTML5 videos on a remote server
HTML5 videos and images in one folder with video.php and with auto detection.

Advantage:
   - Works on almost all devices
   - Responsive videos are available. Videos do scale to your device size!
   - You get a streamed video - this means that the video has not downloaded completely before the playback starts.
   - The video is converted by the uploaded site in the needed format
   - The video are locally stored or even on a different server!
   - You can provide a download link if you like
   - You can use autostart or not!.

Local videos

The easiest way is to use the auto detection and store the videos on your server. Set everything in your my_config.php. E.G.

<?php
$video_size_x=425;
$video_size_y=350;
$video_player="AUTO";
$video_autostart=true; // or false - depending what you want
$video_show_dl_link=true;
$video_autostart_parameter="&autoplay=1";
?>

Upload your videos with a thumbnail and you are done. Use it together with then new responsive features of TWG and your videos should be displayed the best way on all devices.
TWG does also support the automatic conversion of videos and the auto generation of thumbnails. Please see howto 47 for details.
If you don't want to use auto detection or you have several different video types you can use $video_player="HTML5"; and a video.php:

<?php
$video_size_x=425;
$video_size_y=350;
$video_player="AUTO";
$video_autostart=true; // or false - depending what you want
$video_show_dl_link=true;
$video_autostart_parameter="&autoplay=1";
?>
Remote HTML5 videos

You can also store the videos on a remote site. This setup is a little bit more complicated because you still need a dummy mp4 file on the local server. So you need a thumbnail and a empty video file. Than you need to set

$video_flash_site = "https://...";

to the directory where the real videos are. In the demo example this is $video_flash_site = "https://www.mdempfle.de/html5/";
HTML5 videos and images
If you want to mix videos and images you can enable the mixed mode like described in howto 39. Simply set $mixed_video_image_content=true; in the video.php. And if you use $video_player="AUTO"; which is default right now you only have to enable the HTML navigation with $default_big_navigation='HTML';

Please check the HTML 5 videos in the demo. They can be found in the multimedia album and in the resopnsive album .

2. Embed a streamed video like youtube

If you want to use this solution the video is not stored on your web space but on one of the video sites below. You have to create an account there and then upload your file. Then you can directly view your video on this site. Depending on the site the video is then available for all other users of the site too. Some of this sites provide private access as well (see below for details). TWG does then embed the video directly from this site and provides the flash player that does support streaming. TWG can mark your thumbnails with an watermark - to make this work for this solution simply create a file with the same name as the thumbnail and with the extension of your video (e.g. .avi see howto 26 how this works).

Advantage:
   - You don't need your own web space
   - You get a streamed video - this means that the video has not downloaded completely before the playback starts.
   - The video is converted by the uploaded site in the needed format.
Disadvantage:
   - On most of this providers your video is visible to all.
   - You have to upload the video to this providers first.
   - You cannot provide a download link - the setting $video_show_dl_link has to be set to false.

www.youtube.com
If you upload your video (or just want to embed one of the existing) you have an url like
http://www.youtube.com/watch?v=qMSrpZi_6WM&search=josh%20blue
The interesting part is the value of the v. To include this video into TWG you have to use the value of v for the thumbnail e.g. qMSrpZi_6WM.jpg. You have to make your video public that TWG can access the video.
The video.php should look like this:

<?php
$video_size_x=470;
$video_size_y=406;
$video_player="IFRAME";
$video_autostart=true;
$video_flash_site="https://www.youtube.com/embed/";
$video_autostart_parameter="";
?>

Please note that you can append all possible youtube parameters in the parameter video_autostart_parameter. You can find a full list here: https://developers.google.com/youtube/player_parameters
Youtube does support autoplay! If you open the TWG page with the video directly autoplay is not supported by many browsers anymore. It will only autoplay if you clicked on that page before.

SORTING: I have included a solution to sort this videos. Because the names are given by the web sites you can use a prefix for the thumbnails. The prefix has 3 numbers + 3 underscored (___) .e.g. 001___<imagename>.jpg

What should I use?

Now you have many ways to provide multimedia content - which one should you use? I think you can use all ways and still be happy. The new HTML5 player is the one you should use if you also want to support smartphones and tablets where no extra plugin is available. It also depends which video source you have. Then if streaming is important for you - if you have bigger videos I would only choose a streaming solution!

You can actually include most of the video sites available. Simply check the url's they use and then use the dynamic part of the url as file name of the preview jpg.

And now have fun using TWG and videos!

35. How to choose the right storage location for your xml files

Since 1.5 the xml files (where the comments, captions and counters are stored) can be saved into the album where they belong to. Before 1.5 all xml files where only stored in the xml folder. By default the xml folder is still used because you should read this howto before to make this work ;).

1. Storage in the xml folder
By default the xml files are stored in the xml folder. The advantage is that only the xml folder has to be writable and all xml files can be found at one place. The big disadvantage is that if you move or rename a folder the xml file names have to be changed manually to keep the data.
Since TWG 1.7.7 you can create a text file called folder.id with a unique id in your image folder. Then the unique id is used as prefix in the xml folder and not the album name. If you do this you can then move or rename your albums without any problems. Just be aware that this files has to be created when you create the directory. There is no migration if you create it later!
Since TWG 1.7.8 you can TWG let create the folder.id automatically - set $autocreate_folder_id = true; Currently this is not set as default. In one of the next versions I will change this. Make sure that the folders below the pictures folders are writable.

2. Storage in the album folders
If you store the xml files in each album the albums have to be writable! This can be a problem because many folder have to have the right permissions (not only one like in the xml folder). The big advantage is that you can rename and move albums and still keep the data. And it's much easier to find the right xml file if you want to change one manually

The info in the TWG Admin does always show you if all directories are writable and if not lists the directories that have to make writable. If you change from the xml storage to the album storage the xml files from the xml folder are automatically transferred in the album folder. But there is not transfer back!!!
IMPORTANT: It's a step by step process - it's transferred when an xml is modified! Therefore it's moved when you change a caption of an comment of a folder (then all xml's for a folder are moved! (1.6 it's different!))

And now the important switch: $store_xml_in_picfolders

NEW 1.6: In 1.6 I have reworked this part because migration could take very long this way. I have now added this functionality to the pre caching of the xml's. This mean you have to do the following steps to migrate:

Make a backup of the xml folder
Set $store_xml_in_picfolders=true AND turn off the session cache! (the icon "No cache" is shown then).
Simply close the browser and open it again - after 5 sec the pre caching in the background is started and moves the counter, captions and comment files.
Only 50 dirs are done in one row (because pre caching is limited to 50 dirs at once). If you have more directories - simply redo this step.
Log into TWG Admin - Extract IPTC Data - Then the xml's for the tags are moved.
Done ;).

36. How to uninstall TWG if you cannot simply delete it

Because of safe mode restrictions if is possible to set the permissions of directories that way that you cannot change it back and this can lead to the problem you cannot delete your TWG installation anymore. This can happen quite easily if you use the TWGXplorer or the installer and some directories or files are deletable by php but not by you ftp program. Therefore I implemented a small uninstaller.

To uninstall TWG ONLY if you cannot simply delete it with FTP do the following:

Extract the file uninstall.php from the file uninstall.zip in the uninstall directory and copy it to the main directory of TWG. If you have used the installer and safe mode was active twg was installed in the directory twg - if this is the case please copy the uninstall.php to the directory where the folder twg is in (=the directory one above where the config.php is).
Call uninstall.php - the uninstaller create a file called uninstall.sm.php (The file uninstall.sm.php is now owned by the php user and can delete files and folders even when safe mode is on!)
Call uninstall.sm.php (Deletes everything where the safe mode restrictions apply)
Call uninstall.php (Delete the remaining files if still some left ;)).
The directory should now be empty except any directories you have created by yourself!

37. How to use the new backend rights

You can now give the users different rights. Please note that the rights always depend on the home directory of the user. The default should be the pictures directory! It's not possible to have more than one main pictures folder (of course as many sub folders ;)). Therefore you always should start at least with "pictures" as main directory for all users that should not access the TWG installation itself!

There are now 5 rights available:

Login = Login only. Can be used to password protect galleries - see user login mode.
Frontend Edit = Login at the front end to enter captions, tags, delete comments and rotate images permanently.
Frontend Upload = Login at the front end to upload files below the home directory with the Flash Uploader.
Backend Modify = Upload and modify files with the TWGXplorer in the TWG Admin below the home directory.
Administrator = Full access to all areas of TWG Admin

The big difference to 1.5 is that there is not a simple password in the front end where you could enter captions ... anymore. Now it's possible to create a user and give them specified rights to specific directories. A special feature is that if a user has "Frontend Upload" rights. Then he gets a new menu item "Upload" when he is in a directory where he has the rights to upload. Then this user can access the TWG Upload Flash with the rights you gave him ;). In the frontend no html upload is possible.

This new user management makes it possible that you can have one gallery that is filled with content from different people where everyone can only access his area.

38. How to use IPTC data in TWG

TWG does now read of IPTC data from the images. This is meta information that you can easily add to your images. Good programs to add/edit IPTC data are:

PixVue (free) - It's an explorer extension - it's actually not longer supported but you will find it somewhere for sure ;)
MS Photo Info (free) - It's an explorer extension too - The good thing is that you can edit several images at once.
XNView (free) - You can add/edit the metadata - but you have to open each image first and then select metadata in the menu.
Almost every image software (Photoshop, Paint Phop Pro ...) - but they are not free ;).

. TWG uses this information at several places:

Tags
Caption
Info screen

To avoid reading this info every time a picture is displayed (which would be quite slow) this reading is done when:

You enter tags - for image tags the keywords are used (see $iptc_fields_for_imagetags) and for the directory tags the sub-categories (see $iptc_fields_for_dirtags) - This data is automatically entered when you open the enter tags panel.
You start the IPTC extraction in the TWG Admin - The tags and captions (see $iptc_fields_for_caption) for ALL images that don't have any info in the xml file are extracted and stored in the xml files. This means that the generation only works for images that are new. If you use dir tags please note that only the directory tag from the first file of a directory that has a dir tag is extracted. All other existing dir tags are ignored. Therefore you should actually add dir tags only to one image in your external tool!
You upload images with the TWG Flash Uploader (see $add_iptc_at_upload)
You show the info panel - There are all defined and available IPTC data is shown. The data that is read can be defined in the language file $lang_iptc_info - This makes it possible that you define your own metadata and display what you want ;). You can read more than one field in the $lang_iptc_info. Simply define another field - see e.g. Author

The IPTC data fields are tested with Photoshop and XnView. But if you have a different tool where my offsets (the one I have chosen are the most common ones e.g. 2#120 for Description) do not work you can simply change the offsets in the config ;).

Almost all images in the Ajax demo contain IPTC data! If you download the examples and go to the TWG Admin and extract the IPTC data you get a lot of tags and captions already ;).

Exif for caption

You can use Exif information for caption too. This is quite uncommon but e.g. the software "Exifer" and Photoshop Album 2.0 (someone told me) stores e.g. an image description in the exif data. By default reading this info is disabled because it is really slow (about 10 times slower than reading IPTC data). To enable reading data and use this as caption you have to set $exif_field_for_caption to the exif key in the config. "imageDesc" is the key where the image description is saved often.
To find out which keys are in your images you can make a dump of the exif data. Open inc/exif.inc.php, search for "print_r", remove the // at the beginning of this line and store the file again. Then go to the gallery and open the info of an image. Then check the counter/_mydebug.out. There you find a list of all exif keys. Simply use the one you want to extract and don't forget to restore the exif.inc.php.

New 1.7: you can extract a 2nd exif field for the caption - check the parameter $iptc_fields_for_caption_add

39. How to mix images and videos in one folder

Since 1.6 you can have one type of video and images in one folder! This only works in the HTML and HTML_SIDE mode - If you set this to true then DHTML mode is switched to HTML mode! Therefore I recommend to set this to true this ONLY in the video.php!

Add $mixed_video_image_content=true; to your video.php file to enable the mixed mode!

If you set this to true you have too add v___ (3x _) at the front of the filename of the video (this is prefix is use by TWG to detect that this is a video). This prefix is removed when a caption is displayed! e.g. 123345.jpg -> v___123345.jpg. a sorting prefix goes BEFORE this 123345.jpg -> 123___v___123345.jpg.

There are 2 example folders in the Multimedia album of the Ajax Demo.

New 1.7: You can use the auto detection of videos instead using the description above if you have local videos. Please go to howto 34 and read the section about auto detection!

New 2.2: You don't need a sorting prefix only to sort videos back into their normal order of the images. v___ is ignored for sorting now!

40. How to include PNG's (and gif's)

This a quite easy howto:

gif: is supported by default since 1.6 - simply copy your images to the folder like any jpg image.
PLEASE NOTE: If you use gifs you should use image magick! GD-Lib (=default) has a very bad quality when it resizes gifs!
png: Only check that your images does not have the name of one of the internal used files - see howto 0.

41. How to generate preview images for extra file types! - registered version only

Before TWG 1.6 you have to provide a preview image for every extra file type like wmv, pdf, flv. Since 1.6 you can generate default preview images in the TWG Admin.

All images that get a default preview image that are defined in the array $other_file_formats_previews.

Right now the following file types are defined: avi, mpg,mpeg,pdf,mp3,divx,wmv,wma,flv,mov.
They all have the preview: buttons/border.jpg.

Because these types are all defined in $other_file_formats they will get a watermark! You can change the watermark in the array or define no watermark

New 1.7: for video files it's possible to use ffmpeg to generate thumbnails out of the video - see how-to 47.

42. How to check and enable file splitting (new 1.6)

I have tested the TWG Upload Flash and the TFU File Split Applet on several systems and not all servers do support this kind of upload (e.g. funpic.de does not - my TWG server does). The test is quite simple - you have to upload a file bigger than your file upload limit and TWG has to be able to process it. I have written a small howto with the steps you have to do:

Find your server limits - Open info.php or the Info page in the TWG Admin - it tells you the php upload limit and the php memory limit.
You can do the ftp or/and the image test.
If you want to do the image test please create an image with a image software that is bigger then your php upload limit
Using png's with 16 Million colors are quite big ;). Normally these programs tell you what the uncompressed size of this image is.

For the ftp test you simply need any file that is bigger than your upload limit!
Split this file with the File Split Applet (use the size closest to your upload limit). Use part as split prefix
Enable support of splitted files in the TWG Admin - set "Enable support for splitted files" and "File split was tested on the server" to true in the TWG Admin
Make sure if you do the ftp test that the file you have selected is in the $allowed_file_extensions list of tfu_config.php
Upload all parts of the splitted file.
The file should now be merged and be visible as one file on the left side.
FTP test: Open your ftp and download this file. Check if this file is o.k. - At this point some server already have restrictions! They don't allow to process any files bigger than the upload limit. If the download works and the file is o.k. then normally you can use the Flash splitting capability!
Image test: Select the file (that is an image) and a preview of this image should appear or the flash tells you that the flash cannot be processed (it detects that the memory is too little but if this can be detected the file can be read - php needs~ 2x the uncompressed size of the image to process it ) - if not php is can not load this files - means images bigger than the upload limit cannot be processed - if you check the tfu.log (only exists if an error happens and the tfu main dir is writable) in the tfu directory of the server you should see an error message that the file is not valid (because php could only load a par of it) - if this is the case you cannot use the Flash splitting capability!

43. How caching works in TWG

TWG does a lot of caching to speed up the gallery. These are the different levels of caching:

Image caching - All generated images are cached in the cache folder. Therefore they only have to be generated once (generation is very slow!). If you change anything in the config that has to do with images (image size, watermarks ...) this cache has to be deleted - You can do this in the TWG Admin. This cache is always active!
1 day caching (new 1.6) - Some things are generated once a day. This is the album tree and the counter how many images are in one folder. Because this are functions that affect all folders/images they are very slow at big galleries. This speeds up the 1st call of the gallery a lot! This settings are stored in files in the cache folder and rebuild once a day. cache_dirs has to be true to enable this caching! This cache is rebuild once every day - the first user who goes to the gallery after midnight starts this process (And has to e.g. wait 2 seconds longer)
X hours caching (new 1.7) - Since 1.7 it is possible to generate a cache for the TopX ($precache_main_top_x) and the directory structure ($serialize_dir_data). This caches are either build in the background (topx) or saved when important session data is generated. This data can be updated more often than once a day! With $precache_main_top_x_interval you can set the refresh interval. This two caches speed up the viewing of the Topx and the first call of the gallery very much. Only be aware that the TopX is only build every x hours! There is a limit when this caching is enabled: $precache_main_top_x_limit. By default this is set to 2000. Below this value TopX values are not cached.
Since 1.7.1 TWG does use timestaps in the cache files - therefore new/deleted images are detected right away. 1 day caches and X hours caches are refreshed as well.
Session caching. Every time you open your browser and go to the gallery you get a new session. This session exists as long as your browser is open (or it is timed out). In this session I store almost everything that don't has to be done twice. Like: reading directories, data of files like folder.txt, foldername.txt, xml files, languages... . Therefore sometimes you don't e.g. see new directories when you add them with your FTP program. cache_dirs has to be true to enable this caching!
You can delete this cache, the x hours cache and the 1 day cache in the TWG Admin.

Please note: When you click on the bandwidth icon the data from the 1 day caching, X hours caching and the session is deleted! If the cache is not active you can activate it by clicking on the "No Cache" for this session! Then you can see how much faster the gallery is displayed ;).

Summary:

During normal use you should always turn the cache on because otherwise the server has to do a lot of additional work. After the installation the cache is turned off (as you see in the right bottom corner) because during setup you want to see changes even in the topx right away. But once this is done: turn it on. Uploading with the Flash Uploader does automatically update these caches!

44. How to enable url rewrite and get SEO friendly urls

New TWG 2.0!

SEO friendly urls for TWG are now available! The new urls of an album do now look like this:

http://www.tinywebgallery.com/demo/twg_album/05_exif
instead of
http://www.tinywebgallery.com/demo/index.php?twg_album=05_exif

or on the image page:

http://www.tinywebgallery.com/demo/twg_image/05_exif/1.jpg
instead of
http://www.tinywebgallery.com/demo/index.php?twg_album=05_exif&twg_show=1.jpg

Quickstart guide

Use the .htaccess tempate inside htaccess_url_rewrite.zip and change the RewriteBase to your install directory
Make sure that your directory names do not contain the character ~
Enable SEO urls by setting $enable_basic_seo=true;

Detailed description

Extract the .htaccess from htaccess_url_rewrite.zip to the root of your gallery. The template in the .htaccess is:

RewriteEngine on
Options +FollowSymlinks
RewriteBase /twg2/
RewriteRule ^(.*)twg_album/(.*)$ $1index.php?twg_album=$2 [L]
RewriteRule ^(.*)twg_image/(.*)/(.*)$ $1index.php?twg_album=$2&twg_show=$3 [L]
RewriteRule ^(.*)twg_show/(.*)$ $1index.php?twg_album=&twg_show=$2 [L]

You have to change the RewriteBase depending to you installation! Make sure that the RewriteBase ends with /. If TWG is in the main directory simply use /.
If TWG is e.g. installed on www.yourserver.com/gallery/twg then you have to modify the file like this:

RewriteEngine on
Options +FollowSymlinks
RewriteBase /gallery/twg/
RewriteRule ^(.*)twg_album/(.*)$ $1index.php?twg_album=$2 [L]
RewriteRule ^(.*)twg_image/(.*)/(.*)$ $1index.php?twg_album=$2&twg_show=$3 [L]
RewriteRule ^(.*)twg_show/(.*)$ $1index.php?twg_album=&twg_show=$2 [L]

By default ~ is now used instead of / as album seperator. This was done because an / needs to be encoded and is %2F in the url which is not very nice and because of the rewrite is has to be encoded again. Encoded / also have problems with the google boots ans some apache settings (causes 404 errors) and therefore the new way should be used. If you want to switch back to the old encoding $use_old_seo_slash_encoding=false;
You can also set the album seperator character with $album_sub_url_seo_character="~"; Only make sure that the seperator char is not used for folder names. This way you are able to create quite nice urls for the albums as well.

Finally you have to enable in TWG that this kind of urls are generated by TWG. Set

"Enable SEO urls" in the Adminstration of TWG
or
$enable_basic_seo=true; in the my_config.php.

Have fun using TWG

45. How to optimize the gallery for speed

By default most of the features of TWG are enabled. As you can think this looks best but is not optimized for speed. This small howto tells you a few parameter how you can optimize TWG a little bit if you think TWG is too slow ;). But remember - TWG does a bandwidth detection. If it detects a slow connection already the low_ from the config are used. This mode does disable some features that really use much bandwidth (like the colage, fixed number of thumbnails, hides the big navigation ...).

Update to at least TWG 1.8.8. This version uses up to 42% less requests, the requests are in an optimized order and up to 55% less bytes are transfered.
- Use the provided .htaccess if you are on an Apache web server. It enables compression and caching of the server. This brings you the most improvements. Unzip the htaccess.zip in the main directory. In the zip is a readme which modules of Apache are needed.
- All css files are dynamically combined and compressed. the compress css files is stored in the cache folder for one day. You can disable this optimization during setup by setting $optimize_css = false; or you can delete this file by clearing the session cache (in the administration or by clicking on the bandwidth icon. You will find maybe more than one css file in the cache because depending on the folder or the settings different css files are used!
- The order of the requests are changed. Only the Javascript that is really needed in the beginning is loaded there and the rest at the end of the code. This enables parallel downloading of other resources.
- The changes above can be measured by a tool called page speed from google. The score of TWG increased from 49/100 to 95/100 and as rumors say this number is also taken into googles ranking algorithm. In the blog I have make a table with the measurements that compared TWG 1.8.7 with TWG 1.8.8 and the enhancement especially of the .htaccess file is huge! So please give it a try.
Turn on the cache after setup - This still gives you 100% of the features and is the most important thing you have to do - see howto 43 for details! Test again after you turn the cache on - you should see a big difference ;). This is very important for registered users because the album tree would be build over and over again!
The 1 day cache can be made permanent since 1.6.1 - if you set $remove_1_day_data=false; the 1 day cache is only removed if you delete the .tmp files in the cache, you upload an image with TFU, you click on the bandwidth icon or you add twg_reset_bandwidth=true as parameter to the url ;).
NEW 1.7 - TWG does now a lot of more caching by generating e.g topx in the background every x hours only! Check the setting $precache_background and the entries below. You can adjust them if you e.g. want shorter refresh intervals! By default this cache is enabled but only active if you have more than $precache_main_top_x_limit images (500 by default)!
NEW 1.7 - serialize_dir_data! This is the highest level of caching you can enable. If you set this to true then the directory caches that are stored in the session are saved to the cache folder and only updated every couple of hours (precache_main_top_x_interval). Normally this cache is build for every user the first time he accesses the gallery. If they already exist they only have to be loaded. And this is much faster then reading the whole directory structure! The first time access of my private gallery (~3000 images) increased from 5 seconds to less than a second! By default this cache is enabled! It is only active if cache_dirs AND serialize_dir_data is set to true!
Set $cache_time=-1; This disables the check if the images in the cache folder are not used anymore! Normally this is done once every day. Unused cache images are then not deleted anymore! (default is 42)
Generate all the thumbs in the TWG Admin - TWG does generate them when needed but it's a better 1st experience when the cache is already generated ;). If you upload your images with the TWG Flash Uploader the cache images are generated automatically since 1.6.1
Disable random folder images - every time an album is shown a new set of images are loaded - if you turn this of always the same ones are loaded and if they are loaded once the browser can use them from it's internal cache - parameter: $use_random_image_for_folder
Disable the colage of a folder - then you load only 1 image (~3k) instead of four (~12k) - you do the math ;) - parameter: $show_colage;
Use a fixed number of thumbnails - TWG does an autodetection and displays as much thumbnails on the thumbnail page as possible. You can tell TWG to use a fixed number. this is recommended if you use a fix layout anyway - parameter: $autodetect_maximum_thumbnails
Use "fade" as folder effect (=default). "change" would load a different image when you move the mouse over it. parameter: $folder_effect
If you have really many images and the 1st start of the gallery takes very long most likely this is the counting of all images for the "number of images" counter. This counting is cached but the 1st call could timeout if your server settings are to low. You should set $show_counter_in_jstree=false and $show_number_of_pic=false; then. The counter is then not shown anymore.
If you have really many images you should also set $use_cache_with_dir=true; Then images are not stored flat in the cache folder but in the same directory structure as the images. If you set this php needs to be able to create directories with read rights. This is normally not the case if save mode is active.
For each image view the *_counter.xml is written to store the view counter. Each folder has one counter file. If you set $show_count_views=false; you save the writing of this file at each request which makes the gallery a little bit faster when you have many files in a directory.

This is actually everything where I think this really makes a difference. You can of course tune much more but I don't think you will notice a difference in speed if you do this. If you are bored: simply take a look in config.php and you see what you can configure in TWG if you like ;).

46. How to use image magick (New 1.7)

Since 1.7 TWG does support image magick for:

Thumbnails
Detail images
Upload

These are the files that are actually written to the hard disk. Image magic is not used for the slideshow, random and all maximized images. This calculations are still done with gdlib.

You can check if you can use image magick by calling the info.php page. If there is not support you have to install image magick. Ask your hoster or google (if you can install software on your server!) how to do this ;).

Using image magick has the advantage that is needs less memory than gdlib and produces a better quality (but the difference is not very big as far as I can say). If your images are very big and you don't have much php memory than you should try to use image magick. You can enable image magick by setting $use_image_magic=true;

If image magick does not work error images are shown. You have to delete the image cache after changing image magick settings or if you turn the support off when it does not work.

47. How to use ffmpeg

ffmpeg is a very powerful tool to convert videos and to extract thumbnails from videos. TWG can use ffmpeg to:

extract thumbnails from videos

during upload
in the backend at "Generate preview images" (registered version only)

convert uploaded videos to flv or mp4.

First you should check if ffmpeg is available by calling the info.php page. If it is available you can use all the settings below $use_ffmpeg. Please read the documentation in the config.php in the details. There you can specify the extensions, the time where the thumbnail is extracted and a couple of other settings for ffmpeg.

If you don't have ffmpeg installed but you want to use ffmpeg you should ask your hoster or most of the time you can also install it by yourself. Under many Linux distributions you can install it though the package managemente.g. apt-get install ffmpeg. Also static builds on www.ffmpeg.org/download.html are available. You can upload them to your webspace and set this in the config at $ffmpeg_path. Under windows a native port does exist. It's only one exe file and a dll. Really easy to use ;).

You can also use avconv/libav. Than you have tu set this at $ffmpeg_path and check the command string at $ffmpeg_convert_command.

Depending on your input file the provided command in $ffmpeg_convert_command or $ffmpeg_convert_command_mp4 maybe needs different settings. To find the right/best command simply try the command on the console until you get the result you like. Google is also a good help to find the best settings for your input file.

48. How to use self registration (New 1.7)

Since 1.7 you can allow people to create a frontend account for TWG. This user get a directory and can upload the images there. Only usernames with [a-z,A-Z,0-9,- and _] are allowed because of security reasons - please note: You are responsible for the stuff your users upload!

The following settings are available to configure self registration:

$enable_selfregistration - (true/false) You can enable self registration here. In the login window then a link where you can register appears.
$enable_id_registration - (true/false) If you enter an id here than this id is needed on the registration page to register. You can e.g. send this to all users of a mailing list and thn only this people can register and not everyone!
$self_registration_security_image - (true/false) You can enable/disable that users need to enter a security image. This should be enabled to prevent robots to register automatically.
$self_registration_basedir - (String) The directory where the user folders are generated - $basedir = maindir - add e.g an upload dir with : $basedir . "/upload" - the dir upload has to exist!
$self_registration_functions - (String) The default rights of an user - can be changed in the administration: possible values:
- "15" = manage dirs + edit files (if registered) + delete + upload
- "7" = edit files (if registered) + delete + upload
- "3" = delete + upload
- "1" = upload only
  Other values would be possible but in the backend only this 4 settings are configured!

Right now only English and Geman translations are available. If you use this function please translate it and send me the translations.

49. How to use the thumbnail flash (New 1.7.3)

Since 1.7.3 there is the new thubnail flash available. To enable the flash you have to either select "Flash" in the Administration -> Configure TWG -> Functionality -> Default big navigation or set $default_big_navigation="FLASH" in my_config.php. Additonally there are the following options are available:

$flash_nav_reflection='on'; // You can turn the reflection of the thumbnailflash on/off. valid entries: 'on', 'off'
$flash_nav_reflection_bg_color='FFFFFF'; // This is the background color of the reflection. Set this to your background color if you turn reflection on
$flash_hide_scrollbar='false'; // You can hide the scrollbar by setting this parameter to 'true'. Valid settings are 'true','false'. You should enable autoscrolling if you hide the scrollbar!
$flash_enable_autoscroll='false'; //You can enable autoscrolling when you move the mouse to the left and to the right. Valid settings are 'true','false'.
$flash_border_color=''; // You can add a 1 px border around the images in the flash. You have to specify the color in the format FFFFFF. Empty means no boarder! The boarder does not look 100% because it's rendered be the flash and this looses some quality.

You can copy them to the free text field in the administation or in my_config.php

Have fun ;).

50. How to make round corners (New 1.7.5)

Since 1.7.5 TWG gives you the possibility to have round corners around the image area. This is completely done by Javascript. You don't have to create any extra images for this!

An example how this looks like is shown in the admin skin. To enable this you have the following settings in the config (copy changes to my_config.php (or the freetext field in the administration) as always):

$use_round_corners = true; // You can enable round borders for the gallery. Check the settings below AND the css settings that are needed!
$use_round_corners_size = 12; // The radius of the corners. 1-32 are fine. If you use corners > 32 the calculation take quite long and does not look good anymore...
$use_round_corners_border = 1; // The size of the border. 1 or 2 are good values.

Known restrictions:

IE: If you use php include this feature is not supported right now because IE does not render the corners properly. You would have to make the corners with background imags then! I hopefully find a solution in the next build.
IE: If you set $iframe_include to true again IE does not do it right. I'll show the version without round corners then. See howto 2 for details about this.
Opera: does not render the collage properly when round corners are enabled. Therefore the round corners are disabled there too and the normal version is used.
Firefox: The ajax thumbnail strip is not very smooth - This does NOT affect the thumbnail flash.
Firefox: The rating image always highlights 5 stars if you hovering of the image.

Supported skins: The skins admin, black and white do support round corners. You only have to enable this by setting $use_round_corners = true; in the php file of the skin in the skins folder! I recommend to use the flash thumbnailstrip with round corners. Then everything looks quite nice.

I'm looking if I do find a better solution without the restrictions. But if you don't use php include the fallbacks do look like before and if it is supported it looks better.

Now you have to set the styles for the corners. Simply create a file called <skin>_round.css and put in the settings below and adopt the colors as described:

/* Please set the color for the background of the inner area */
#content_div, #content_div .sb-inner {
height:100%;
background-color:#f1f1f1;
}

/* Set the color of the border */
#content_div .sb-border {
background-color:#ccc;
}

/* Disables the old border AND set the color to the color of the border of TWG (the background of the header part. ) */
td.twg_info { border: none; background-color: #fff; }

You find working examples in the skin folder. You should always make a skin if you want to use it because e.g. for Opera I disable this feature.

Now you should have nice round borders around TWG ;).

Have fun ;).

51. How to add captions to an image

If finally wrote this small howto because too many users asked me how to add captions to an image. There are the following ways:

Name your images. By default the image name is used as caption. Only be aware that TWG only shows the image name is a certain number of numbers are not reached. This is done because only the camera name does normally not make sense. You can set the limit of numbers by setting the parameter: $autodetect_filenames_as_captions_number. There are a couple of more options in config.php. Search for $show_captions in config.php and read the sub setting too. Make sure to store this changes in the administration or directly in my_config.php (as explained on the configuration page).
Login in the right upper corner. On the image detail page you get the new menu item 'Caption' where you can simply enter the captions. Even smilies are supported. Your captions are then stored as xml in the xml folder.
Enter the caption as IPTC data offline to your images and let TWG extract them. Read howto 38 for details. Once the data is extracted you can still modify it like described in 2. This is a very flexible way because if you move from one gallery to another some galleries can extract this data too.
Use image.txt to add additional data for the image. This is no real caption but you are more flexible to place your output. image.txt data is not shown during a slideshow. Therefore for captions you should use 1. or 2. An example how image.txt can be used is shown here.

52. How to use the multi root mode

This mode can be used if you like independant galleries in one TWG install where each subtree should look like it's own gallery. Before you could do this by creating a root.txt in each folder. But this had some restrictions which don't exist now anymore:

In this mode you can not go to the main page and find out which other galleries do exist. An album parameter is always required.
You don't have to create root.txt files.
The album tree does now work and show the subtree only.
You can protect access by a session variable which e.g. can be set by Joomla (see the example below).

You can enable the mode by setting
$multi_root_mode=true;

You the have to link directly to the album with: <path to the TWG install>/index.php?twg_album=<your foldername>

Without a folder you get an error message that you are not allowed to see the root.
If you want to secure this directory then you have to do the same like described below in the JFU + TWG scenario.

JFU + TWG

An interesting combination is to use JFU with the module of TWG. In JFU you can create profiles for your users (or use a master profile with the login name as sub directory name) and point the directory to the pictures directory of TWG.

The module of TWG (it's in the joomla-mambo directory) does set the current login of Joomla to the session variable 's_user' and you can enable in the module that the login is automatically added as twg_album parameter. Then the user directory is shown in the module. Finally you have to set the parameter
$multi_root_mode_login='';
to
$multi_root_mode_login='s_user';

in the configuration of TWG. By doing this setup every user get's his own little gallery nicely included in Joomla.
If you leave $multi_root_mode_login=''; no session check is made. Then you can access an album by knowing the url. If you want to give the user the posibility to share their images without login this is usefull.

If you don't use the multi root mode you can still use the TWG module to make a direct link to the users directory.

About including a module in the content area: If you don't have a module position where you can include TWG you can include it by following this tutorial of loadposition. For 1.0.x users: google for mosmodul.

New 1.8:

It is now possible to automatically log in a user to his folder. You can enable that a user can edit or upload. The parameters you have to use for this is

$multi_root_mode=true;
$multi_root_mode_login='<session variable with the folder e.g. s_user>'
$multi_root_mode_permissions='<'', 'edit', or upload. >';

$multi_root_mode_permissions is an extension of the JFU+TWG setup which you can also do without Joomla. Simply set the folder name to the session in . If you set $multi_root_mode_permissions = ''; then the handling like above in the JFU+TWG setup. If you set it to 'edit' or 'upload' then the user gets automatically logged in with edit or upload rights. If someone accesses the gallery without the right session variable then he can only view the gallery. Be aware that this is the difference to the JFU+TWG setup. If you set the $multi_root_mode_login there you need the session variable to access the gallery while with multi_root_mode_permissions set you can access the album without login.

53. Howto configure your server to run TWG properly

Iit's quite important how you configure your server to get TWG working properly. On the configuration page the first thing I tell you is the call info.php. And this is the howto how to change this settings.

So first call info.php and check the settings you see there. These are the settings you have set on your server in your php.ini.

The php.ini is your php configuration file of your server. It's not part of TWG/TFU/JFU and you have to make changes there to increase the limits. There are several locations where the php.ini files is/can be.

Private hosting: In the config directory of your web server. For apache this is e.g. in the apache\bin folder. The locations below should work too.
Shared hosting: If you are on shared hosting you normally cannot change the php.ini directly. But most hosters allow to have a custom php.ini in the root directory or even in a sub directory. Therefore you should try to place your php.ini in the root folder and/or the tfu folder (JFU: administrator/components/com_joomla_flash_uploader/tfu/).
If this does not work you have to ask your hoster!

The usage is really simple. You overwrite the settings from the default php.ini with the settings you set in your custom php.ini

These are the most interesting settings:

TWG:

memory_limit: This is the most important setting for TWG. If images are not shown or TWG does seem to load for ever you should check and increase this value if needed. info.php shows you your current settings + the maximum image size that can be processed. The debug file (counter/_mydebug.out) should give you additional details if you have not enough memory to resize images.
session.save_path: Sometimes this variable is not set properly or the directory not writeable. If this is the case you are logged out right after a login. Set this variable to a writeable directory. Sometimes you find a message in the log file if the session.save_path is not writable or not set if this is the case. The current setting is shown in the php info which can be seen if you call info.php -> Click on "Show php info" -> Search for " session.save_path"

Upload in TWG/TFU/JFU:

post_max_size, upload_max_filesize... Please go to howto 4 of the TFU howtos for details

A simple example for a custom php.ini for TFU would look like this.

memory_limit=64M
upload_max_filesize = 20M
post_max_size = 20M
max_input_time=1800
max_execution_time=1800
default_socket_timeout=1800

This defines a 20 MB upload limit, php memory of 64MB and timeouts of 30 min. There are most of the time maximum limits by your hoster you cannot exceed. Therefore you have to ask your hoster if you cannot increase the limits to the value you need..

For a complete list of settings that you may configure in the php.ini file, please refer to the PHP manual page found at http://www.php.net/manual/en/ini.list.php. Please be informed that the php.ini file does not require all of these settings; only enter the line that you wish to change from the default value.

When changing the maximum file upload size, please ensure you have changed both the upload_max_filesize and post_max_size configuration together. The two settings should share the same value.

If you have an ISS as webserver please read this post: http://www.tinywebgallery.com/forum/viewtopic.php?t=2295

54. How to set a background image

There are a couple of ways how to define background images in TWG. TWG does also support dynamic background images which means that the background images gets resized dynamically to the browser dimensions.

IMPORTANT

SINCE 1.8.8:

For optimal display for round corners the css styles #twg_info and #twg_content_div have now background colors. You have to overwrite them if you define a background image by setting

#twg_info { background-color:transparent }
#twg_content_div { background-color:transparent }

in my_style.css or use the 'transparent' skin! Then the image is visible in the conent area.
This styles are needed for all options below if not specified differently.

These are the different options you have:

Fixed global image:

Define the background image in the style sheet. e.g. in my_style.css ->
body { background-image: url('<your image>') }
If you only want the image in the content use:
#twg_content_div { background-image: url('<your image>') }
then you don't even have to overwrite the styles explained above. If you use round corners this is the best way!
OR: Specify the image by setting $background_default_image='<your image>'; . To have a static background you have to set then $use_dynamic_background=false;
Enter this setting in the the extra tab in the TWG administration.

Dynamic global image:

Specify the image by setting $background_default_image='<your image>'; . To have a dynamic background you have to set then $use_dynamic_background=true; (=default)
Enter this setting in the the extra tab in the TWG administration. There are additional options available ($use_resized_background, $resized_background_tolerance, $resize_only_if_too_small). Take a look at the description in config.php for more details.
CSS3 offers the new attribute background-size. You can now define the background like above in css. You have to add
background-size:cover;
background-repeat:no-repeat;
where you define the images as well. the 3 interesting settings are:
- percentage: Sets the height and width of the background image in percent of the parent element. The first value sets the width, the second value sets the height. If only one value is given, the second is set to "auto"
- cover: Scale the background image to be as large as possible so that the background area is completely covered by the background image. Some parts of the background image may not be in view within the background positioning area
- contain: Scale the image to the largest size such that both its width and its height can fit inside the content area.

Individual folder image:
- See howto 22 if you want to use this.

If you use the color manager you can select different example images. Make sure to use the 'color' transparent for the areas you want to see the background images. Wenn Sie das für den inneren Bereich machen brauchen die oben beschriebenen Styles nicht überschieben werden. Dies erledigt der Farbenmanger bereits. The background image cannot be defined directly in the color manager and has to be set like described above.

55. How to create/modify the buttons of TWG

Since TWG 1.8 the main buttons are not single images anymore but are all one one images which saves a lot of requests and speeds up TWG again.

To create your own icon set you can use one of the existing ones in the buttons/iconset folders as template and e.g. just color it the way you like. You can also exchange the images if you like to stick to the same size. If you want to fully create your own iconset please do the following:

Create your icons in the size and color you like
Go to http://css-sprit.es/ and create your buttons.png file and get the sprite image and the css.
Save the image as button.png in your icon set folder.
Copy one of the existing style.css files from a different icon set and modify the part between /* twg buttons */ and /* Fullscreen images! */. You will get the coordinates from the css from css-sprit.es. The names in the style sheet are hopefully selfexplaining enough ;)...

Test the icon set and send it back to me if you like. I will add it to the download section. If you like you can even write a small script that will create everything automatically. I just don't have the time to do this right now by myself ;).

56. How to optimize TWG for search engines (SEO)

TWG has a lot of internal links which point to the same pages but with different urls because of different parameters. This leads to a lot of duplicate pages which are bad for googel ranking. Since TWG 2.0 the gallery is optimized as good as it is possible right now. So since 2.0 the following things are done:

SEO optimized urls. See howto 44
Unique meta titles and descriptions are generated.
Unique title for each page
Support of canonical URLs. Only twg_album and twg_image are the parameters that identifies a detail page of TWG. On all pages that have additional parameters a canonical url is added in the header so that google does not treat them as duplicate content anymore. See: http://www.google.com/support/webmasters/bin/answer.py?answer=139066
noindex, nofollow are now at all rotation links and the topx links.

So please update to TWG 2.0 to optimze your gallery. Furthmore you should register your site at the google webmaster tools: https://www.google.com/webmasters/tools. There you can check at Diagnose -> HTML suggestions about potential issues Google found when crawling and indexing your site. Simply look before updating TWG and after (it takes a few weeks/months until google has updated the index).

Additional go to Website Configuration -> Url-Parameter and tell Google that all parameters except twg_album and twg_show should be used for crawling. For all other parameters starting with twg_ please set that this parameter should not be used. There are some paraleters start with amp and have a twg_ also. Please disallow theses as well.

Wait a few weeks and you will see the results ;).

57. How to make TWG responsive (new 2.2) - registered version only

Since TWG 2.2 it is possible to make TWG responsive. This means that depending on the screen size the images do float or the image/video does scale. You can enable/disable this setting for the following pages: main page, thumbnail page and the detail page. Before TWG 2.2 the thumbnail page and the TopX where already optimizing the number of images depending on the screensize if the screensize was measured in the request before.

See a working example in the Ajax demo and click on the TWG responsive folder.

The settings are disabled by default because it also means that if you update to this version your gallery would look a little bit different than before. So you can now decide if you want to go responsive. The following settings are available:

Global:
- $responsive_align_center - Define if the images on the main and thumbnail page are centered or left aligned in responsive mode.
Overview page:
- $responsive_main_page - Enables a responsive main page. The table structure does than float. The $menu_x and $menu_y settings do than only define the number of albums shown on each page.
- $responsive_main_page_padding_x = 40; - The x padding of each album. Choose a value where all your descriptions do fit and the distance of your alumbs have the distance you like
- $responsive_main_page_padding_y = 50; - The y padding of each album. Choose a value where all your descriptions do fit and the distance of your alumbs have the distance you like. The given values are good for 2 lines of album names.
Thumbnail page:
- $responsive_thumb_page - Enables a responsive thumbnail page. The table structure does than float. The x and y settings do than only define the number of thumbnails on each page. When autodetection is enabled TWG still tries to find the optomal number of thumbnails which are all displayed on one page without scrolling.
Detail page:
- $responsive_detail_page - Enables a responsive detail page. If you enable this images and html5 videos do scale. Elements like the thumnail strip and the folder description are hidden if they do not fit anymore. Be aware that for mobile devices the fullsceen mode for the detail page is default.
- $responsive_detail_page_full_slideshow - If set to true the maximized slideshow is used which scales to the size of the browser.

Please note that TWG has a bandwidth detection ($test_client_connection and the $low_* settings in config_internal.php) and a mobile mode ($enable_mobile_detection and the $twg_mobile_* settings in config_internal.php) that can e.g. change the default number of albums on the overview of which navigation elements are shown.

Have fun using TWG,

Michael

FAQ (English only!)

I'm using TWG 1.5 and my cmotion thumb strip is not moving anymore!

Before 1.5 the cmotion gallery was always moving if you had dhtml mode enabled - since 1.5 this is not the case anymore! this can have one of the following reasons:

$autodetect_noscoll=true; - If you have less then $numberofpics images you don't need to scroll at all - if you set this to true the thumbs below are static no mater which one you select (the actual thumb in not below the image anymore!)
$use_nonscrolling_dhtml=true; - This is a mode where the strip does not move by moving the mouse but by clicking on the thumbs - This looks like the html solution but is much nicer because no reload is done and lots of precaching can be done either

TWG Admin does not work and all iframes are white

If all iframes are white and the TWG Admin does not work then most likely a basedir restriction of your php installation is the problem. If you can speak german you can check the following thread in the forum: http://tinywebgallery.com/forum/viewtopic.php?t=399.

To make find out if this is the case add

ini_set("display_errors",1);
error_reporting(E_ALL);

to your index.php if no errors are shown in the debug file.

If you find something like that:

Warning: main(): open_basedir restriction in effect. File(./../config.php) is not within the allowed path(s): (/serv/www/data:.:/tmp/) in /home/gf1491/public_html/twg/admin/index.php on line 61

Warning: main(./../config.php): failed to open stream: Not owner in /home/gf1491/public_html/twg/admin/index.php on line 61

Then you have the basedir restriction. This means that you are not allowed to access a file from an upper directory. Please ask your admins to loosen this restriction because otherwise TWG won't work.

The images/directories are not shown at all or only some are shown

If you have set the right file permissions there can be a problem with your php memory limit. If you have original images with ~ 1MB the needed intern memory is ~10MB (Open a jpg e.g. in Paint Shop Pro or Photoshop and check the memory usage of your image). Call the file info.php in the TWG main directory. It shows you the php-settings of your system. If your memory limit is lower than the limit you need for your pictures you have to increase this limit or make your images smaller.

OR - If all images are missing: Have you enabled the "text on image" feature. If yes maybe the FreeType lib isn't installed on your system (call info.php section gd). Set $print_text to false and retry - If the images are shown please use the $print_watermark switch. I will try to detect if the print_text does not work in one of the next releases.

OR - TWG is caching everything from the file system in the session - close your browser and try again! Since 1.7.1 this cache checks itself if it needs changes!

Some of the images are completely black on the thumbnail view

You have maybe opened the gallery during uploading the images. Just delete the cache folder and retry. Or the images cannot be read by the php library. I know some cameras that create jpg's that are not readable by the gdlib! If you can you should update your php installation > 5.1.3 - From there on corrupt images can be read much better - TWG sets all the flags that are needed to process these images!

Deleting the cache

Deleting the cache does not mean to delete all the files which are in there. It means to delete all the images that are in there! There are also .rot files where the rotation of images are stored :). If you want to remove stupid rotations - delete all files in this folder except the index.htm! Use the administration to delete the different levels of the caching!

You wrote that you removed all the cookies - but when I go to the gallery a cookie is set!

That's right - TWG does not use any cookies to store information by itself but php does to track your session. If you don't allow this cookie you can't login or change any settings. But you can refuse this cookie and still use everything of TWG. TWG is designed to run without cookies if the php installation is setting a parameter in the php.ini. If the administrator of the gallery is able to set the flag 'session.use_trans_sid = 1' the urls get a sessionid. Then you can refuse the cookie and still use the whole functionality. If not you should allow your browser to accept this one cookie.

I want to sort my images by the date the picture is taken (using exif data) - what do I have to set on my server?

TWG tries so sort your images after the time the picture is taken. Therefore it need to read exif information from the image. This function is only available in PHP 4 compiled using --enable- exif (call the info.php of TWG and check your php settings). Its functionality and behavior has changed in PHP 4.2. Earlier versions are very unstable. There are a couple of libraries in the www that can read the information without --enable- exif but I have tried some and didn't get better results reading the time the picture was taken (my own camera does not have exif data I can use :(). If no proper data can be read the file time is used. If --enable-exif is not set the file time is used as well.

How can I reset/change the image view counter/caption/comments?

Maybe you want to reset/change the image view counter. The counter files are stored in the xml directory and have the format <twg_album>_image_counter.xml. Each directory has its own counter file. If you remove the file a new one is created the next time a picture of the twg_album is called. You can also modify it with a text editor to maybe reduce a stupid counter value.
The xml directory does also hold the captions (<twg_album>_image_text.xml) and the comments (<twg_album>_album_kommentar.xml). You can delete this files if you want to reset the entries. If you modify something with a text editor there please be careful because the text is stored encoded there (xml does not like something like & ;)).

I want to test TinyWebGallery at my system at home. Is there a easy way to do this?

Yes there is. There is a great project called xampp that has a ready to go package of an actual Apache with installed PHP (and much more). Just go to http://www.apachefriends.org/de/xampp-windows.html and download the package. You have only to execute a batch file to start the Webserver (if you download the zip file!). Simply unpack the TWG into the htdocs directory of xampp and you are ready to go.

Exif information is not shown in TWG but the Windows Explorer does. Why?

Exif information is stored differently by each camera type. The exif reader that is used is looking at a defined set of offsets and tries to extract the information. Windows explorer (and other tools) do just know more offsets than the small php class ;). I have this problem too depending which program I use to process my images. If the images don't work download the freeware version of cam2pc (http://www.nabocorp.com) and resize the image with the flag "copy metadata" set. Use as size a size bigger than your images if you don't want to resize! This nice tool copies the exif data to a place the exif reader con find it ;).

The exif reader is the same coppermine gallery uses. Therefore I want to thank coppermine programmers and the initial developer of the exif class who released this under the GNU General Public License!

Known restrictions

Opera:

The album explorer does not open with Javascript. The layout is not displayed properly if this is done. Therefore a reload is done for displaying it.
When the album exploer is open then sometimes the footer does no stay at the bottom. It jumps dynamically and I haven't found a way to fix this. The html is w3c conform but Opera still acts very weired. Therefore the album tree is always closed automatically by default when you click on it - there is no pin where you can make the explorer album sticky like in the other supported browsers.
Opera opens the popup in a new tab by default and this cannot be resized - therefore the remaining space is black.
Round corners are not supported. The fallback without round corners is used.

How-to's for TWG

Summary Howto - Read this first!

Security & Optimization

Integration of TWG / Random image

Installation & Advanced Setup help

Overview and thumbnail page settings

Detail page settings

Big navigation settings

Video

Global stuff

Layout and colors

FAQ questions & problems

Summary Howto

1. How to secure your TWG data

2. How to include TWG into php sites or a cms system (like mambo, phpnuke).

3. How to integrate your own HTML into TWG

4. Anzeigen eines Zufallsbildes oder meistgesehenen Bildes auf einer anderen Seite oder in einem anderen frame.

5. How to setup a folder image

6. How to set a gallery name different from the folder name (e.g. for enhanced sorting)

7. How to add a folder description (shown below the gallery name) or an image "header"

8. How to create a language file

9. How to change colors of TWG

10. How to check which php version is available on your server and if TWG likes it

11. How to link directly into a password protected gallery

12. How to protect a gallery (and how-to set multiple passwords for one gallery and why ;))

13. How to configure watermarks and text on an image

14. How to track errors if TWG does not work on your system.

15. How to change or extend the smilies

16. Linking to a web site instead of downloading a file

17. How to use a directory based config.php

18. How to enable e-mail notification

19. How to enable download of a whole directory

20. How to link to pictures in a remote http directory

21. How to add a "home" link to the gallery and how to create independant sub galleries

22. How to use a different background image for each folder

23. How to upgrade from older versions from TWG

24. How to show more images in the DHTML thumbnail strip

25. How to use and make a skin!

26. How to include different file formats like avi, mpg ...

27. How to configure the hover effects for ie properly

28. How to use the image.txt

29. How to configure the HTML_SIDE big navigation

30. How to use the TWGXplorer and what is the safe mode any why is this a problem ;)

31. How to update TWG with the installer

32. How to add big folder descriptions like in the AJAX demo - registered version only

33. How to use the lightbox feature (new 1.4.2)- registered version only

34. How to use embedded video support

35. How to choose the right storage location for your xml files

36. How to uninstall TWG if you cannot simply delete it

37. How to use the new backend rights

38. How to use IPTC data in TWG

39. How to mix images and videos in one folder

40. How to include PNG's (and gif's)

41. How to generate preview images for extra file types! - registered version only

42. How to check and enable file splitting (new 1.6)

43. How caching works in TWG

44. How to enable url rewrite and get SEO friendly urls

45. How to optimize the gallery for speed

46. How to use image magick (New 1.7)

47. How to use ffmpeg

48. How to use self registration (New 1.7)

49. How to use the thumbnail flash (New 1.7.3)

50. How to make round corners (New 1.7.5)

51. How to add captions to an image

52. How to use the multi root mode

53. Howto configure your server to run TWG properly

54. How to set a background image

55. How to create/modify the buttons of TWG

56. How to optimize TWG for search engines (SEO)

57. How to make TWG responsive (new 2.2) - registered version only

FAQ (English only!)

I'm using TWG 1.5 and my cmotion thumb strip is not moving anymore!

TWG Admin does not work and all iframes are white

The images/directories are not shown at all or only some are shown

Some of the images are completely black on the thumbnail view

Deleting the cache

You wrote that you removed all the cookies - but when I go to the gallery a cookie is set!

I want to sort my images by the date the picture is taken (using exif data) - what do I have to set on my server?

How can I reset/change the image view counter/caption/comments?

I want to test TinyWebGallery at my system at home. Is there a easy way to do this?