# TinySrc Helper

## Overview

tinysrc.net provides an API for automatic scaling and image format conversion for use with mobile devices. The API is quite simple: you simply create a standard HTML image tag, but append your image URL to a URL on the tinysrc.net domain:

    <img src="http://i.tinysrc.net/http://yourdomain.com/images/foo.jpg" />

Their service then sizes the image appropriately for the device requesting it.

You can control a number of aspects regarding image display, including:

- Image dimensions. You may specify a width and optional height. These dimensions can be in absolute pixels, or use one of the adaptive mechanisms tinysrc.net offers. One is subtractive; prepending a dimension with a minus ("-") indicates that the image should fill the maximum physical dimensions, minus the value given in pixels. The other is percentage based; prepending a dimension with an "x" tells the service to size that dimension by that percentage -- e.g., "x20" indicates "20%".

- Image format. By default, tinysrc.net autodiscovers the format. Internally, it supports only JPEG or PNG, and autoconverts GIF to PNG. You can specifically request that it should convert an image to either PNG or JPEG, however.

The `TinySrc` view helper provides functionality around the tinysrc.net API, and gives you the ability to:

- selectively enable or disable whether it returns just the tinysrc.net URL or a fully-populated HTML img tag (enabled by default);

- specify default values for image format as well as width and height;

- specify a default value for the base URL used (uses the BaseUrl view helper by default);

- override the default options on a per-image basis, via passed in options.

## Quick Start

The most basic usage is simply to pass the path to an image, relative to your document root or base URL, to create the appropriate image tag:

    <?php echo $this->tinySrc('/images/foo.png'); ?>

You may specify default values for the base URL, conversion format, dimensions, and whether or not to create an img tag by default:

    <?php $this->tinySrc()
               ->setBaseUrl('http://example.com/foo/')
               ->setCreateTag(false)                // disable tag creation
               ->setDefaultFormat('png')            // convert images to PNG
               ->setDefaultDimensions('-5', 'x20'); // width should be 5 less than screen width;
                                                    // height should be 20% of total screen height
    ?>

Finally, you can also pass in values as an array of options, passed as the second parameter:

    <?php echo $this->tinySrc('/images/foo.png', array(
        'format' => 'jpg', // convert to JPEG
        'width'  => 'x50', // 1/2 screen width
    ); ?>

## Configuration Options

### TinySrc Helper Options

The following options may be passed to the `$options` (second) argument of the helper.

base_url

  The base URL, including scheme, host, and optionally port and/or path; this value will be prepended to the image path provided in the first argument. By default, this uses the `BaseUrl` and `ServerUrl` view helpers to determine the value.

create_tag

  A boolean value indicating whether or not the helper should return an HTML img tag, or simply the tinysrc.net URL. By default, this flag is enabled.

format

  Should be one of the values "png" or "jpeg". If specified, this value will be used to indicate the image conversion format. If not specified, the default format will be used, or the format will be auto-determined based on the image itself.

width

  This should be either `null`, or an integer (optionally prefixed by "x" or "-"). If specified, this value will be used to determine the converted image width. If null, neither a width nor a height value will be used. If not specified, the default dimensions will be used.

height

  This should be either `null`, or an integer (optionally prefixed by "x" or "-"). If specified, this value will be used to determine the converted image height. If null, no height value will be used. If not specified, the default height will be used.

Any other options provided will be used as attributes to the HTML img tag (if created).

## Available Methods

`tinySrc` $image = null, array $options = array()

  Called with no arguments, returns the helper instance. This is useful for configuring the helper.

  If the `$image` argument is provided, it will either create and return the tinysrc.net URL for the image, or an image tag containing that URL as the source, depending on the status of the "create tag" flag (either the default value, or the value passed via `$options`).

  See the configuration section for details on the `$options` array.

`setBaseUrl` $url

  Use this method to manually specify the base URL to prepend to the `$image` argument of the `tinySrc()` method.

`getBaseUrl`

  Retrieve the base URL for prepending to image URLs. By default, autodiscovers this from the `BaseUrl` and `ServerUrl` view helpers.

`setDefaultFormat` $format = null

  Specifiy the default image conversion format. If none provided, the value is cleared. Otherwise, expects either "png" or "jpeg".

`setDefaultDimensions` $width = null, $height = null

  Set the default dimensions for image conversion. If no `$width` is specified, an empty value is provided for all dimensions (setting the height requires a width as well). Passing no value for the height will set only a width. Dimensions should be specified as either pixel dimensions, or:

  - A pixel value, preceded by a "-" sign. This will indicate the width should take the entire screen size, minus the number of pixels specified.

  - A percentage of the total screen dimensions, expressed as "x" followed by the percentage: "x20" is equivalent to 20%.

`setCreateTag` $flag

  Indicate whether the `tinySrc()` method should create an HTML image tag. If boolean `false`, only a tinysrc.net URL will be returned.

`createTag`

  Returns the status of the "create tag" flag.

## Examples

### Returning only a tinysrc.net URL

You may want to return only a tinysrc.net URL. To do this, you have two options: make this the default behavior, or specify in your `$options` not to create a tag.

    // Specifying default behavior:
    $this->tinySrc()->setCreateTag(false);
    echo $this->tinySrc('image.jpg');

    // Per-image:
    echo $this->tinySrc('image.jpg', array('create_tag' => false));