Skip to content

README.md

Latest commit

 

History

History
99 lines (66 loc) · 3.77 KB

README.md

File metadata and controls

99 lines (66 loc) · 3.77 KB
Raw
description This module brings file management and image manipulation to Nails. Can be configured to use the local filesystem, or remote services for truly distributed content.

CDN

The CDN module provides a unified interface for storing user generated content (i.e files), known as objects. Objects are organised in buckets.

Objects can be uploaded via the CDN Service, or via the API.

Objects

Objects are synonomous with files in a traditional file system. They represent binary data which is stored in the CDN. Objects have meta data attached to them such as a title, mime type, file size etc.

Buckets

Buckets can be though of as simialr to a folder in a traditional file system, they contain objects. They can only be one level deep, however: buckets cannot be nested and have no hierarchy.

Drivers

Data storage is controlled through the use of drivers. Drivers allow the developer to leverage local storage, as well as storage as a service systems like S3, or Google Cloud Storage

{% content-ref url="drivers/" %} drivers {% endcontent-ref %}

{% hint style="info" %} All official drivers allow the end URL to be specified so that edges like CloudFront can be used to serve assets, {% endhint %}

CDN Service

Upload, delete, and fetch CDN objects and buckets using the CDN Service.

{% content-ref url="cdn-service.md" %} cdn-service.md {% endcontent-ref %}

API

The CDN module exposes various API endpoints for querying the CDN and for uploading files.

{% content-ref url="api/" %} api {% endcontent-ref %}

Image Transformation

Simple image transformations can be made via the CDN module.

{% content-ref url="image-transformation.md" %} image-transformation.md {% endcontent-ref %}

Console

The CDN module provides some utility console commands for managing objects from the command line.

{% content-ref url="console.md" %} console.md {% endcontent-ref %}

Housekeeping

CDN ships routines that expire tokens and empty old trash. See Housekeeping.

CMS widget

The CDN module supplies a CMS widget with the slug image (class Nails\Cdn\Cms\Widget\Image). It appears in the widget editor alongside the widgets shipped by the CMS module. How widgets are discovered and how DISABLED, HIDDEN, and DEPRECATED behave is covered in CMS widgets.

The editor asks for a CDN object (iImageId) and then:

Field Values
sScaling NONE (native size), CROP, or SCALE
sSize A widthxheight pair drawn from the app's permitted image dimensions. The widget renders only when this is set. NONE still serves the original; crop and scale use the pair.
sLinking NONE, FULLSIZE (the original object), or CUSTOM
sUrl Used when linking is CUSTOM
sTarget Empty, _blank, or _parent
sImgAlt, sImgTitle alt and title on the <img>
sImgAttr, sLinkAttr Extra attributes on the image and the link

Crop and scale call cdnCrop() and cdnScale(). NONE calls cdnServe(). The markup is wrapped in .cms-widget-image. A missing object, or a size the driver rejects, renders nothing.

Older saves used different keys. The widget still reads image_id, scaling, size, url, target, img_attr, and link_attr, and it maps a legacy width and height onto sSize when that pair is one of the permitted dimensions.

The widget implements Nails\Cms\Interfaces\Monitor\Cdn\Widget and reports iImageId, so CDN usage monitoring can find the object inside widget data.

<?=cmsWidget('image', [
    'iImageId' => 42,
    'sScaling' => 'CROP',
    'sSize'    => '1200x630',
    'sImgAlt'  => 'Harbour at dusk',
])?>