Getting Started

# System Requirements

# General requirements

  • ExpressionEngine 3.5.0 or greater
  • PHP 5.4.0 or newer compiled with GD (or GD 2) library
    • ImageMagick is also supported if installed
  • MySQL 5.5.3 or newer
  • At least 256 megabytes of memory allocated and available to PHP
    • 512 megabytes is recommended (and more if you can spare it). Manipulating images can take a lot of memory. And particularly, the larger image, the more memory it will take.

# Control panel interface and entry field type use requirements

  • Internet Explorer 11 or greater
  • Chrome (tested on version 55)
  • Firefox (tested on version 50)
  • Safari (Mac) (tested on version 10)

# Image optimization requirements

Ansel will also utilize various image optimization libraries if they are installed on the server and your PHP version is high enough. Here are the requirements for image optimization:

  • PHP 5.5 or greater
  • jpegoptim for jpeg optimization
  • gifsicle for gif optimization
  • optipng for PNG optimization

# Installing Or Updating

Installing and updating Ansel is very easy.

  • Download the Ansel zip file and unzip it
  • Copy system/user/addons/ansel to the same directory location in your EE instance
    • If you are updating, replace the existing ansel directory
  • Copy themes/user/ansel to the same directory location in your EE instance
    • If you are updating, replace the existing ansel directory
  • Log in to your EE control panel and navigate to the Add-on Manager
  • Scroll down to the “Third Party” section, locate “Ansel” in the list and click “Install” or “Update”

Ansel is now installed or updated.


# Configuring

Ansel has a few settings you may want to look at before diving in to making your Ansel fields.

Ansel Global Settings
Ansel for ExpressionEngine Settings

# License Key

The first thing you will want to do is visit the License page and enter your license key from your purchase.

The license page can by located by clicking on “Ansel” from the list of Add-ons in the Add-on Manager, then clicking on the “License” link in the sidebar.

Remember

You will need a license for each of the sites/public domain names you install Ansel on.

# Global Settings

Ansel has a number of other global settings you may wish to take advantage of. To access them, click on “Ansel” from the list of Add-ons in the Add-on Manager.

Note

The following settings have config file overrides which you can use to keep your config in your config file.

# Default host

This field is blank on new installs. If you wish all image URLs to be served from a CDN (for instance), you can enter a fully qualified URL here.

The config override item is $config['ansel']['default_host'].

# Hide the Upload/Save directory instructions when setting up a new field?

Hide the instructions for how to use the Upload/Save directory settings when setting up/editing Ansel fields.

The config override item is $config['ansel']['hide_source_save_instructions'] = true;.

# Default maximum quantity

Use this to set a default value for maximum quantity when creating new fields.

The config override item is $config['ansel']['default_max_qty'].

# Default image quality

Use this to set a default value for the image quality setting when creating new fields.

The config override item is $config['ansel']['default_image_quality'].

# Default force JPG setting

Use this to set newly created fields to default to forcing JPG.

The config override item is $config['ansel']['default_jpg'].

# Default retina mode

Use this to set newly created fields to default to retina mode.

The config override item is $config['ansel']['default_retina'].

# Default display title field

Use this to set newly created fields to default to show the title field.

The config override item is $config['ansel']['default_show_title'].

# Default require title

Use this to set newly created fields to default to require the title field.

The config override item is $config['ansel']['default_require_title'].

# Default customize title label

Use this to set newly created fields to have a default value for the title label.

The config override item is $config['ansel']['default_title_label'].

# Default display caption field

Use this to set newly created fields to default to show the caption field.

The config override item is $config['ansel']['default_show_caption'].

# Default require caption

Use this to set newly created fields to default to require the caption field.

The config override item is $config['ansel']['default_require_caption'].

# Default customize caption label

Use this to set newly created fields to have a default value for the caption label.

The config override item is $config['ansel']['default_caption_label'].

# Default display cover field

Use this to set newly created fields to default to show the cover field.

The config override item is $config['ansel']['default_show_cover'].

# Default require cover

Use this to set newly created fields to default to require the cover field.

The config override item is $config['ansel']['default_require_cover'].

# Default customize cover label

Use this to set newly created fields to have a default value for the cover label.

The config override item is $config['ansel']['default_cover_label'].

# Config file only options

There are a couple of configuration options that can only be set in the config file.

# optimizerShowErrors

Normally the optimizer for jpegoptim, gifsicle, and optipng will fail silently. However, it can sometimes be useful to know if something is going wrong — for instance, when you install the tools on your server and want to make sure they are working. If the optimizer is not able to find the tools or they return an error code when trying to optimize the image, when this config setting is set to true, the optimizer will throw an error for you to see.

$config['ansel']['optimizerShowErrors'] = true;

# disableOptipng

Disables optipng optimization.

$config['ansel']['disableOptipng'] = true;

# disableJpegoptim

Disables jpegoptim optimization.

$config['ansel']['disableJpegoptim'] = true;

# disableGifsicle

Disables gifsicle optimization.

$config['ansel']['disableGifsicle'] = true;

# forceGD

Forces Ansel to use GD image processing for manipulating images. Normally, Ansel will auto-detect if ImageMagick is installed/setup with PHP and use it for manipulating images. If for whatever reason you would like to force Ansel to use GD even though ImageMagick is available, make this setting true.

$config['ansel']['forceGD'] = true;