1. Before you start
2. Preparation stage
3. Adding yii-gallery-manager to your application
4. Adding behavior and views
5. Tuning up
6. Using migrations
7. Debugging
8. Demo application
9. Sources and information
10. Some alternatives

Finding good looking, working and not abandoned gallery manager for Yii 1.x application is a tough task. Out of all I found, only yii-gallery-manager extension looked promising. But, after downloading it, it turned out, that there are certain unusual things to do, to include it in your application. So, I decided to write this article to remember all these for future reference.

Before you start ¶

Here are some initial points, you should go through, to learn, if this extension is for you:

1. If you're not sure, if yii-gallery-manager extension is for you and want to play a little bit with this, before incorporating it into your application, then follow to "Demo application" section at the end of this text.

2. Gallery Manager is only a set of widgets, models, behaviors and controllers, which provides gallery management functionality to your own models and modules. It is not a ready, out-of-the box solution in form of entire module for managing galleries. Plus, it is also gallery manager only. It is meant for backend and does not provide you with anything special for frontend. You must write your own code for presenting particular gallery basing on data provided by yii-gallery-manager extension.

3. Because galleries are attached to one of your models and are kept in separate tables, using Gallery Manager widget causes changes to be immediately on-line. In other word, user editing any model doesn't have to save it or can even cancel editing it, but changes made by him/her in Gallery Manager are immediately sent (via AJAX), immediately stored in database and are public at once. You should probably pass this information to users of your application. And even consider some implementation, that will make post invisible, if user is editing it and changing galleries.

4. Gallery Manager extension is backed-up by quite powerful yii-image extension (actually a Yii port of famous Kohana image manipulation class) and offers you automated generation of previews for each uploaded image, including many cool graphical effects and image transformations.

5. Extension uses Twitter Bootstrap styles. If you're using it in your application as well, you'll have gallery manager matching styles of your entire application. If you don't use Bootstrap, you don't need to install it (yii-gallery-manager requires only bootstrap.css file as it uses styles from it), but you'll probably have gallery manager in different styling than rest of your application.

If you're convinced to use this extension, then continue reading. If resign, you can scroll to the end of this text, where I put some alternatives.

Preparation stage ¶

To install and use this extension in your application you need:

• yii-gallery-manager extension itself,

• yii-image extension,

• Twitter Bootstrap's styles.

Main repository (at BitBucket) for both extensions are not clonable due to some bug. You should use files added to Download section in extension page at yiiframework.com or alternatively (for main extension only) mirror code repository at GitHub.

Decompress their contents into extensions folder in your application and optionally, change their folders' names.

As for Twitter Bootstrap, you only need it's styles (bootstrap.css) which are used by extension. You don't need entire library.

After unpacking yii_image extension, you need to add it's configuration to your application's configuration array (in protected/config/main.php, if you didn't change this).

It should be:

'image'=>array
(
    'class'=>'application.extensions.image.CImageComponent',
    'driver'=>'GD'
)

if you want to use default PHP's GD library for image processing, or:

'image'=>array
(
    'class'=>'application.extensions.image.CImageComponent',
    'driver'=>'ImageMagick',
    'params'=>array('directory'=>'D:/Program Files/ImageMagick-6.4.8-Q16')
)

if you want to use ImageMagick library.

Double check, if path/alias (application.extensions.image here) are correct and valid. Most operations in yii-gallery-manager extension are made via POST/AJAX and debugging them is a little bit harder. Wrong path/alias to yii-image extension is first source of problems with Gallery Manager not uploading images correctly.

Adding yii-gallery-manager to your application ¶

I decided to use behavior-based approach, because using behaviors is more flexible.

Here are steps, that I took to add yii-gallery-manager to my application:

1. Download (and unpack to extensions folder) yii-gallery-manager and yii-image extension, if you haven't done this yet.

2. Go to migrations folder in yii-gallery-manager and either import schema.mysql.sql to your SQL database or use contents of schema.migration file as base for your new migration (yiic create [name]) and save it. Consider changes discussed later (Using migrations section). Finally, run the migration (yiic migrate).

3. Add ext.yiiimage.*, ext.gallerymanager.* and ext.gallerymanager.models.* to import section of your application's configuration array. Adjust path to these extensions accordingly to where you put them.

4. Add image extension to components section of your configuration array (see above).

5. Consider updating yii-gallery-manager and yii-image extension with files found in demo application (see below) as they seems to be a bit newer.

6. Copy GalleryController.php from yii-gallery-manager extension's folder to location of your controllers (usually protected/controllers) or keep it in original place and add this to main configuration of your application:

   'controllerMap'=>array (

    'gallery'=>'ext.gallerymanager.GalleryController'
   

   ),

Adding behavior and views ¶

Now, your application should be ready to use this extension. All, that is left is to add behavior to your model:

public function behaviors()
{
    return array
    (
        'galleryBehavior'=>array
        (
            'class'=>'GalleryBehavior',
            'idAttribute'=>'gallery_id',
            'versions'=>array
            (
                'small'=>array
                (
                    'centeredpreview'=>array(98, 98)
                ),
                'medium'=>array
                (
                    'resize'=>array(800, NULL)
                )
            ),
            'name'=>TRUE,
            'description'=>TRUE
        )
    );
}

Where name and description decides whether you want to save these kind of data along with each of your gallery to database and idAttribute refers to field in your model, which will store foreign key to gallery. For information about versions, refer to next chapter.

Finally, modify your views. Extension comes with ready widget for managing image galleries:

<?php if($model->galleryBehavior->getGallery() === NULL): ?>

    <p>Before add photos to product gallery, you need to save the product first.</p>

<?php else: ?>
    
    <?php $this->widget('GalleryManager', array
    (
        'gallery' => $model->galleryBehavior->getGallery(),
    )); ?>

<?php endif; ?>

As for presenting image galleries in front end, you're completely on your own. This is backend's gallery manager, not full solution, right. So, as for frontend, it offers you nothing more, than a pure array of data, with which you can do whatever you need or want:

<?php $photos = $content->galleryBehavior->getGalleryPhotos(); ?>

Tuning up ¶

Files, folders and paths ¶

By default, yii-gallery-manager uploads all gallery-related images to gallery folder in web-root of your application. This setting is stored as galleryDir property of GalleryPhoto. I don't know, what reasons caused extension's author to store path to galleries directly in each photo model, instead of Gallery model or even inside GalleryManager widget. But, it is like it is.

And, due to construction of this extension (based on widgets and behavior attached to your own model, operating on POST/AJAX only) there is no way to modify this setting dynamically, in your application. If you need to change directory for your gallery images, you need to simply alter public $galleryDir = 'gallery'; line in GalleryPhoto model.

Auto-generated versions (previews) ¶

Using versions key in galleryBehavior array you can declare, how many (and in what dimensions) previews will be auto-generated for each uploaded image. It is an array like this:

'versions'=>array
(
    'small'=>array
    (
        'centeredpreview'=>array(98, 98)
    ),
    'medium'=>array
    (
        'resize'=>array(800, NULL)
    )
)

Each element in master array represents one preview generated automatically for each image upload. For each preview you can set as many operations, as you want. Each operation (subarray key -- for example centeredpreview) refers to selected image operation -- a method found in Image class in yii-image_ extension. Subarray value is an array of arguments passed to this method (operation parameters).

Examples for resizing preview:

• 'resize'=>array(500, 500) will resize image to fixed 500 x 500 pixels dimensions, ignoring its original aspect ratio,

• 'resize'=>array(800, NULL) will resize image to have longer edge set to 800 pixels and shorter edge relatively to original image ratio,

• 'centeredpreview'=>array(450, 450) will resize image as in second example and then crop it (cut off 450 x 450 pixels in center of image).

Resizing images is most popular operation made for auto-generated previews, but Image class provides you with a lot of graphical effects and image transformations. You can emboss, sharpen, negate image, flip it and rotate it etc.

If this is only possible, try to set fixed value here and do not change it later. Extension provides you with a nifty tool for updating all versions (previews) of images later -- you need to call $model->galleryBehavior->changeConfig(); on each model, which versions / previews are about to change. But, this isn't recommended way, as this will modify many files on-the-fly and can even bloat your server (if you have really big number of galleries there).

Keep in mind, that versions array is kept (serialized) in database for each of your gallery. Therefore, you have to call $model->galleryBehavior->changeConfig(); for each of gallery already stored in database, after changing versions settings.

Widget preview ¶

Using the same methods, a preview for Gallery Manager widget is generated. It's line 147 of GalleryPhoto model, inside setImage method:

Yii::app()->image->load($path)->resize(300, null)->save(Yii::getPathOfAlias('webroot') . '/' .$this->galleryDir . '/_' . $this->getFileName('') . '.' . $this->galleryExt);

It generates too big preview (300 px longer edge, while actual widget uses 140 px at max) and produces over all not so cool effect, with a large piece of white empty space below each image preview. If found out that, changing this line to:

Yii::app()->image->load($path)->centeredpreview(140, 140)->crop(140, 120)->save(Yii::getPathOfAlias('webroot') . '/' .$this->galleryDir . '/_' . $this->getFileName('') . '.' . $this->galleryExt);

And changing following lines in assets/galleryManager.css:

• line 126, .GalleryEditor .caption p selector, add white-space: nowrap; line,

• line 33, .GalleryEditor .photo selector, change line-height: 1; to line-height: 0.7;,

• line 144, .GalleryEditor .image-preview selector, change height: 88px; to height: 120px;,

will produce a much better effect. But, this is my private opinion. Note, that you should add first change in any conditions, even if you don't change anything else, as it seems, extension's author forgot about this line. Without it, long photo descriptions spans into many lines, ugly messing around in edit and delete buttons' background.

Another thing, that was missed by extension's author is adding this style to the end of ``:

.sorter
{
    overflow: auto;
    height: 400px;
}

Without this assets/galleryManager.css, images area in your gallery won't be vertically scrollable and you will have no access to other photos, if you upload many images to particular gallery. Remember to remove assets after applying these changes, to actually see them on-line.

Using migrations ¶

If you're using migrations to update database, then note, that schema.migration file found in migrations folder in yii-gallery-manager extension folder has some problems, that should be / must be corrected.

First thign is, that you should add $this->dropForeignKey('fk_gallery_photo_gallery1', 'gallery_photo'); to your down() method to clean everything, what was created by up() method; add it before dropping extension's tables:

public function down()
{
    /**
     * Drop yii-gallery-manager extension tables.
     */
    $this->dropForeignKey('fk_gallery_photo_gallery1', 'gallery_photo');

    $this->dropTable('gallery_photo');
    $this->dropTable('gallery');
}

And, if you're using behavior, you should modify all your tables / models, that will be using galleries, and add new column, that will hold gallery ID per particular model. Name this column the same way as you name idAttribute parameter in behavior configuration. By default, it should be named gallery_id. I suggest to alter this name only, if it conflicts with something in your model or application:

$this->addColumn('contents', 'gallery_id', "integer DEFAULT NULL COMMENT 'Foregin key to Gallery -- gallery for this content' AFTER `content_id`");

Debugging ¶

You can use modified piece of code from GalleryController::actionAjaxUpload() to do pretty nice debugging. Put this code somewhere (in some view?) and execute:

<?php 
    $model = new GalleryPhoto();

    $model->gallery_id = 123;
    $model->file_name = 'test1';

    $model->setImage('test2');
 ?>
 

It helped me discover problems with database (incorrect table names) in first place and it brought me answer, why the heck images are not uploaded? After three hours of searching, I found out, that Yii isn't able to find CImageComponent. I wasn't able to discover this earlier, because all upload-related events occurs in post-only, ajax-mode mood, which is quite hard to debug.

Demo application ¶

There's a nice looking and (nearly) ready to use demo application found at BitBucket (this time repository is cloneable): https://bitbucket.org/z_bodya/yii-demo-blog. It contains Gallery Manager and other extensions made by this author.

When you get it running, don't be surprised, that you see no sign of gallery manager at first. To see it in action, you should edit any post (or create new one), because gallery manager widget has been included only in this view (and in post view in frontend, once particular view contains some gallery).

This is very simple demo, and need some sort of work to port it to working application. But, for sure this is a good starting point for dealing with all troubles you may have with this extension. And a nice thing from author, that he wanted to spare his time not only on writing extension itself, but also for providing working demo application. Big thumb up from my side! :>

Note, that cloned code does not contain assets folder and protected/runtime folder. You should create these two in point 2.5 (before changing folder permissions) of instruction mentioned in BitBucket repository.

Therefore, steps for installing demo application are this:

1. Clone repository (git clone git@bitbucket.org:z_bodya/yii-demo-blog.git).

2. Install composer dependencies (run php composer.phar install or composer install inside protected folder).

3. Create missing folders (mkdir assets, mkdir protected/runtime).

4. Change folder permissions (chmod -R 777 assets protected/runtime gallery uploads images in most situations).

5. Run application in your browser, login using demo/demo, go to control panel and edit (or create and save first) any post found there.

Read [this article](Installing Composer to PHP on Windows.txt) if you don't have Composer on your Windows and need to install it.

Note, that demo applications includes gallery's cover image functionality, requested by some user and implemented as a part of separate branch. It is not included in master branch and since branches at BitBucket are not accessible right now, you can only get this feature by hand-copying changed code.

Sources and information ¶

Here is a list of pages, you may wish to visit to read more about yii-gallery-manager:

• extension page at yiiframework.com,
• main code repository at BitBucket,
• mirror code repository at GitHub,
• demo application at BitBucket.

Main repository at BitBucket is not accessible (the moment of writing it) and does not provide a code to clone. You should use GitHub mirror instead or download .tar.gz file from extension page at yiiframework.com.

There's also a forum discussion on this extension, but last post (unanswered) is over two years old now. So, this forum is pretty useless.

Some alternatives ¶

If, for any reason, yii-gallery-manager is not an option for you, you can consider these alternatives:

• https://code.google.com/p/yii-gallery-extension/
• https://github.com/Crisu83/yii-imagemanager
• https://github.com/drumaddict/angular-yii