Merge pull request #24 from ironland/image-helper

Add readme for image helper

Author: Nomafin

README.md

@@ -389,6 +389,11 @@ Example:
 {@content data=fields.some_content.value /}
 ```
 
+### image
+
+The `image` helper returns a markup for `img` tags with proper `srcset` and `sizes` attributes for responsive use. The full readme for the helper can be found [here](docs/helpers/image.md).
+
+
 ### menu
 
 `menu` helper does what it name suggests: it creates a menu. It has several parameters that are explained below:
@@ -655,7 +660,7 @@ public function Query() {
 
     // This returns a WP_Query like object.
     // Queried posts are accessible in dust by typing 'Query.posts'.
-    return \DustPress\Query::get_posts( $args );   
+    return \DustPress\Query::get_posts( $args );
 }
 ```
 

docs/helpers/image.md

@@ -0,0 +1,58 @@
+### Image
+
+The `image` helper returns a markup for `img` tags with proper `srcset` and `sizes` attributes for responsive use. 
+
+You can either give the helper the ID of an image uploaded to WordPress or alternatively use a completely custom URL as the source. 
+
+#### An image from WP
+
+When using the helper with an `image ID`, no additional parameters are needed but can be given optionally. The helper fetches the image url from the database and constructs the srcset from the specified WP image sizes. 
+
+``` {@image id=image.id /} ```
+
+By default it constructs the same `sizes` attribute for the image as in WP default behaviour. You can also give a custom `sizes` parameter when using the helper with a WP image ID, so that the default WP sizes attribute construction is overriden.
+
+``` {@image id=image.id sizes=Settings.mainImage.sizes /} ```
+
+#### An image from a custom src
+
+When using the helper with a custom src url, you also have to provide the `srcset` and the `sizes` so that the helper is able to produce the responsive HTML markup.
+
+``` {@image src=Settings.mainImage.src srcset=Settings.mainImage.srcset sizes=Settings.mainImage.sizes /} ```
+
+#### The class and alt parameters
+
+With any use case of the helper, you can always optionally provide the `class` and `alt` parameters and they will be added to the returned markup. 
+
+If you don't provide the alt parameter when using the helper with an image id, it tries to use the alt attribute given to the image when it was uploaded to WordPress. This attribute might be empty in most cases though, so remember to check the final markup for accessibility purposes. 
+
+``` {@image id=image.id class="myclass" alt="An alternative text" /} ```
+
+#### A settings model
+
+We recommend using a separate settings model in your DustPress installation for easily defining custom settings for images. This model can be bound to chosen models or even to the middle model which is extended by page and post models. 
+
+The custom image settings for different images in your web site layout can then be easily acquired for use in the templates.
+
+```
+<?php
+
+class Settings extends \DustPress\Model {
+
+    public function imageSettings() {
+        return [
+            'mainImage' => [
+                'sizes'  => [
+                    '(min-width: 1280px) 100vw',                    						'(min-width: 768px) 50vw',
+                    '100vw',
+                ],
+                'src' => 'https://image.com/example.jpg',
+                'srcset' => [
+                    'https://image.com/example-300.jpg 300w',
+                    'https://image.com/example-768.jpg 768w',
+                    'https://image.com/example-1024.jpg 1024w',                    
+                ],
+            ],
+        ];
+    }
+}