By default JoomGallery doesn't use the real path of images for their URLs, but a generic one which identifies an image with its ID. This has several advantages like the possibility to count the views on images and to be able to move images around after uploading without having to adapt all the pages where the image was already published.

Unfortunately, there is a disadvantage, too: The image URLs aren't very good for SEO anymore and they don't end on a valid image file extension like .jpg.

One possibility to solve that problem is to enable option 'Use real paths' in tab 'General Settings' -> 'Paths and directories' of the configuration manager, but with that you will lose all the advantages of the generic URLs. Additionally it has to be noted that this change cannot be applied in all situations. For example, when inserting images into articles with the help of the content plugin JoomPlu still the generic URLs will be used due to technical reasons.

The good news is that you can still enable good SEF URLs for images in JoomGallery by using the core SEF of Joomla! (the following won't work if you are using a third party SEF extension).

1. You have to ensure that you are using the core SEF with having 'Use URL rewriting' and 'Adds Suffix to URL' enabled.
2. Go to control panel of JoomGallery and click on the 'Options' button in the toolbar. In the 'SEO Settings' tab enable the SEF URLs for images.
3. Depending on whether you are using a '.htaccess' or a 'web.config' file in your Joomla! root directory do the following change:

.htaccess

Search the following line in your '.htaccess' file

RewriteCond %{REQUEST_URI} /component/|(/[^.]*|\.(php|html?|feed|pdf|vcf|raw))$ [NC]

and add the 'jpg' file extension to the list of allowed extensions so that it looks like that:

RewriteCond %{REQUEST_URI} /component/|(/[^.]*|\.(php|html?|feed|pdf|vcf|raw|jpg))$ [NC]

web.config

Search the following line in your '.htaccess' file

<add input="{URL}" pattern="/component/|(/[^.]*|\.(php|html?|feed|pdf|vcf|raw))$" />

and add the 'jpg' file extension to the list of allowed extensions so that it looks like that:

<add input="{URL}" pattern="/component/|(/[^.]*|\.(php|html?|feed|pdf|vcf|raw|jpg))$" />

If you have any questions about that feel free to visit our forum.

SEF URLs for images are available in JoomGallery starting with version 3.1 (there are workarounds for versions 2.5 and 3.0 in our forum).

This article explains how to use the JoomGallery plugins JoomAdditionalImageFields and JoomAdditionalCategoryFields to extend the image resp. category information with additional, user defined information.

For that you first have to install one (or both) of the plugins, dependent on whether you need the additional information fields for images, categories or both. Don't forget to activate the plugin(s) in the Plugin Manager of Joomla!. After completing the installation please rename the file(s) 'additional.tmp.xml' in the folder 'plugins/joomgallery/joomadditionalimagefields/additionalfields/' resp. 'plugins/joomgallery/joomadditionalcategoryfields/additionalfields/' to 'additional.xml'. After that you will find an additional slider resp. fieldset with 'Additional Fields' in JoomGallery's backend resp. frontend in the respective edit view (either image or category edit view). You will not find any 'Additional Fields' in any JoomGallery upload form yet.

The additional fields you can see are just some example fields showing what is possible. If filled with data, the information will be displayed in the frontend views (gallery, category, detail view). To define your individual additional fields you have to adapt the respective XML file(s) 'additional.xml' to suite your needs. Therefore you need some further Joomla! knowledge about Joomla! forms and Joomla! fields. For now, please consult the Joomla! documentation for details.

This documentation will be extended and will become more detailed soon.

We are keen to construct the gallery on a way that it is accplicable universally. For this it is necessary to integrate other components, modules und plugins which aren't written by us (e.g. Community Builder, AlphaUserPoints or JComments to just mention a few).
For some, we already developed additional add-ons which establish a connection between the particular third party extension and JoomGallery. You can find them in our downloads and here is a small summary of all of them.

Since we aren't able to create JoomGallery add-ons for every available extension or some of you have a special intent JoomGallery offers a huge API, which you may use. So this article is mainly interesting for the developers among you.

If you have decided to write your own extension for JoomGallery you will find below a full description of the JoomGallery API.
Examining already existent extensions may also help you for your own development.

The API of JoomGallery is divisible into three main areas:

• Interface class
  The interface class offers - once included in your extension - many useful functions in order to 'communicate' with the gallery and to query information or output images.
• Module positions
  Inside JoomGallery, several module positions are built-in which you may use like the module positions of your template. Additionally they may be loaded very individually.
• Plugin events
  For the diverse tasks the gallery executes or while displaying the views different events are triggered to which your plugins may react und influence the gallery.

Interface class

In order to use the interface class it needs to be included in your extension first. This happens with the follwing code:

$file = JPATH_ROOT.DS.'components'.DS.'com_joomgallery'.DS.'interface.php';
if(!file_exists($file))
{
  JError::raiseError(500, 'JoomGallery seems not to be installed');
}
else
{
  require_once $file;
  $interface = new JoomInterface();
}

The variable '$interface' now holds the interface object (provided that JoomGallery is installed).

By now you are able to use the functions the interface provides.
A call looks like this, for example:

$interface->getPageHeader();

or like this if something you need is returned by the function:

$images = $interface->getPicsOfUser($userid);

The funktion 'getPageHeader' will be important if your extension shall output images or the like and you want to use the style definitions of the gallery, because it loads the CSS files of JoomGallery.

Please have a look at the interface class on your own ('components/com_joomgallery/interface.php'). There are descriptions in the header of every function, which list what the function does, what it returns possibly and which parameters it needs.

At this point only the function 'addConfig()' shall be mentioned additionally. With this one, you are able to configure the interface. For example, you may define the method which will be used to open an image:

$interface->addConfig('openimage', 6);

The number 6 is mapped with Slimbox, other assignments are listed below:

0 => Default view
1 => New window
2 => JavaScript window
3 => DHTML Container
5 => Thickbox3
6 => Slimbox
12 => additional plugins

If 'openimage' isn't set, the interface will use the correspondent setting of JoomGallery's configuration manager ('Entering Detail View' in tab 'Category View' -> 'General Settings').

Further options are 'group', 'limit' or 'type', for example.

Module positions

For the module positions of the gallery, there is a separate article in the documentation which you can find here: Module positions.

You may also add your own module positions at any point inside the gallery with the help of template overrides by using the following code:

<?php $this->loadModules('positionname'); ?>

With this, the new module positions can be used with suffixes right like the already integrated ones. Please note, that you have to specify the prefix 'jg_' in module manager also with this positions ('jg_positionname'), but please omit it in the function call.

Plugin events

Developers among you know that there are different plugin types in Joomla, e.g. content plugins, user plugins or system plugins.

Of course, you may write JoomGallery extensions for this types which use the interface class, for example, like the content plugin 'JoomPlu'.

In this section of the API documentation, however, we want to concentrate on plugin events which are triggered solely by JoomGallery and its extensions. For this, JoomGallery accesses an additional plugin type which is called 'joomgallery'.

So if you want to create a plugin which is able to influence the gallery, the 'install' element of the correspondant XML install file should look like this:

<install version="1.5" type="plugin" group="joomgallery" method="upgrade">

For the general constitution of a plugin, please have a look at one or more of the example plugins which are delivered with Joomla.

In the following, there is a list with all plugin events currently built-in JoomGallery:

• onJoomBeforeComment
• onJoomAfterComment
• onJoomBeforeUpload
• onJoomAfterUpload
• onJoomBeforeVote
• onJoomAfterVote
• onJoomBeforeSendMessage
• onJoomAfterAddFavourite
• onJoomAfterRemoveFavourite
• onJoomAfterClearFavourites
• onJoomAfterDisplayThumb
• onJoomAfterDisplayCatThumb
• onJoomAfterSend2Friend
• onJoomAfterTag
• onJoomDisplayIcons
• onJoomDisplayUser
• onJoomGetCaptcha
• onJoomCheckCaptcha
• onJoomGetLastComments
• onJoomGetSmileys
• onJoomOpenImage
• onJoomSearch

Template overrides are a powerful tool for customising your output of components and modules.

In Joomla it's very easy to create those overrides and JoomGallery supports that fully for every single view. So you are able to customise the layout of Joomla until it perfectly fits into your site.

The procedure is described here in general, please read that article first.

Nevertheless we will describe it here with examples of JoomGallery, too.

In order to create such an override only one step is necessary: Copying the layout file you want to override into the 'html' directory of your template, but it needs to be the correct one.

For this please have a look into the folder 'components/com_joomgallery/views/'. There you can find directories for each view of the gallery and in each of these directories there is a folder called 'tmpl'. All files in these 'tmpl' folders can be overridden in your template.

For example have a look in folder 'components/com_joomgallery/views/favourites/tmpl'. There are two different layouts: 'default.php' and 'list.php'. The other files there are included by these two according to their name. Please also note that you can find this structure again while creating a new menu item for JoomGallery in the menu manager.

Now the important thing:
If you want to override the detail view for example please download file

'components/com_joomgallery/views/detail/tmpl/default.php'

and upload it again into directory

'templates/<your_template>/html/com_joomgallery/detail/'.

If this directory structure doesn't exist (which is most probably the case if you are doing this the first time) you will have to create the folders first.

Overriding gallery view would mean to copy file

'components/com_joomgallery/views/gallery/tmpl/default.php'

to

'templates/<your_template>/html/com_joomgallery/gallery/default.php'.

As you can see the 'tmpl' folders is left out while creating the structure in the template.
So in general the new paths in the template look like this:

'templates/<your_template>/html/com_joomgallery/<view_name>/<layout_name>.php'.

Please note that the main layout files (e.g. called 'default.php' or 'list.php') include other layout files like 'default_header.php' or 'list_footer.php'. You are able to override them also or even only them by only copying these sub-files.

As promised before we will place in the gallery several module positions. So you can include e.g. ads banner or additional information to your visitors. Here a litte howto about using this module positions.
At the moment this 4 positions exist:

If you need more positions ask at the forum.

To publish a module at one of these positions click in the text inputfield of the combo box 'Position' and type in the name of the position. It's not possible to select the position with clicking on the box because then you can see only positions provided by the template.

Since version 1.5.0 of the JoomGallery you can make the positions to load the module more individual. For example you wat to see a module above the pathway but only on the startpage of the gallery, the gallery view.

You can reach this with the more specified position 'jg_top_gal'. The Position 'jg_top' means as described showing the module above the pathway and the suffix '_gal' leads to displaying the module only at the gallery view.

If there are more modules positioned at 'jg_top' they will be shown furthermore on all pages of the gallery.

You can use the following suffixes:

We thought this are the most essential ones. But you can control other sites in the gallery by using the value assigned to 'view' as suffix. You can find them in the URL on each site (e.g. &view=downloadzip).

So 'jg_btm_downloadzip' would load a module at the bottom in the gallery, but only at the site where you can download a zip with your favorites.

• AlphaUserPoints
• Artio JoomSEF
• CB
• CBE
• HighSlide JS
• JComments
• JomComment
• JomSocial
• Joom!Fish
• Kunena
• reCaptcha
• RokBox
• SEFAdvanced
• sh404SEF
• Shadowbox JS
• Xmap

The migration from JoomGallery 1.5.7 to JoomGallery 2 is possible with the help of the migration script you can download here.

Please note that the migration can only be done from JoomGallery 1.5.7. In case that you are still using previous versions you have to update them first.

This article will guide you through all the steps that have to be done for migrating the gallery successfully:

• Step 1: Backup
• Step 2: Preconditions
• Step 3: Installation of JoomGallery
• Step 4: Installation of migration script
• Step 5: Migration
• Step 6: Check
• Step 7: Clearance

Step 1: Backup

Surely this is the most important step for the whole migration. Even though we have tested the migration extensively we cannot guarantee that it will work successfully for everyone.
There can be undiscovered bugs or the migration fails because of missing write permissions on the server, for example.

Therefore, a complete backup of the filesystem and the database tables is indispensable.

In case that the migration fails this is the only possibility to reverse the operation. Please create the backup carefully and test it.

The migration deletes all image files in the source folders.

Step 2: Preconditions

Since a simple update from Joomla! 1.5 to Joomla! 1.7/2.5 isn't possible you have usually two parallel Joomla! installations: Old Joomla! 1.5 and the new Joomla! 1.7/2.5 (created with component jUpgrade, for example).
Please do a check im migration manager in the old installation for removing problems if there are any.
For migration of JoomGallery additionally the following preconditions must be fulfilled:

• The three image folders of the images to migrate must be in the same webspace than the new Joomla! 1.7/2.5.
• The database tables of JoomGallery 1.5.7 must be in the same database than the tables of the new Joomla! 1.7/2.5.

These conditions are already fulfilled if you used jUpgrade component for creating the new Joomla! 1.7/2.5. In this case please simply jump to step 3.

Otherwise please check whether the conditions are fulfilled:

• If the images are on another server you have to move them to the new one via FTP first.
• If the database tables are in another database, please transport them to the new one via export/import of PhpMyAdmin or MySQL-Dumper.
  Important: Along with that, please ensure that there prefix (the part afore string 'joomgallery') is not the same than the one of the other tables there (but a uniform one). Otherwise the migration is not possible.

Step 3: Installation of JoomGallery

In accordance with the preconditions the images are now on the same server than the Joomla! to which you want to migrate and the old database tables of JoomGallery are in the same database than that Joomla!, but with their own prefix.

Please download JoomGallery 2 now from here and install it via the installer of Joomla! 1.7/2.5.

If everything is correct there shouldn't be any problems during installation and you should get a message for the successful installation, not a message for an update or even an error.

If you don't want to store the images in the default image folders of JoomGallery (in 'images/joomgallery/') please edit the image paths in first tab of the ocnfiguration manager and create the folders now.

Step 4: Installation of migration script

Please download the migration script now (if not already done) from here and install it also via the installer of Joomla! 1.7/2.5.

After the installation please enable the offline mode of Joomla! 1.7/2.5. You can do that in the first section of global configuration of Joomla!.

Then, please go to migration manager of JoomGallery 2 (you can find it near CSS manager and maintenance manager in the menu of JoomGallery).
There, you should see a possibility for migrating JoomGallery 1.5.7 to JoomGallery 2 with a small form and a check button. This form has to be filled completely first:

Database prefix of Joomla! 1.5
Please insert here the database prefix of the old Joomla! 1.5 (e.g. jos_).

Path to Joomla! 1.5
If the old Joomla! 1.5 installation is on another server or doesn't exist anymore, please insert here a hyphen: '-'.
Otherwise, you have to enter the complete absolute path to the old Joomla! 1.5. The suggested value is the path to the current Joomla! 1.7/2.5 and has to be changed usually only marginally. For determining the correct path you should have a look on your server via FTP.

Path to original images, Path to detail images, Path to thumbnails
Here you have to specify the paths to the original, detail and thumbnail folders of the old Joomla! installation. If you entered a hyphen at Path to Joomla! 1.5 you will have to specify the complete absolute paths. Otherwise, please copy in the corresponding values from the configuration manager of the old JoomGallery 1.5.7.

Check owners
If this option is enabled there will be checked for all owners of the images and categories whether these users exist in Joomla! 1.7/2.5. If the latter isn't the case the value will be set to 0. This would be possibly later on in maintenance manager, too.
If you also migrated the users to Joomla! 1.7/2.5 should remain disabled.

Then, please click on 'Check'. With that it will be checked whether a migration is possible. If there are any problems you may have to go back to the form and correct the values.

Step 5: Migration

If all entries are marked green you may start the migration with the button 'Start'.

Depending on the size this may take some time (an hour or more is not uncommon). Please don't interrupt the process by no means, but wait until you get an error or a message of success.
For dealing with possible errors and a check please have a look at step 6.

Step 6: Check

If the migration ends with a message of success all categories, images, comments, name tags, votes, favourites and many parts of the configuration were transfered successfully.

After creating a menu item for the gallery in menu manager of Joomla! should see the gallery in frontend like before.

Finally, please start a check in migration manager to ensure that actually everything is alright.

Possibly you have to adjust some settings in configuration manager because there couldn't be migrated all settings for technical reasons (especially the part of the upload permissions and things like that because this is handled via the ACL of Joomla! now).

In the case there there were errors during the migration please download the log file 'migration.mvc2acl.php' from the log directory of Joomla!. Usually, this is the folder 'logs' in the root directory of Joomla!.
If you migrated your Joomla! with the help of component jUpgrade possibly the log directory of the old Joomla! installation is still used for the new one. You may check that in the global configuration.

Please have a precise look at the log file. If only single images weren't transfered you probably are able to do that manually now. If there were serious errors (e.g. a category could not be created) please import your backup and check whether there is alright in the old Joomla! installation afore trying again.

If you have any questions please feel free to ask the in the board 'Migration' of our forum.

Step 7: Clearance

If the migration was successful you should uninstall the migration script again. For that, please click on 'Manage' in extension manager of Joomla! and filter by type 'File'.

The datebase tables of the old gallery are now waste because the image files were moved away and should be deleted. The image folders of the old gallery should also be deleted via FTP because during migration only the image files were moved away, so the folders are still there.

Only a few steps are necessary in order to get JoomGallery running on your Joomla based website. Here's a short overview over them, but they are described in the proximate article:

• Step 1: Installation of the Component
• Step 2: Installation of Desired Language Files
• Step 3: Choosing Image Folders
• Step 4: Creating a Category
• Step 5: Uploading Some Images
• Step 6: Creating a Menu Item
• Step 7: Setting Up the Gallery

Step 1: Installation of the Component

The system requirements of JoomGallery are the following (please check them afore trying to install the gallery):

• Joomla! 1.5 (Legacy Mode is not necessary)
• PHP5
• MySQL 4.1 or better MySQL 5

The installation of JoomGallery is done via the installer of Joomla! as it is for all other Joomla components, too.

If you are not familiar in installing components for Joomla! please check this link.

Please note: Updates are done in the same way: Simply install the new package without uninstalling the gallery afore or else you would lose all the data.

If the installation was successful you should see a page like this one:

Please don't click it away, but jump to step 2 first.

Step 2: Installation of Desired Language Files

If the installation was successful there should be offered two buttons for you: 'Start now!' and 'Languages'. If you want to use the gallery in English language, please simply click on 'Start now!' and jump to step 3.

Otherwise, if you want to see the gallery in any other language please click on 'Language'. With that you will be redirected to 'Help and Information' manager of JoomGallery (you are able to come back to this manager at any time by clicking on the correspondent administrator menu item of JoomGallery).
In this manager you can find all languages the gallery has already been translated into. If your language isn't in the list unfortunately there aren't any language files for this language yet. In that case you would have to use the gallery in any other available language for now or you could create the translation by yourself. Please contact us if you are willing to do so.

If you have found your language please click on the corresponding flag. If a certain functionality (cURL-Library) is enabled on your server the language files will be installed and applied to the gallery automatically by this click. Please simply return to the Admin Menu of JoomGallery by selecting it in the 'Components' menu. You should see the gallery in your language then (for some languages there are only frontend language files available yet, so the backend isn't translated, but you should see the gallery translated in the frontend later on in step 6 after creating a menu item).

If cURL isn't installed on your server you will be redirected to the download page of the requested language files after clicking on the flag. Please download the language pack (a zip file) and install it via the installer of Joomla! just like JoomGallery itself afore. JoomGallery will have access to the language files with that.

The gallery always automatically uses the language which is chosen in Joomla!'s language manager!
You don't have to do anything else after installing the language pack.

Please remember to also update the language files after each update of JoomGallery.

Step 3: Choosing Image Folders

By default JoomGallery stores all uploaded images into sub-folders of 'images/joomgallery/' (these are created automatically). If you don't want to change that please simply jump to step 4.

Otherwise, if you want to move the image directories into another folder (for example since you don't want the string 'joomgallery' to appear in your image paths) please move the three folders you find in 'images/joomgallery/' to another place with the help of an FTP client (Note: At the moment the images cannot be stored outside of the Joomla! root directory!).

After that please go to 'JoomGallery' -> 'Configuration Manager' in the backend. In the tab 'General Settings' -> 'Paths and Directories' the image directories will be marked red then. Please correct them according to the new locations and press 'Apply' in the toolbar above until all directories are marked green again.
If you have problems with that please contact us in the forum.

Step 4: Creating a Category

Before you are able to upload any images at least one category has to be created.
For this please go to 'JoomGallery' -> 'Category Manager' in the 'Components' menu or select the category manager in JoomGallery's admin menu.

After that please search the 'New' icon in the toolbar above and click on it. With that the edit view for a category will be opened.

Please enter a name for the new category into the field 'Title' and have a look at the toolbar above again. Now there should be a button called 'Save' with which you are able to create the category. For now you don't have to fill anything else into the fields in the edit view.

After clicking on 'Save' you will be redirected back to the list of categories which should show the just successfully created category.

Step 5: Uploading Some Images

Now that a category is created you can start uploading images. For that please go to 'Image Upload' in the sub-menu of JoomGallery where you can select several images (or only one) you want to upload (don't worry, mass uploads will be possible with the other upload managers, too). After doing this you have to type in a general name for the images into the field labeled with 'Generic Title' and to select a category above it. So you need to select the one created afore. Please don't bother about the other fields yet, but simply click on 'upload'.

If there aren't any errors you will be informed about the successfully uploaded images. You can go to 'Image Manager' in order to check or edit them.

Step 6: Creating a Menu Item

Until now we worked only in the backend, but of course finally you want to see the gallery in your page on the frontend. For that we have to create a menu item for JoomGallery.

In order to do that please go to 'Menus' -> 'mainmenu' (or any other already created menu) and click on the toolbar button 'New'.

You will see a list of the installed components then, so please click on 'JoomGallery'. With that the list will be expanded to show the available views of JoomGallery with their layouts. For starting please select the default layout of the view 'Gallery (default)'.
After clicking on the layout you will be able to type in the displayed name of the menu item into field called 'Title'. Please do so (for example simply 'Gallery') and press 'Save' in the toolbar.

If you go to your site in the frontend then, a new menu item in your selected menu should have appeared. After clicking on it you will see the gallery view of JoomGallery in your site which shows the category you created.

Please don't hesitate to click on each link in the gallery and see what happens.

Step 7: Setting Up the Gallery

Since most probably at the moment the gallery doesn't look like or have the functionality you want it to have you will have to configure the gallery.
Most of this is done in the configuration manager with all of its available settings. There are very many as you have probably seen before.
It is very important that you really have a look at all the options and read all descriptions there in order to learn what the gallery is able to do.

We recommend to start with the settings in tab 'General Settings' -> 'Image processing' in order to determine the size of the automatically resized images. Please change the settings until the images perfectly fit into your template, but please note that a change of these settings will only be applied to images which are uploaded after the change (images uploaded before can be resized with the new settings by using the 'Recreate' button in image manager).

Then, play with all the other settings until the gallery works like you want it to work!

It is possible to have a very clean displaying of the whole gallery as well as to have very many options and community functions enabled.

If you still have any questions please use the search function in our forum, most probably some one had the same question afore!
If not, please don't hesitate to start a new thread!

Have fun with JoomGallery!