Illustrated 2.0
Behavior for Yii2 ActiveRecord
, (*1)
Illustrated 2.0 is a Behavior for the Yii2 framework that
makes any ActiveRecord, well, illustrated.
It links the ActiveRecord to one or more image files. The images
have strict proportions, allowing for a clean layout of views
and other pages. The images may be saved in several resolutions., (*2)
The Illustrated 2.0 behavior co-operates with the
enclosed CropperWidget widget. This lets the user crop the image,
before uploading it to the server., (*3)
Here is a demo of the Illustrated 2.0 behavior and its
associated CropperWidget., (*4)
Note that the current version (2.0.0) is changed considerably
from previous versions. It should be far easier to use. Please
consult this document carefully., (*5)
Installation
Install Illustrated 2.0 with Composer. Either add the
following to the require section of your composer.json file:, (*6)
"sjaakp/yii2-illustrated-behavior": "*"
Or run:, (*7)
composer require sjaakp/yii2-illustrated-behavior "*"
You can manually install Illustrated 2.0
by downloading the source in ZIP-format., (*8)
Note that Illustrated 2.0 needs PHP version 8.1 or later., (*9)
Usage of Illustrated
Illustrated 2.0 is used like any Behavior of an
ActiveRecord. The code should look something like this:, (*10)
<?php
use sjaakp\illustrated\Illustrated;
class <model> extends \yii\db\ActiveRecord {
...
public function behaviors(){
return [
[
"class" => Illustrated::class,
"attributes" => [
"picture" => [ // attribute name of the illustration
... // options for 'picture'
],
... // other illustrations
],
... // other Illustrated options
],
... // other behaviors
];
}
...
}
An ActiveRecord with Illustrated 2.0 behavior can have one or more
illustrations., (*11)
Each illustration has it's own, fixed proportions, so that views of
the ActiveRecord will have a consistent layout., (*12)
Each illustration is associated with one attribute in the ActiveRecord
and a corresponding field in the database table. This attribute stores
the filename of the uploaded image. Illustrated 2.0 uses its own
naming scheme. An uploaded image file name is never longer than eleven
characters., (*13)
In its basic operation, Illustrated 2.0 stores one version of the
uploaded file for each illustration. However, it is possible to make
it store several versions, with different resolutions. This is perfect
for responsive images
More information here., (*14)
CropperWidget is an input widget. It is intended
to upload an illustration. It can be used in an ActiveForm
like this:, (*15)
use sjaakp\illustrated\CropperWidget;
<?php $form = ActiveForm::begin([
'options' => ['enctype' => 'multipart/form-data'] // important, needed for file upload
]); ?>
... // other form fields
<?= $form->field($model, 'picture')->widget(CropperWidget::class, [
... // CropperWidget options
]) ?>
...
<?= Html::submitButton('Submit') ?>
<?php ActiveForm::end(); ?>
CropperWidget displays a control for file upload combined with controls to
crop and rotate the image. It is based on
my Cropper 2.0 JavaScript
widget., (*16)
Note that the ActiveForm must have the option 'enctype' set
to 'multipart/form-data'., (*17)
By far the most important option of CropperWidget is aspect. This
sets the aspect ratio of the cropped immage., (*18)
It can be set to one one of the following strings:, (*19)
-
'tower' equivalent to 0.429, 9:21
-
'high' equivalent to 0.563, 9:16
-
'phi_portrait' equivalent to 0.618, 1:φ, golden ratio
-
'din_portrait' equivalent to 0.707, 1:√2, DIN/ISO 216 paper sizes
-
'portrait' equivalent to 0.75, 3:4
-
'square' equivalent to 1.0, 1:1
-
'landscape' equivalent to 1.333, 4:3
-
'din_landscape' equivalent to 1.414, √2:1
-
'phi_landscape' equivalent to 1.618, φ:1
-
'wide' equivalent to 1.718, 16:9
-
'cinema' equivalent to 2.333, 21:9
Alternatively, you can set aspect to a float between 0.2 and 5.0., (*20)
CropperWidget has some other options too. Please refer tot the documentation
for Cropper 2.0, (*21)
Example
To set the aspect ratio to 'portrait' (0.75) one would use:, (*22)
use sjaakp\illustrated\CropperWidget;
<?php $form = ActiveForm::begin([
'options' => ['enctype' => 'multipart/form-data']
]); ?>
...
<?= $form->field($model, 'picture')->widget(CropperWidget::class, [
'aspect' => 'portrait'
]) ?>
...
<?php ActiveForm::end(); ?>
Illustrated 2.0 functions
These functions become methods of the ActiveRecord that owns
the Illustrated 2.0 Behavior., (*23)
getImgHtml()
function getImgHtml( $attribute, $options = [] ), (*24)
Gets a complete HTML <img> element of the uploaded and cropped
illustration. If cropWidth is set and cropSteps is greater
than zero, a srcset is included., (*25)
Note that for srcset to be effective, you have to set the
sizes value in $options. For details,
see here., (*26)
-
attribute: the attribute name of the illustration.
-
options: HTML options of the img tag. See yii\helpers\Html::img.
Default: [] (empty array).
The easiest way to display the illustration stored in the attribute 'picture' in a view is:, (*27)
...
<?= $model->getImgHtml('picture') ?>
...
getSrc()
function getSrc( $attribute, $step = 0 ), (*28)
Gets the source URL of (one of the variants of) the uploaded and
cropped illustration. Returns null if not available., (*29)
-
attribute: the attribute name of the illustration.
-
step: the 'step', or variant, of the illustration, 0 being the greatest.
To get the smallest variant (useful for thumbnails), set step to -1.
getSrcSet()
function getSrcSet( $attribute ), (*30)
Gets the srcset of the uploaded and cropped illustration.
Returns "" if cropWidth is not set., (*31)
-
attribute: the attribute name of the illustration.
deleteFiles()
function deleteFiles( $attribute ), (*32)
Deletes the image file(s) and clears attribute., (*33)
-
attribute: the attribute name of the illustration.
Illustrated 2.0 options
attributes
array List of illustration properties key => value., (*34)
Array member key is the name of the attribute that stores the file name of the resulting cropped image., (*35)
value is an array with the following properties (all are optional):, (*36)
-
cropWidth:
int - Width of the cropped image, in pixels.
- If not set, the cropped image is saved with the maximum
possible resolution and filesize.
-
cropSteps:
int - Number of size variants of the cropped image.
Each variant has half the width of the previous one.
- Example: if
cropWidth = 1280, and cropSteps = 5, variants
will be saved with widths 1280, 640, 320, 160, and 80 pixels, each
in it's own subdirectory.
- If
cropSteps = 0 or is not set, only one cropped image is saved,
with width cropWidth.
- If
cropWidth is not set, cropSteps is ignored.
-
rejectTooSmall:
bool - If true, images which are too small
to crop are rejected.
If not set, true is assumed; small images will be rejected.
mime
MIME type of saved, cropped image(s). If null, cropped images will be
saved with the same MIME type as the original. Default: 'image/avif'.
AVIF is a recent (2019) image file format
which is in many ways superior to JPEG. It is supported by all modern browsers., (*37)
directory
Directory (or alias) where cropped images are saved., (*38)
If null (default), the directory will be '@webroot/<$illustrationDirectory>/<table name>',
where <table name> is the table name of the ActiveRecord., (*39)
baseUrl
URL (or alias) where cropped images reside., (*40)
If null (default), the URL will be '@web/<$illustrationDirectory>/<table name>',
where <table name> is the table name of the ActiveRecord., (*41)
illustrationDirectory
Name of subdirectory under '@webroot' where cropped images are stored.
Default: 'illustrations'. If directory is anything else than null,
illustrationDirectory is ignored, (*42)
noImage
HTML returned if no image is available, i.e.
$imgAttribute is empty. Default: '' (empty text)., (*43)
fileValidation
Array with extra parameters for the validation of the file attribute.
By default, only the file types and the number of files are tested., (*44)
You may add things like maximum file size here.
See FileValidator.
Default: [] (empty array)., (*45)
tooSmallError
Error message template for images that are too small to crop.
Parameters: original file name, width, and height.
Default: 'Image "%s" is too small (%d×%d).'., (*46)
uploadError
Error message template for upload errors.
Parameter: error number. See here.
Default: 'Upload Error %d.'., (*47)
options
Client options such as aspect for the Cropper 2.0 control.
See Cropper documentation., (*48)
translations
Optional translations for the Cropper 2.0 control.
See Cropper documentation., (*49)
FAQ
Why am I getting an error like 'Trying to get property of non-object'?, (*50)
- You probably didn't give the form the option
'enctype' => 'multipart/form-data'.
Why can't I change the cropping of an illustration if I try to
update an illustrated document?, (*51)
- This is by design. 'Recropping' an already cropped image is discouraged.
You might reload the original image.
Wallogit.com
