Installation

After uploading all the files that come with Fresco, include it below the latest 3.x release of jQuery:

<script type="text/javascript" src="http://code.jquery.com/jquery-3.1.1.min.js"></script>
<script type="text/javascript" src="/js/fresco/fresco.js"></script>
<link rel="stylesheet" type="text/css" href="/css/fresco/fresco.css"/>
Note: The downloads have an example folder demonstrating the installation.

Usage

The easiest way to use Fresco is by adding the class fresco to a link.

<a href="image.jpg" class="fresco">Show image</a>

The alternative is using the Javascript API. See the API documentation for more on it, this section will cover just the HTML approach.

Fresco.show('image.jpg');

A caption can be added by using the data-fresco-caption attribute:

<a href="image.jpg"
   class="fresco"
   data-fresco-caption="Caption below the image">Caption</a>

Options

Extra Options and Callbacks can be added using the data-fresco-options attribute.

<a href="image.jpg"
   class="fresco"
   data-fresco-caption="Caption on top of the image"
   data-fresco-options="ui: 'inside'">Caption on top</a>

Groups

Create groups by giving links a data-fresco-group attribute. Each group should have a unique name. Groups can contain multiple types of content, images can be mixed with Youtube videos for example:

<a href="image1.jpg"
   class="fresco"
   data-fresco-group="unique_name">Image 1</a>
<a href="image2.jpg"
   class="fresco"
   data-fresco-group="unique_name">Image 2</a>

Whenever links in a group share options repetition can be avoided by using the data-fresco-group-options attribute. It sets options for the entire group:

<a href="image1.jpg"
   class="fresco"
   data-fresco-group="shared_options"
   data-fresco-group-options="ui: 'inside'">This group</a>
<a href="image2.jpg"
   class="fresco"
   data-fresco-group="shared_options">has shared</a>
<a href="image3.jpg"
   class="fresco"
   data-fresco-group="shared_options">options</a>

User Interface Pro only

There are two types of user interface settings, outside and inside. outside is the default and will put user interface elements outside of the window.

data-fresco-group-options="ui: 'outside'"

The alternative is inside, it puts the elements inside the window:

data-fresco-group-options="ui: 'inside'"

On small screens Fresco will switch to an alternative UI mode to optimize use of the viewport. This mode uses the entire screen for navigation and doesn't close Fresco when clicking the overlay.

Note: Touch devices will always use ui: 'outside' no matter which ui option is selected.
Important: ui: 'outside' will be forced whenever a group contains more than images. The reason for this is that interaction with content like Youtube videos would be impossible if it had overlapping user interface elements.

Overflow Pro only

Overflow can be used to create a zoom-like effect. By default the overflow options is set to false, which resizes images to fit within the viewport. Using overflow true will allow overflow along the y-axis.

Here's a popular usecase of overflow combined with vertical thumbnails:

<a href="large_image_2.jpg"
   class="fresco"
   data-fresco-group='overflow-example'
   data-fresco-group-options="overflow: true, thumbnails: 'vertical', onClick: 'close'">Overflow</a>
<a href="large_image_2.jpg"
   class="fresco"
   data-fresco-group='overflow-example'>2</a>
Note: Overflow is not supported on touch based devices.

Thumbnails Pro only

Thumbnails are enabled by default and are automatically generated for images and Youtube videos. They can also be disabled by setting the thumbnails option to false:

data-fresco-group-options="thumbnails: false"

By default the thumbnails option is set to horizontal, the alternative is vertical:

data-fresco-group-options="thumbnails: 'vertical'"

Performance, best practices

To improve performance it's recommended to create your own thumbnails. This avoids having to load entire source images to generate them on the fly. Providing thumbnails using the thumbnail option speeds up load times and saves bandwidth, especially noticeable with groups containing large images.

<a href="image1.jpg"
   class="fresco"
   data-fresco-group="thumbnail-example"
   data-fresco-options="thumbnail: 'thumbnail1.jpg'"
>Generated Thumbnails</a>
<a href="image2.jpg"
   class="fresco"
   data-fresco-group="thumbnail-example"
   data-fresco-options="thumbnail: 'thumbnail2.jpg'"
>2</a>

Most backend frameworks have plugins to generate thumbnails on the fly (and cache them). Scripts like phpThumb and ImageMagick can also be used for this. It allows automatic thumbnail generation like this:

thumbnail: 'phpThumb.php?src=image1.jpg&w=240&h=240&zc=1'
Note: The thumbnail generated is set to 240x240px because the maximum dimensions of a thumbnail are 120x120px. Having double the size available will make sure the thumbnails look good on Retina displays.
Note: Thumbnails aren't used on touch based devices for performance reasons.

Media types

Fresco attempts to automatically detect the media type using the given url. The type can also be set to one of the following values using the data-fresco-type attribute: image, youtube or vimeo.

Image

Most of the time setting the type will not be required for images, it will be required in cases where Fresco cannot detect it based on the url:

<a href="/images/?id=1337" class="fresco" data-fresco-type="image">Image</a>

Youtube Pro only

Links to Youtube videos will be embedded using the Youtube <iframe> API.

<a href="http://www.youtube.com/watch?v=c0KYU2j0TM4" class="fresco">Youtube</a>

Options of the Youtube <iframe> API can be set using the youtube option, see YouTube Embedded Players and Player Parameters for all the available options. Setting the width and height option might also be desired:

<a href="http://www.youtube.com/watch?v=7gFwvozMHR4"
    class="fresco"
    data-fresco-options="
      width: 853,
      height: 480,
      youtube: { autoplay: 0 }
    ">Youtube - Dimensions and options</a>
Note: By default Youtube optimizes the quality setting based on video dimensions, even with hd: 1 set HD might not be enabled. Fresco can force HD quality onto videos if the Youtube Iframe API is included, this is optional and covered in the installation instructions.

Vimeo Pro only

Vimeo links are embedded using the Vimeo API:

<a href="http://vimeo.com/32071937" class="fresco">Vimeo</a>

Options of the Vimeo Player API can be set using the vimeo option. See Vimeo Player Embedding for all the available options:

<a href="http://vimeo.com/108057431"
   class="fresco"
   data-fresco-options="
     width: 853,
     height: 480,
     vimeo: { autoplay: 0 }
   ">Dimensions and options</a>
Note: Vimeo videos don't have a thumbnail by default, this can be set using the thumbnail option.

Javascript API Pro only

For more advanced use see the documentation on the Javascript API. All the demonstrations on this page can also be created using the Javascript API, you might even prefer it over the HTML approach.

Fresco.show([
  { url: 'image1.jpg', caption: 'Caption below the image' },
  { url: 'image2.jpg' },
  { url: 'http://www.youtube.com/watch?v=7gFwvozMHR4',
    options: {
      width: 853,
      height: 480
    }
  },
  { url: 'http://vimeo.com/36897783',
    options: {
      width: 853,
      height: 480,
      thumbnail: 'vimeo_thumbnail.jpg'
    }
  }
], {
  afterPosition: function(position) {
    alert('Moved to position: ' + position);
  }
});