new syntax for configure & run, with legacy support

docs/api/events.rst

@@ -8,20 +8,36 @@ similar to jQuery's event model, except that it adds event.scope that refers to
 the current gallery scope of each event. Some events will add even further
 properties to the event object, specified here.
 
+In the callback, the ``this`` keyword inside the callback always refers to the gallery scope.
+
 .. highlight:: javascript
 
-Use ``.bind()`` to listen to the Galleria events. In the callback, the this
-keyword inside the callback always refers to the same gallery scope. Example::
+=====================
+How to use the events
+=====================
+
+You can use the global ``Galleria.on()`` function to bind functions to events, f.ex::
 
-    this.bind("thumbnail", function(e) {
+    Galleria.on('image', function(e) {
         Galleria.log(this); // the gallery scope
-        Galleria.log(e) // the event object
+        Galleria.log(e.imageTarget); // the currently active IMG element
     });
 
-    this.bind("loadstart", function(e) {
-        if ( !e.cached ) {
-            Galleria.log(e.target + ' is not cached. Begin preload...');
-        }
+Or you can use ``.bind()``  inside the ``Galleria.ready`` or ``extend`` to listen to
+the Galleria events. Example::
+
+    Galleria.ready(function() {
+
+        this.bind("thumbnail", function(e) {
+            Galleria.log(this); // the gallery scope
+            Galleria.log(e) // the event object
+        });
+
+        this.bind("loadstart", function(e) {
+            if ( !e.cached ) {
+                Galleria.log(e.target + ' is not cached. Begin preload...');
+            }
+        });
     });
 
 =======================

docs/api/utilities.rst

@@ -9,17 +9,64 @@ Static methods are exposed using ``Galleria.fn()``.
 
 .. highlight:: javascript
 
+Galleria.run( selector, options )
+--------------------------
+
+    | returns Galleria
+
+This function initializes the gallery. The first argument is the jQuery selector of
+element(s) you want to load the gallery to. The second argument (optional) is an object
+of configuration options::
+
+    Galleria.run('#galleria');
+    Galleria.run('#galleria', {
+        imageCrop: true,
+        transition: 'fade'
+    });
+
+
+Galleria.configure( options )
+--------------------------
+
+    | returns Galleria
+
+This function configures options to the gallery. The options you specify here will be
+applied to all instances on the page. If you want to apply options for a specific gallery,
+use the ``.setOptions()`` API call, or apply the options when calling ``Galleria.run()``.
+
+You can add multiple options like this::
+
+    Galleria.configure({
+        thumbCrop: true,
+        lightbox: true
+    });
+
+Or single options using key/value::
+
+    Galleria.configure('imageCrop', false);
+
+The options will be applied to the gallery no matter when it’s called. If the gallery
+is not yet ready, they will be applied when it is. If the gallery is already running,
+the options will be applied at run-time.
+
+
 Galleria.ready( function )
-----------------------------------------
+--------------------------
 
-    | returns null
+    | returns Galleria
+
+Use this function to bind bind custom functionality to each gallery instance
+when the gallery is loaded. Example::
+
+    Galleria.ready(function() {
+        Galleria.log('Gallery ready', this); // the Galleria instance
+    });
 
-Use this to bind custom functionality to each gallery instance onload. Works the same way as the extend option.
 
 Galleria.log( msg [,msg,...] )
 ------------------------------
 
-    | returns null
+    | returns Galleria
 
 A helper metod for cross-browser logging. It uses the console log if available
 otherwise it falls back to the opera debugger and finally ``alert()``
@@ -28,37 +75,27 @@ otherwise it falls back to the opera debugger and finally ``alert()``
 Galleria.raise( msg )
 ---------------------
 
-    | returns null
+    | returns Galleria
 
 This method will raise an error message if Galleria.debug is true. Useful if
 you have sensitive code that needs to throw an error if not completed when
 developing.
 
 
-.. _galleria_get:
-
 Galleria.get( [index] )
 -----------------------
 
-    | returns Galleria
+    | returns instance or array of instances
 
 Use this to fetch a galleria instance from anywhere on your page. If you only
 have one galleria gallery, ``Galleria.get(0)`` will return the first (and only)
 gallery. If you call ``Galleria.get()`` without specifying an index, it will
 return an array with all galleries initiated. Example::
 
-    $('#images').galleria(); // initialize the galleria
+    Galleria.run('#galleria'); // initialize the galleria
 
-    var gallery = Galleria.get(0); // gallery is now the first galleria instance
     $('#play').click(function() {
-        gallery.play(); // will start slideshow when the element #play is clicked
-    });
-
-    $('#images2').galleria() // initialize another gallery
-
-    var galleries = Galleria.get(); // galleries is now an array of all galleria instances
-    $('#fullscreen').click(function() {
-        galleries[1].enterFullscreen(); // will enter fullscreen mode for the second gallery
+        Galleria.get(0).play(); // will start slideshow when the element #play is clicked
     });
 
 
@@ -67,7 +104,7 @@ return an array with all galleries initiated. Example::
 Galleria.loadTheme( url[, options] )
 ------------------------------------
 
-    | returns null
+    | returns Galleria
 
 This methods loads a theme into galleria. It will insert the necessary scripts
 and styles into the document and provide a event that will hold the galleria
@@ -79,7 +116,7 @@ absolute path to the theme .js file. Example::
     Galleria.loadTheme('galleria/themes/classic/galleria.classic.js'):
 
     // initiate the gallery
-    $('#images').galleria();
+    Galleria.run('#galleria');
 
     // when the theme is fully loaded, galleria will run.
 

docs/getting_started/beginners_guide.rst

@@ -107,7 +107,7 @@ but the simplest one is probably to just add images as HTML.
 
 Add the following markup inside the ``<body>`` tag::
 
-    <div id="gallery">
+    <div id="galleria">
         <img src="photo1.jpg">
         <img src="photo2.jpg">
         <img src="photo3.jpg">
@@ -132,10 +132,7 @@ Set dimensions and fire up the gallery
 All we need to do now is set dimensions and apply Galleria.
 Add the following script after the loadTheme function we just inserted::
 
-        $("#gallery").galleria({
-            width: 500,
-            height: 500
-        });
+        Galleria.run('#galleria');
     </script>
 
 As you can see, we just applied galleria to the '#gallery' container where the images are, and set dimensions to 500x500 pixels.
@@ -155,17 +152,14 @@ The complete code example:
             <script src="galleria/galleria-1.2.7.min.js"></script>
         </head>
         <body>
-            <div id="gallery">
+            <div id="galleria">
                 <img src="photo1.jpg">
                 <img src="photo2.jpg">
                 <img src="photo3.jpg">
             </div>
             <script>
                 Galleria.loadTheme('galleria/themes/classic/galleria.classic.min.js');
-                $("#gallery").galleria({
-                    width: 500,
-                    height: 500
-                });
+                Galleria.run('#galleria');
             </script>
         </body>
     </html>

docs/getting_started/quick_start.rst

@@ -23,28 +23,28 @@ There are several ways of adding image data to your gallery, but the simplest
 way is probably to add some HTML. Just put the images inside any container on
 the site. You can also add titles and descriptions using data attributed on the IMG tag::
 
-    <div id="gallery">
+    <div id="galleria">
         <img src="/img/pic1.jpg" data-title="My title" data-description="My description">
         <img src="/img/pic2.jpg" data-title="Another title" data-description="My <em>HTML</em> description">
     </div>
 
 If you want separate thumbnails (recommended), just add them as a link::
 
-    <div id="gallery">
+    <div id="galleria">
         <a href="/img/large1.jpg"><img src="/img/thumb1.jpg" data-title="My title" data-description="My description"></a>
         <a href="/img/large2.jpg"><img src="/img/thumb2.jpg" data-title="Another title" data-description="My <em>HTML</em> description"></a>
     </div>
 
 You may also add a separate larger image for fullscreen using the data-big attribute::
 
-    <div id="gallery">
+    <div id="galleria">
         <a href="/img/large1.jpg"><img src="/img/thumb1.jpg" data-big="/img/big1.jpg" data-title="My title" data-description="My description"></a>
         <a href="/img/large2.jpg"><img src="/img/thumb2.jpg" data-big="/img/big2.jpg" data-title="Another title" data-description="My <em>HTML</em> description"></a>
     </div>
 
 Adding video from YouTube, Vimeo or Dailymotion is easy - just link an image to the video page. If you want Galleria to fetch a thumbnail, add an element with the class 'video' instead of a thumbnail::
 
-    <div id="gallery">
+    <div id="galleria">
         <a href="http://www.youtube.com/watch?v=GCZrz8siv4Q"><img src="/img/thumb1.jpg"></a>
         <a href="http://vimeo.com/12309423"><span class="video">Watch this on Vimeo!</span></a>
     </div>
@@ -80,22 +80,27 @@ Use the Galleria.loadTheme and then the galleria() function on the selected jQue
 
     <script>
         Galleria.loadTheme('galleria/themes/classic/galleria.classic.min.js');
-        $('#gallery').galleria();
+        Galleria.run('#galleria');
     </script>
 
 
 Adding options
 ===============
 
-The galleria function takes one arguments, *options*. The options argument is
-an object with Galleria options that you can use, please visit :doc:`/options/index` for a complete list.
+Use the Galleria.confirgure function to apply options. You can define an object to apply
+multiple options, or two arguments (key/value) to apply a single option.
+Please visit :doc:`/options/index` for a complete list.
 
 Example options::
 
-        $('#gallery').galleria({
-            imageCrop: true,
-            transition: 'fade'
-        });
+    Galleria.configure({
+        imageCrop: true,
+        transition: 'fade'
+    });
+
+Configuring a single options::
+
+    Galleria.configure('imageCrop', true);
 
 
 Optimize Galleria
@@ -107,7 +112,8 @@ We strongly recommend you to read through :doc:`/references/optimize` to optimiz
 Using the API
 =============
 
-Further customizations can be done using the :doc:`/api/methods` and :doc:`/api/events`. You’ll have access to them using the Galleria.ready function::
+Further customizations can be done using the :doc:`/api/methods` and :doc:`/api/events`.
+You’ll have access to them using the Galleria.ready function::
 
     Galleria.ready(function(options) {
 
@@ -119,6 +125,12 @@ Further customizations can be done using the :doc:`/api/methods` and :doc:`/api/
         });
     });
 
+Another option if you just want to listen to events is using the Galleria.on() function:
+
+    Galleria.on('image', function(e) {
+        Galleria.log('Now viewing ' + e.imageTarget.src);
+    });
+
 You can also access the methods inside the jQuery.data object of the element you attached the gallery to, f.ex::
 
     $('#galleria').data('galleria').enterFullscreen();

docs/options/dataConfig.rst

@@ -38,7 +38,7 @@ Example on how to alter the extraction logic:
         <span class="desc">My picture</span>
     </div>
     <script>
-    $('#galleria').galleria({
+    Galleria.run('#galleria', {
         dataConfig: function(img) {
             // img is now the image element
             // the function should return an object with the new data
@@ -65,7 +65,7 @@ Example on how to add rich HTML captions:
         </div>
     </div>
     <script>
-    $('#galleria').galleria({
+    Galleria.run('#galleria', {
         dataConfig: function(img) {
             return {
                 title: $(img).next('h2').html(), // tell Galleria to use the h2 as title

docs/options/dataSelector.rst

@@ -25,7 +25,7 @@ Example::
     </div>
 
     <script>
-    $('#galleria').galleria({
+    Galleria.run('#galleria', {
         dataSelector: "a",
         dataConfig: function(a) {
             // a is now the anchor element

docs/options/dataSource.rst

@@ -18,11 +18,11 @@ Examples:
 ::
 
     // Galleria will look for images in '#galleria':
-    $('#galleria').galleria();
+    Galleria.run('#galleria');
 
     // Galleria will look for images in '#images'
     // but use '#galleria' as gallery container:
-    $('#galleria').galleria({dataSource: '#images'});
+    Galleria.run('#galleria', { dataSource: '#images' });
 
 .. highlight:: html
 
@@ -38,7 +38,7 @@ Using custom data Array:
         { image: "/path/to/myimage2.jpg" },
     ];
 
-    $('#gallery').galleria({
+    Galleria.run('#galleria', {
         dataSource: data,
     });
     </script>
@@ -55,7 +55,7 @@ Placing the Galleria gallery in a different place and keep the thumbnails:
         <a href="myimg2.jpg"><img src="mythumb2.jpg"></a>
     </div>
     <script>
-    $('#gallery').galleria({
+    Galleria.run('#galleria', {
         dataSource: "#source",
         keepSource: true // this prevents galleria from clearing the data source container
     });

docs/options/debug.rst

@@ -13,6 +13,6 @@ For deployment you can turn debug off to generate a more generic error message i
 
 Example::
 
-    $('#galleria').galleria({
+    Galleria.configure({
         debug: false // debug is now off for deployment
     });

docs/options/dummy.rst

@@ -10,6 +10,6 @@ Think of it as a 404 for Galleria.
 
 Example::
 
-    $('#galleria').galleria({
+    Galleria.configure({
         dummy: '/images/noimage.jpg'
     });

docs/options/extend.rst

@@ -19,12 +19,10 @@ Example on how to add a play link by extending the theme:
 
     <a id="play" href="#">Play</a>
     <script>
-        $('#galleria').galleria({
-            extend: function(options) {
-
+        Galleria.run('#galleria', {
+            extend: function() {
                 var gallery = this; // "this" is the gallery instance
                 $('#play').click(function() {
-
                     gallery.play(); // call the play method
                 });
             }