Added documentation on handling images.

docs/README.md

@@ -30,11 +30,12 @@ Finally it's a nerdy reference to the computer term "Bit Blits" commonly used in
 - [Computed properties](computed_properties.md)
 - [Watching for changes](watchers.md)
 - [Styling and positioning Elements](element_attributes.md)
+- [Displaying images](displaying_images.md)
+
 <!---
 - More complex logic in methods
 - Transitions
 - Implementing Custom components
 - Handling Text
-- Handling Images
 - Routing
 -->

docs/_sidebar.md

@@ -8,4 +8,5 @@
 - [Computed properties](computed_properties.md)
 - [Watching for changes](watchers.md)
 - [Styling and positioning Elements](element_attributes.md)
+- [Displaying images](displaying_images.md)
 

docs/displaying_images.md

@@ -0,0 +1,69 @@
+# Blits - Lightning 3 App Development Framework
+
+## Displaying Images
+
+
+Now that we've covered the basics of creating Elements, as well as styling and positioning them, it's time to move away from these boring rectangles and explore how you can incorporate _images_ into your App.
+
+In Blits is very easy to display an image. Simply add the `src` attribute to an Element, specifying the image's location.
+
+For local images, make sure to place them in the `public` folder (e.g., `public/assets/background.jpg` or `public/images/logo.png`) and refer to them with a _relative_ path (omitting the `public` folder as root).
+
+Remote images are also supported and can be linked directly (e.g., `http://mycdn.com/artists/jimi_hendrix/woodstock.jpg`).
+
+```xml
+<Element src="images/logo.png" w="100" h="80" />
+<Element src="http://mycdn.com/artists/jimi_hendrix/woodstock.jpg" w="1920" h="1080" />
+```
+
+### Sizing and Scaling
+
+Make sure to give your Element a width (`w` ) and a height (`h`) attribute. Blits will scale the image to fit these exact dimensions.
+
+For the best performance, it's important to keep your source images as small as possible. If you're displaying an image at `200px x 200px`, make sure the image is exactly that size or _smaller_. The latter option may lead to some quality loss.
+
+### Colorization
+
+You also have the option to _colorize_ an image on the fly. Just add a `color` attribute to the Element with a `src` attribute. You can use a single color, or apply a gradient. By default all Elements with a `src` attribute get the a solid white background, which corresponds with the actual colors of the image.
+
+```xml
+<Element
+  w="200"
+  h="300"
+  :src="$src"
+  color="{top: '#fff', bottom: '#000'}"
+/>
+```
+
+### Asynchronous Loading
+
+All images are loaded asynchronously (and can possibly fail to load), even those local to your App. Blits allows you to easily hook into the `loaded` and `error` events of image Elements.
+
+You can use this, for example, to only make something visible once an image is fully loaded. Or to display a fallback image when an remote image can't be retrieved.
+
+```xml
+<Element src="http://mycdn.com/lightning.jpg" @loaded="$revealPage" @error="$showFallback" />
+```
+
+> Note how events are prefixed with a `@` sign.
+
+Considering the template above, in the `methods` key of your Component configuration object, you would then do something like:
+
+```js
+{
+  //...
+  methods: {
+    revealPage(dimensions) {
+      this.$log.info('Image dimensions', dimensions.w, dimensions.h)
+      this.show = true
+    },
+    showFallback(error) {
+      this.$log.error('Image failed to load', error)
+      this.showBackupImage()
+    }
+  }
+}
+```
+
+The `loaded` event receives the images dimensions as it's argument and the `error` event receives an error message explaining the failure.
+