README.md 9.36 KB
Newer Older
Martin Markech's avatar
Martin Markech committed
1
2
3
4
5
6
# Refinery CMS Photo Gallery

__Photo gallery engine for Refinery CMS.__

## Requirements

7
8
9
Currently unreleased version 0.2.x in master branch supports Rails 4.2.x and Refinery CMS ~> 3.0.0

Previous versions of refinerycms-photo-gallery supports Rails 3.2.x and Refinery CMS ~> 2.0.3.
Martin Markech's avatar
Martin Markech committed
10
11
12
13

## Features

* Multiple photo uploading with [Plupload](http://www.plupload.com/) 1.5.4
Martin Markech's avatar
Martin Markech committed
14
* Only HTML5 runtime is supported
Martin Markech's avatar
Martin Markech committed
15
16
* Client side photo resizing to do faster uploading on slow connections
* Server side resizing with Carrierwave
Martin Markech's avatar
Martin Markech committed
17
* Attach album to page. One album can be attached to many pages.
Martin Markech's avatar
Martin Markech committed
18
* Grouping albums to collections. Album can be placed in one or more collections.
Martin Markech's avatar
Martin Markech committed
19
* Ajaxified photo editation during uploading
Martin Markech's avatar
Martin Markech committed
20
21
* Reading EXIF records from file - GPS latitude/longitude, photo title, photo description (In Linux you can put EXIF data using [digiKam](www.digikam.org/) )
* Multiple photo editing at once
Martin Markech's avatar
Martin Markech committed
22
* Fully configurable, searchable
Martin Markech's avatar
Martin Markech committed
23
24
* Using [Fancybox](http://fancyapps.com/fancybox/) 2.0.6 for frontend image slideshow. Read Fancybox license before you
use it on profit websites.
25
26
* Fragment caching on frontend
* Ajaxified pagination with history.pushState on frontend
Martin Markech's avatar
Martin Markech committed
27
28
29

## Screenshots

30
All screenshots are in branch screenshots
Martin Markech's avatar
Martin Markech committed
31

32
33
34
![Photo uploading](https://raw.github.com/Matho/refinerycms-photo-gallery/screenshots/screenshots/07_photos%23upload-uploading_2.png)
![Frontend album](https://raw.github.com/Matho/refinerycms-photo-gallery/screenshots/screenshots/11_frontend_show.png)
![Frontend album](https://raw.github.com/Matho/refinerycms-photo-gallery/screenshots/screenshots/12_show_photo_using_fancybox.png)
Martin Markech's avatar
Martin Markech committed
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52


## Options

* choose runtimes
* set max file size
* on/off client side resizing
* set plupload locale
* file extensions white list
* delete original files after resizing to save disk space
* set dimmensions of photo versions without need to override uploader


## Language

Gem is fully translated to slovak and english. Plupload is translated to 24 languages. You can add your own to
photo_gallery/app/assets/javascripts/refinery/photo_gallery/admin/plupload/i18n and enable it in config.plupload_locale

Martin Markech's avatar
Martin Markech committed
53
54
55
## Browser support
Client side image resizing with Plupload is possible on Firefox 3.5+ (with fixed quality) and Chrome.
Safari doesn't support direct data access to the selected files. Opera 12.00 + supports drag&drop and also client side image resizing.
Martin Markech's avatar
Martin Markech committed
56
57


58
## Installation for ~> 0.2.0
Martin Markech's avatar
Martin Markech committed
59
60
61
62
63
64
65
66
67
68
69
70
71

Make sure, you [have installed ImageMagick](http://www.imagemagick.org/script/install-source.php#unix) and ImageMagick dev.
On Ubuntu 12.04 you can install dev suite with commands:

```ruby
sudo apt-get install libmagickcore-dev libmagickwand-dev
```

Then you need to install command-line Exiftool application.
Instructions for installation you can find under [www.sno.phy.queensu.ca/~phil/exiftool/install.html](www.sno.phy.queensu.ca/~phil/exiftool/install.html).


Open up your ``Gemfile`` and add at the bottom this line:
72
73
74
75
-for edge version:
```ruby
gem 'refinerycms-photo-gallery', '~> 0.2.0', :github=>"Matho/refinerycms-photo-gallery", :branch=>"master"
```
Martin Markech's avatar
Martin Markech committed
76

77
-for latest stable version
Martin Markech's avatar
Martin Markech committed
78
```ruby
Martin Markech's avatar
Martin Markech committed
79
gem 'refinerycms-photo-gallery', '~> 0.1.0'
Martin Markech's avatar
Martin Markech committed
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
```

Now, run 

```ruby
bundle install
```

Next, to install the photo gallery plugin run:

```ruby
 rails g refinery:photo_gallery
```

Run database migrations:

```ruby
rake db:migrate
```

Seed your database:

```ruby
rake db:seed
```
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147

Override pages/show.html file using
```ruby
rake refinery:override view=pages/show.html.erb
```
and at the bottom of file append:
```ruby
<%= render "/refinery/photo_gallery/albums/show" %>
```
It will ensure album photos will be shown. Change it according your needs. 


You have to change list of custom manifest files in your ror app. Copy following values to your app's config/initializers/asset.rb file: 
```ruby
Rails.application.config.assets.precompile += [
"refinery/photo_gallery/admin/photo_gallery.css",
"refinery/photo_gallery/admin/chosen.css",
"refinery/photo_gallery/admin/icons/loading.gif",
"refinery/photo_gallery/admin/photo_gallery.js"
]
```

Then you need to override PagesController in admin namespace. In your terminal run:
```ruby
rake refinery:override controller=admin/pages_controller
```
Then open this overriden file in your app's folder - app/controllers/refinery/admin/pages_controller.rb Look for permitted_page_params method and add check for another attribute:
```ruby
album_page: [:album_id]
```

It should look like: 
```ruby
def permitted_page_params
    [
      :browser_title, :draft, :link_url, :menu_title, :meta_description,
      :parent_id, :skip_to_first_child, :show_in_menu, :title, :view_template,
      :layout_template, :custom_slug, parts_attributes: [:id, :title, :slug, :body, :position], album_page: [:album_id]
    ]
end
```

## Configurations && Fancybox installation
Martin Markech's avatar
Martin Markech committed
148
149
150

You can configure gem in ``your_app_name/config/initializers/refinery/photo_gallery.rb``

151
152
If you want to use ajaxy pagination, copy ``app/assets/javascripts/refinery/photo_gallery/photo_gallery.js`` to your app's asset and add to manifest.

Martin Markech's avatar
Martin Markech committed
153
154
Check, if you have ``jquery.js`` included in your backend.

155
If you want to use Fancybox on frontend, copy ``photo_gallery/app/assets/images/refinery/photo_gallery/fancybox``, ``photo_gallery/app/assets/javascripts/refinery/photo_gallery/fancybox``, ``photo_gallery/app/assets/refinery/photo_gallery/stylesheets/fancybox`` to your
Martin Markech's avatar
Martin Markech committed
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
refinery cms assets directory.

Then you need to add fancybox js files to your js manifest file in ``your_app_name/app/javascripts/application.js``:

```ruby
//= require fancybox/jquery.fancybox.pack
//= require fancybox/lib/jquery.mousewheel-3.0.6.pack
//= require fancybox/helpers/jquery.fancybox-buttons
```

And fancybox css files in ``your_app_name/app/stylesheets/application.css``:

```ruby
*= require jquery-ui-1.8.21.custom
*= require fancybox/jquery.fancybox
*= require fancybox/helpers/jquery.fancybox-buttons
```

And initialize Fancybox in your_app_name/app/views/refinery/_javascripts.html.erb. If you don't have this file
in your app, override it using rake refinery:override command and add this line to it:

```javascript
<script type="text/javascript">
 $(document).ready(function() {
        $(".fancybox").fancybox({
                    prevEffect		: 'none',
                    nextEffect		: 'none',
                    beforeShow : function(){
                      this.title =  $(this.element).attr('data-title');
                    },
                    helpers : {
                        title	: { type : 'outside' },
                        buttons	: {},
                        overlay : {
                            opacity: 0.8,
                            css : {
                                'background-color' : '#000'
                            }
                        }
                    }
                }

        );
    });
</script>
```

203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
If you want to use Fancybox 1.3, use this javascipt to initialize:
```javascript
<script type="text/javascript">
    $(document).ready(function() {
        var load_fancybox = function loadFancybox() {
            $("a[rel=group]").fancybox({
                'transitionIn'		: 'none',
                'transitionOut'		: 'none',
                'titlePosition' 	: 'over',
                'titleFormat'		: function(title, currentArray, currentIndex, currentOpts) {
                    return '<span id="fancybox-title-over">Image ' + (currentIndex + 1) + ' / ' + currentArray.length + (title.length ? ' &nbsp; ' + title : '') + '</span>';
                }
            });
        };
        load_fancybox();

        $("#photo_gallery").on("gallery_loaded", function() {
            load_fancybox();
        });

    });
</script>
```

Martin Markech's avatar
Martin Markech committed
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
Before production, don't forget to precompile assets by:

```ruby
rake assets:precompile
```
## Uninstall

```ruby
rails destroy refinery:photo_gallery
```
From your app db/migrate dir, remove migrations from

``20120805130459_create_collections.refinery_photo_gallery.rb``

to 

``20120805130463_add_indexes.refinery_photo_gallery.rb``

Remove database tables. Run multiple times to remove all photo gallery tables:

```ruby
rake db:rollback
```
Remove fancybox assets folders, which you copied to you app assets and also remove them from your js/css manifests.

Remove fancybox init javascript from _javascripts.html.erb file

Remove gem from Gemfile

Martin Markech's avatar
Martin Markech committed
256
257
258
259
260
261
262
263
## Testing
* cd to this engine path
* bundle install
* rake refinery:testing:dummy_app
* rake spec
* Probably you will need to set some asset manifest to dummy's app manifest - see console output for errors


Martin Markech's avatar
Martin Markech committed
264
265
266
## Todo list

* show live links in admin
Martin Markech's avatar
Martin Markech committed
267
* create pop-up window to upload photos from pages area, like page-images
Martin Markech's avatar
Martin Markech committed
268
269
* add checkboxes to delete multiple/all photos in album
* stop uploading
Martin Markech's avatar
Martin Markech committed
270
* add support for amazon S3 storage
Martin Markech's avatar
Martin Markech committed
271
272
* travis, codeclimate

Martin Markech's avatar
Martin Markech committed
273
274
## Code
[![Code Climate](https://codeclimate.com/badge.png)](https://codeclimate.com/github/Matho/refinerycms-photo-gallery)
Martin Markech's avatar
Martin Markech committed
275

Martin Markech's avatar
Martin Markech committed
276
## Known bugs
Martin Markech's avatar
Martin Markech committed
277
278
279
280
281
282
283
284

* Files with spaces in file names are rejected if you upload them using drag&drop
* Due to Opera bug I turn off Plupload client side mime type validation. It is able to choose files with non valid
file extensions to upload queue. ( But server side validation reject these files.).

## Road map ?

* GPS editing in degrees,minute,seconds format 
285
286
* album/photo tags using acts_as_taggable ?
* show photo location on google maps ?
Martin Markech's avatar
Martin Markech committed
287
288


Martin Markech's avatar
Martin Markech committed
289
290


Martin Markech's avatar
Martin Markech committed
291
292
293
294
295

## License

Refinery CMS Photo Gallery engine is released under the MIT license. Created by Martin Markech, inspired by
Espen Antonsen's [Balder photo gallery](http://balderapp.com/)