finalizing 1.2

docs/index.rst

@@ -23,15 +23,6 @@ Themes
     themes/using_themes.rst
     themes/creating_a_theme.rst
 
-Plugins
-=======
-
-.. toctree::
-    :maxdepth: 1
-
-    plugin/flickr
-    plugin/history
-
 
 References
 ==========

docs/references/dom.rst

@@ -0,0 +1,91 @@
+**************
+DOM Structure
+**************
+Galleria builds a rich DOM structure for each Gallery. You can access them in
+the Theme API using ``this.get( ID )`` or ``this.$( IDs )``. Read more about
+DOM manipulation in the API Reference.
+
+
+List of elements
+================
+Here is a list of each element in the default Galleria DOM and their layout::
+
+    container
+        stage
+            images
+            loader
+            counter
+                current
+                total
+            image-nav
+                image-nav-right
+                image-nav-left
+        thumbnails-container
+            thumb-nav-left
+            thumbnails-list
+                thumbnails
+            thumb-nav-right
+        info
+            info-text
+                info-title
+                info-description
+                info-author
+        tooltip
+
+
+HTML structure
+==============
+The HTML structure is built with a ``galleria-`` prefix to all classes to
+ensure CSS encapsulation. The class ``.carousel`` is added to
+``thumbnails-container``  if a carousel is present. The ``.disabled`` class is
+added to ``thumb-nav-left`` and ``thumb-nav-right`` if you are at the end/start
+of the carousel.
+
+The HTML structure is built with a ``galleria-`` prefix to all classes to ensure CSS encapsulation.
+The class ``.carousel`` is added to ``thumbnails-container``  if a carousel is present.
+The ``.disabled`` class is added to ``thumb-nav-left`` and ``thumb-nav-right`` if you are at the end/start of the carousel.
+
+This presentation of the Galleria HTML structure is good to have when building CSS for your custom theme::
+
+    <div class="galleria-container">
+        <div class="galleria-stage">
+            <div class="galleria-images">
+                <div class="galleria-image">
+                    <img>
+                </div>
+                <div class="galleria-image">
+                    <img>
+                </div>
+            </div>
+            <div class="galleria-loader"></div>
+            <div class="galleria-counter">
+                <span class="current"></span>
+                <span class="total"></span>
+            </div>
+            <div class="galleria-image-nav">
+                <div class="galleria-image-right-nav"></div>
+                <div class="galleria-image-left-nav"></div>
+            </div>
+        </div>
+        <div class="galleria-thumbnails-container [ carousel ]">
+            <div class="galleria-thumb-nav-left [ disabled ]"></div>
+            <div class="galleria-thumbnails-list">
+                <div class="galleria-thumbnails">
+                    <div class="galleria-image">
+                        <img>
+                    </div>
+                    [...]
+                </div>
+            </div>
+            <div class="galleria-thumb-nav-right [ disabled ]"></div>
+        </div>
+        <div class="galleria-info">
+            <div class="galleria-info-text">
+                <div class="galleria-info-title"></div>
+                <div class="galleria-info-description"></div>
+                <div class="galleria-info-author"></div>
+            </div>
+        </div>
+        <div class="galleria-tooltip"></div>
+    </div>
+

docs/references/extending.rst

@@ -0,0 +1,111 @@
+.. highlight:: javascript
+
+******************
+Extending Galleria
+******************
+
+Once you fiddled around with the Galleria options and styles, you might come to
+a point when you want to do some more advanced customizations. Galleria makes
+this possible with a bunch of public methods and events that makes
+customization easy.
+
+There are several ways you can access the methods:
+
+- use the ``extend`` option
+
+- fetch the Galleria instance
+
+- create and/or modify an existing theme
+
+
+Using the extend option
+=======================
+
+The extend option is a function that gets called when the galleria is loaded,
+after the theme init. Use this option to extend an existing theme with custom
+functionality. Example::
+
+    $('#images').galleria({
+    
+        extend: function(options) {
+        
+            Galleria.log(this) // the gallery instance
+            Galleria.log(options) // the gallery options
+
+            // listen to when an image is shown
+            this.bind('image', function(e) {
+            
+                Galleria.log(e) // the event object may contain custom objects, in this case the main image
+                Galleria.log(e.imageTarget) // the current image
+
+                // lets make galleria open a lightbox when clicking the main image:
+                $(e.imageTarget).click(this.proxy(function() {
+                   this.openLightbox();
+                }));
+            });
+        }
+    });
+
+
+Fetching the Galleria instance
+==============================
+
+Another option for extending galleria is to fetch the instance from anywhere on
+your page. You can do that using the static ``Galleria.get( [index] )``
+function. If you only have one galleria gallery, ``Galleria.get(0)`` will
+return the first (and only) gallery. If you call ``.get`` without specifying an
+index, it will return an array with all galleries initiated. Example::
+
+    $('#images').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
+    });
+
+
+The ``this`` keyword
+====================
+In the Galleria extend option and theme init, the ``this`` keyword represents
+the Galleria instance per default. In jQuery, the ``this`` keyword often
+represents a HTML element and this might be confusing at first when mixing them
+together. You can always assign the ``this`` keyword to a local variable like
+so::
+
+    var gallery = this;
+
+and then use ``gallery`` as the Galleria instance if you feel confused. In the
+examples, we always use the ``this`` keyword.
+
+
+The ``.proxy`` method
+=====================
+In javascript closure the ``this`` keyword represents different things
+depending on the context. Often using jQuery, the ``this`` keyword will
+represent a HTML element or something else in the callback function. In order
+to bring the scope to any callback, Galleria comes with a proxy method that
+makes sure that the ``this`` keyword will stay as a reference to the galleria
+instance. Example::
+
+    $(this.get('stage')).click(function(e) {
+    
+        Galleria.log(this) // this is now the stage element
+        this.openLightbox(); // will not work anymore
+        
+    });
+
+
+Using the proxy method, we can maintain the ``this`` keyword inside the
+callback::
+
+    $(this.get('stage')).click(this.proxy(function(e) {
+    
+        Galleria.log(this) // this is now the galleria instance
+        Galleria.log(e.currentTarget) // in jQuery, e.currentTarget is the element that bound the event (same as this)
+        
+        this.openLightbox(); // works!
+        
+        $(e.currentTarget).addClass('newclass'); // newclass added to stage using jQuery
+    });
+

docs/references/faq.rst

@@ -0,0 +1,70 @@
+***
+FAQ
+***
+
+What browsers can I run Galleria in?
+------------------------------------
+
+**The short answer:** IE7+, FF3+, Opera 11+, Chrome 9+, Safar 4+ and Mobile Safari.
+
+**The long answer:** The Galleria core is not very browser dependent. We use regular, linted JavaScript for most of our API and jQuery to even out browser differences in the DOM. However, themes might have different support tables, and sometimes they use progressive enhancement for visual details. All themes made by Galleria supports IE7+, Opera 11, Firefox 3+, Chrome 9+, Safari 4+ and Mobile Safari (iPad, iPhone, Android etc). IE6 is not supported by any theme at this point, but Galleria itself supports it so you can patch a theme yourself if you need IE6 compliance (we don’t really see the point though).
+
+
+Wait a minute, what’s up with all the ”Buy now” stuff? I thought Galleria was free?
+-----------------------------------------------------------------------------------
+
+Galleria and two themes are released under the MIT license and is completely free to use and abuse. We like to keep it that way. However, nobody wants to see Galleria become yet another JavaScript component that drops out after the first beta, like so many jQuery-related products do. But in order to establish continuous growth and progress, we need fundings. Donations are always welcome, but unfortunately not enough to keep things running for us.
+
+So the business model we decided to take was to keep Galleria 100% free but also develop Premium Themes and add-ons that we release under a commercial license. These themes are available for purchase on our site and they probably cost less than half of your hourly consulting fee rate. Purchasing themes is a great way to support the project and at the same time increase your portfolio of web design components.
+
+
+I get a "Fatal Error" when I run Galleria
+-----------------------------------------
+
+Galleria throws errors when something is not right. Some errors are considered critical for Galleria to run properly, and when they occur Galleria stops and throws a "Fatal Error". The most common reason is that Galleria needs a width and height to function. It tries to extract the measures from your CSS styles, but if it fails you will get a "Fatal Error: width & height not found", or something similar. So the first thing you can try is to pass width and height to galleria, like this::
+
+    $('#gallery').galleria({
+        width: 800,
+        height: 500
+    });
+    
+If that doesn’t help, please refer to the documentation and support sections of this site to debug further.
+
+
+The gallery does not work, instead I get a big list of images
+-------------------------------------------------------------
+
+This is probably because Galleria never gets initialized. Please make sure you are:
+
+* targeting the correct element selector when calling Galleria
+* including jQuery in your document
+* including Galleria and not getting any error messages
+* calling Galleria after the images in the HTML source
+
+
+Do you do custom themes for a fee?
+----------------------------------
+
+At the moment, not really. But you are welcome to throw us a request and we’ll see what we can do. It helps if you include your budget and design mockups / feature specs when contacting us.
+
+
+Galleria runs much smoother in Chrome than in IE
+------------------------------------------------
+
+Being JavaScript based, the user experience can vary depending on browser and OS environment. Chrome is generally a really good browser with a fast JavaScript rendering engine, while IE and FF can be slower. We did optimize the product to work at it’s best in all environments, but the result can vary slightly.
+
+
+What mobile strategy does Galleria have?
+----------------------------------------
+
+We do not currently develop specific themes for mobile devices since we have not yet seen a good web app for flicking through images that comes anywhere near the native experience. Instead, we focus on mobile compatibility in a web site context, meaning that the Galleria gallery works on mobile devices much the same way as they do on the desktop web. We also optimize our themes so the interaction is more precise when displayed on touch devices.
+
+This direction might change very soon since there is a lot of things happening on the mobile web in a fast pace.
+
+
+Can I use HTML captions?
+------------------------
+
+Yes you can. In our examples, we extract captions from the ``title`` and ``alt`` attribute by default, but you can configure your gallery to fetch data from anywhere else using the ``dataConfig`` option. See the docs for more info and examples.
+
+

docs/references/optimize.rst

@@ -0,0 +1,40 @@
+*******************
+Optimizing Galleria
+*******************
+
+One of the goals with Galleria is to simplify the process of creating beautiful image galleries on the web. We did that; setting up a gallery is really easy and most of the times it ”just works” with almost any images. However, there are some things you can do to make the Gallery run even smoother, especially when deploying.
+
+1. Use reasonably sized images
+------------------------------
+
+The biggest performance lag comes from using really large images and letting Galleria scale them down for you. This might work OK in your local environment, but it can have great effects for users with less optimized setups. Always scale down your images to a reasonable size and use jpg for compression. A good standard to start with is 1000px x 1000px using 70 as quality.
+
+
+2. Use separate thumbnails
+--------------------------
+
+Galleria can create thumbnails for you. This is great for setting up a Gallery and trying out different themes without having to manually scale images. But when deploying, you will always get the best result if you scale your images to a size that is close to the display size, either manually or using server-side scripting. This is especially true for thumbnails. If you let Galleria create thumbnails, it will load all full-sized images at once. If you use separate thumbnails, it will load them first and then just load the big image when needed. This can improve the overall user experience.
+
+You can define separate thumbnails by linking a thumbnail to the big image in the HTML source or using a plain JSON object as gallery data. See the Quick Guide for more info and examples.
+
+
+3. Don’t add too many images at once
+------------------------------------
+
+There are no limits to how many images you can add, but after 30 it can clog the pipes on load, especially in IE. Use a reasonable amount of images at first, then try the ``.load()``, ``.splice()`` and ``.push()`` methods to add/remove image data on the fly.
+
+
+4. Include your theme js in the head
+------------------------------------
+
+We generally recommend you to use the ``Galleria.loadTheme`` method to load themes because it’s really convenient and makes it easier to switch themes. However, you might get a snappier result if you include the theme javascript in the head tag, especially if it’s minified together with the rest of your scripts.
+
+You can also add the theme CSS file as a ``<link>`` tag to make it load faster. Just make sure you give it the id 'galleria-theme'.
+
+
+5. Use JSON as data
+-------------------
+
+This can also be a small speed-booster, but can also be negative from a progressive enhancement point of view. If you use JSON, make sure you serve a reasonable fallback for users without JavaScript turned on. Read more in the Quick Guide for more examples.
+
+