diff --git a/ajax-introduction.md b/ajax-introduction.md index 0d5b1f41..cd6119e8 100644 --- a/ajax-introduction.md +++ b/ajax-introduction.md @@ -17,7 +17,7 @@ The AJAX framework comes in two flavors, you may either use [the JavaScript API] The AJAX framework is optional in your [CMS theme](../cms/themes), to use the library you should include it by placing the `{% framework %}` tag anywhere inside your [page](../cms/pages) or [layout](../cms/layouts). This adds a reference to the October front-end JavaScript library. The library requires jQuery so it should be loaded first, for example: - + {% framework %} diff --git a/backend-lists.md b/backend-lists.md index 4d18d28e..a79e90a1 100644 --- a/backend-lists.md +++ b/backend-lists.md @@ -187,6 +187,7 @@ There are various column types that can be used for the **type** setting, these
- [Text](#column-text) +- [Image](#column-image) - [Number](#column-number) - [Switch](#column-switch) - [Date & Time](#column-datetime) @@ -216,6 +217,22 @@ You can also specify a custom text format, for example **Admin:Full Name (active type: text format: Admin:%s (active) + +### Image + +`image` - displays an image using the built in [image resizing functionality](../services/image-resizing#resize-sources). + + avatar: + label: Avatar + type: image + sortable: false + width: 150 + height: 150 + options: + quality: 80 + +See the [image resizing docs](../services/image-resizing#resize-sources) for more information on what image sources are supported and what [options](../services/image-resizing#resize-parameters) are supported + ### Number @@ -806,7 +823,7 @@ You can extend the filter scopes of another controller from outside by calling t Categories::extendListFilterScopes(function($filter) { // Add custom CSS classes to the Filter widget itself $filter->cssClasses = array_merge($filter->cssClasses, ['my', 'array', 'of', 'classes']); - + $filter->addScopes([ 'my_scope' => [ 'label' => 'My Filter Scope' diff --git a/config/toc-docs.yaml b/config/toc-docs.yaml index ec1be995..f784f145 100644 --- a/config/toc-docs.yaml +++ b/config/toc-docs.yaml @@ -81,6 +81,7 @@ Services: services/error-log: "Errors & Logging" services/events: "Events" services/html: "Forms & Html" + services/image-resizing: "Image Resizing" services/filesystem-cdn: "Filesystem / CDN" services/hashing-encryption: "Hashing & Encryption" services/helpers: "Helpers" diff --git a/config/toc-markup.yaml b/config/toc-markup.yaml index 077515cb..ea3bdda6 100644 --- a/config/toc-markup.yaml +++ b/config/toc-markup.yaml @@ -34,13 +34,16 @@ Filters: icon: "icon-quote-right" itemClass: "code-item" pages: - markup/filter-app: "|app" - markup/filter-page: "|page" - markup/filter-theme: "|theme" - markup/filter-media: "|media" - markup/filter-md: "|md" - markup/filter-raw: "|raw" - markup/filter-default: "|default" + markup/filter-app: "| app" + markup/filter-page: "| page" + markup/filter-theme: "| theme" + markup/filter-media: "| media" + markup/filter-reszize: "| resize" + markup/filter-image-width: "| imageWidth" + markup/filter-image-height: "| imageHeight" + markup/filter-md: "| md" + markup/filter-raw: "| raw" + markup/filter-default: "| default" Functions: icon: "icon-eraser" diff --git a/database-attachments.md b/database-attachments.md index 029c6d7e..aee43cd3 100644 --- a/database-attachments.md +++ b/database-attachments.md @@ -45,7 +45,7 @@ For singular attach relations (`$attachOne`), you may create an attachment direc You may also pass a string to the `data` attribute that contains an absolute path to a local file. $model->avatar = '/path/to/somefile.jpg'; - + Sometimes it may also be useful to create a `File` instance directly from (raw) data: $file = (new System\Models\File)->fromData('Some content', 'sometext.txt'); @@ -62,18 +62,18 @@ Alternatively, you can prepare a File model before hand, then manually associate $file->save(); $model->avatar()->add($file); - + You can also add a file from a URL. To work this method, you need install cURL PHP Extension. $file = new System\Models\File; $file->fromUrl('https://example.com/uploads/public/path/to/avatar.jpg'); $user->avatar()->add($file); - + Occasionally you may need to change a file name. You may do so by using second method parameter. $file->fromUrl('https://example.com/uploads/public/path/to/avatar.jpg', 'somefilename.jpg'); - + ### Viewing attachments @@ -96,33 +96,7 @@ To output the file contents directly, use the `output` method, this will include echo $model->avatar->output(); -You can resize an image with the `getThumb` method. The method takes 3 parameters - image width, image height and the options parameter. The following options are supported: - -Option | Description -------------- | ------------- -**mode** | auto, exact, portrait, landscape, crop, fit. Default: auto -**quality** | 0 - 100. Default: 90 -**interlace** | boolean: false (default), true -**extension** | auto, jpg, png, webp, gif. Default: jpg - -The **width** and **height** parameters should be specified as a number or as the **auto** word for the automatic proportional scaling. - - echo $model->avatar->getThumb(100, 100, ['mode' => 'crop']); - -Display image on a page: - - Description Image - -#### Viewing Modes - -The `mode` option allows you to specify how the image should be resized. Here are the available modes: - -* `auto` will automatically choose between `portrait` and `landscape` based on the image's orientation -* `exact` will resize to the exact dimensions given, without preserving aspect ratio -* `portrait` will resize to the given height and adapt the width to preserve aspect ratio -* `landscape` will resize to the given width and adapt the height to preserve aspect ratio -* `crop` will crop to the given dimensions after fitting as much of the image as possible inside those -* `fit` will fit the image inside the given maximal dimensions, keeping the aspect ratio +You can resize an image with the `getThumb` method. The method takes 3 parameters - image width, image height and the options parameter. Read more about these parameters on the [Image Resizing](../services/image-resizing#resize-parameters) page. ### Usage example @@ -191,11 +165,11 @@ If you need to access the owner of a file, you can use the `attachment` property public $morphTo = [ 'attachment' => [] ]; - -Example: + +Example: $user = $file->attachment; - + For more information read the [polymorphic relationships](../database/relations#polymorphic-relations) @@ -206,7 +180,7 @@ The example below uses [array validation](../services/validation#validating-arra use October\Rain\Database\Traits\Validation; use System\Models\File; use Model; - + class Gallery extends Model { use Validation; @@ -214,12 +188,12 @@ The example below uses [array validation](../services/validation#validating-arra public $attachMany = [ 'photos' => File::class ]; - + public $rules = [ 'photos' => 'required', 'photos.*' => 'image|max:1000|dimensions:min_width=100,min_height=100' ]; - + /* some other code */ } diff --git a/markup-filter-app.md b/markup-filter-app.md index f0d2dc91..95494b67 100644 --- a/markup-filter-app.md +++ b/markup-filter-app.md @@ -1,8 +1,8 @@ -# |app +# | app -The `|app` filter returns an address relative to the public path of the website. The result is an absolute URL, including the domain name and protocol, to the location specified in the filter parameter. The filter can be applied to any path. +The `| app` filter returns an address relative to the public path of the website. The result is an absolute URL, including the domain name and protocol, to the location specified in the filter parameter. The filter can be applied to any path. - + If the website address is __http://octobercms.com__ the above example would output the following: @@ -10,7 +10,7 @@ If the website address is __http://octobercms.com__ the above example would outp It can also be used for static URLs: - + About Us @@ -20,4 +20,4 @@ The above would output: About us -> **Note**: The `|page` filter is recommended for linking to other pages. +> **Note**: The `| page` filter is recommended for linking to other pages. diff --git a/markup-filter-default.md b/markup-filter-default.md index 23844af7..3a0ee582 100644 --- a/markup-filter-default.md +++ b/markup-filter-default.md @@ -1,15 +1,15 @@ -# |default +# | default -The `|default` filter returns the value passed as the first argument if the filtered value is undefined or empty, otherwise the filtered value is returned. +The `| default` filter returns the value passed as the first argument if the filtered value is undefined or empty, otherwise the filtered value is returned. - {{ variable|default('The variable is not defined') }} + {{ variable | default('The variable is not defined') }} - {{ variable.foo|default('The foo property on variable is not defined') }} + {{ variable.foo | default('The foo property on variable is not defined') }} - {{ variable['foo']|default('The foo key in variable is not defined') }} + {{ variable['foo'] | default('The foo key in variable is not defined') }} - {{ ''|default('The variable is empty') }} + {{ '' | default('The variable is empty') }} When using the `default` filter on an expression that uses variables in some method calls, be sure to use the `default` filter whenever a variable can be undefined: - {{ variable.method(foo|default('bar'))|default('bar') }} + {{ variable.method(foo | default('bar')) | default('bar') }} diff --git a/markup-filter-image-height.md b/markup-filter-image-height.md new file mode 100644 index 00000000..ca52095e --- /dev/null +++ b/markup-filter-image-height.md @@ -0,0 +1,10 @@ +# | imageHeight + +The `| imageHeight` filter attempts to identify the width in pixels of the provided image source. + +>**NOTE:** This filter does not support thumbnail (already resized) versions of FileModels being passed as the image source. + + {% set resizedImage = 'banner.jpg' | media | resize(1920, 1080) %} + + +See the [image resizing docs](../services/image-resizing#resize-sources) for more information on what image sources are supported. \ No newline at end of file diff --git a/markup-filter-image-width.md b/markup-filter-image-width.md new file mode 100644 index 00000000..9f9a1144 --- /dev/null +++ b/markup-filter-image-width.md @@ -0,0 +1,10 @@ +# | imageWidth + +The `| imageWidth` filter attempts to identify the width in pixels of the provided image source. + +>**NOTE:** This filter does not support thumbnail (already resized) versions of FileModels being passed as the image source. + + {% set resizedImage = 'banner.jpg' | media | resize(1920, 1080) %} + + +See the [image resizing docs](../services/image-resizing#resize-sources) for more information on what image sources are supported. \ No newline at end of file diff --git a/markup-filter-md.md b/markup-filter-md.md index dced25d8..76a72b4b 100644 --- a/markup-filter-md.md +++ b/markup-filter-md.md @@ -1,8 +1,8 @@ -# |md +# | md -The `|md` filter converts the value from Markdown to HTML format. +The `| md` filter converts the value from Markdown to HTML format. - {{ '**Text** is bold.'|md }} + {{ '**Text** is bold.' | md }} The above will output the following: diff --git a/markup-filter-media.md b/markup-filter-media.md index fc9fb824..0781bee5 100644 --- a/markup-filter-media.md +++ b/markup-filter-media.md @@ -1,9 +1,9 @@ -# |media +# | media -The `|media` filter returns an address relative to the public path of the [media manager library](../cms/mediamanager). The result is a URL to the media file specified in the filter parameter. +The `| media` filter returns an address relative to the public path of the [media manager library](../cms/mediamanager). The result is a URL to the media file specified in the filter parameter. - + -If the media manager address is __http://cdn.octobercms.com__ the above example would output the following: +If the media manager address is __https://cdn.octobercms.com__ the above example would output the following: - + diff --git a/markup-filter-page.md b/markup-filter-page.md index 49116aa3..c224f2bf 100644 --- a/markup-filter-page.md +++ b/markup-filter-page.md @@ -1,17 +1,17 @@ -# |page +# | page -The `|page` filter creates a link to a page using a page file name, without an extension, as a parameter. For example, if there is the about.htm page you can use the following code to generate a link to it: +The `| page` filter creates a link to a page using a page file name, without an extension, as a parameter. For example, if there is the about.htm page you can use the following code to generate a link to it: - About Us + About Us Remember that if you refer a page from a subdirectory you should specify the subdirectory name: - About Us + About Us > **Note**: The [Themes documentation](../cms/themes#subdirectories) has more details on subdirectory usage. To access the link to a certain page from the PHP section, you can use `$this->pageUrl('page-name-without-extension')`: - + == p You can create a link to the current page by filtering an empty string: - Refresh page - + Refresh page + To get the link to the current page in PHP, you can use `$this->pageUrl('')` with an empty string. == @@ -39,7 +39,7 @@ To get the link to the current page in PHP, you can use `$this->pageUrl('')` wit ## Reverse routing -When linking to a page that has URL parameters defined, the `|page` filter supports reverse routing by passing an array as the first argument. +When linking to a page that has URL parameters defined, the ` | page` filter supports reverse routing by passing an array as the first argument. url = "/blog/post/:post_id" == @@ -47,7 +47,7 @@ When linking to a page that has URL parameters defined, the `|page` filter suppo Given the above content is found in a CMS page file **post.htm** you can link to this page using: - + Blog post #10 @@ -60,7 +60,7 @@ If the website address is __http://octobercms.com__ the above example would outp ## Persistent URL parameters -If a URL parameter is already presented in the environment, the `|page` filter will use it automatically. +If a URL parameter is already presented in the environment, the ` | page` filter will use it automatically. url = "/blog/post/:post_id" @@ -68,7 +68,7 @@ If a URL parameter is already presented in the environment, the `|page` filter w If there are two pages, **post.htm** and **post-edit.htm**, with the above URLs defined, you can link to either page without needing to define the `post_id` parameter. - + Edit this post @@ -80,12 +80,12 @@ When the above markup appears on the **post.htm** page, it will output the follo The `post_id` value of *10* is already known and has persisted across the environments. You can disable this functionality by passing the 2nd argument as `false`: - + Unknown blog post Or by defining a different value: - + Blog post #6 diff --git a/markup-filter-raw.md b/markup-filter-raw.md index d6537a93..222f5ecf 100644 --- a/markup-filter-raw.md +++ b/markup-filter-raw.md @@ -1,19 +1,19 @@ -# |raw +# | raw -Output variables in October are automatically escaped, the `|raw` filter marks the value as being "safe" and will not be escaped if `raw` is the last filter applied. +Output variables in October are automatically escaped, the `| raw` filter marks the value as being "safe" and will not be escaped if `raw` is the last filter applied. {# This variable won't be escaped #} - {{ variable|raw }} + {{ variable | raw }} Be careful when using the `raw` filter inside expressions: {% set hello = 'Hello' %} {% set hola = 'Hola' %} - {{ false ? 'Hola' : hello|raw }} + {{ false ? 'Hola' : hello | raw }} {# The above will not render the same as #} - {{ false ? hola : hello|raw }} + {{ false ? hola : hello | raw }} {# But renders the same as #} - {{ (false ? hola : hello)|raw }} + {{ (false ? hola : hello) | raw }} diff --git a/markup-filter-resize.md b/markup-filter-resize.md new file mode 100644 index 00000000..51ec23f4 --- /dev/null +++ b/markup-filter-resize.md @@ -0,0 +1,17 @@ +# | resize + +The `| resize` filter attempts to resize the provided image source using the provided resizing configuration and outputs a URL to the resized image. + + + +If the filter can successfully resize the provided image, then a URL to the October image resizer (`/resize/$id/$targetUrl`) will be rendered as the output of this filter until the image has been successfully resized. Once the image has been resized any future calls to this filter with the specific image and configuration combination will instead output a direct URL to the resized image. + +This means that the actual work of resizing the image is delayed until the browser requests a specific image which prevents the resizing of the images from blocking the rendering of a page. It also means that several resize requests can be handled at once in parallel as the browser will make multiple requests at the same time for resized images with each request able to handle just resizing its own image. + +>**NOTE:** If the filter is unable to process the provided image, then it will instead return the original URL unmodified. + +The filter accepts three parameters: `| resize(int $width [, int $height , array $options])`. + +See the [image resizing docs](../services/image-resizing#resize-parameters) for more information on the parameters. + +- [List of locations images can be resized from](../services/image-resizing#resize-sources) diff --git a/markup-filter-theme.md b/markup-filter-theme.md index 3a3899fa..41789f7d 100644 --- a/markup-filter-theme.md +++ b/markup-filter-theme.md @@ -1,8 +1,8 @@ -# |theme +# | theme -The `|theme` filter returns an address relative to the active theme path of the website. The result is an absolute URL, including domain and protocol, to the asset specified in the filter parameter. Theme assets usually reside in the **assets** subdirectory of a theme directory. +The `| theme` filter returns an address relative to the active theme path of the website. The result is an absolute URL, including domain and protocol, to the asset specified in the filter parameter. Theme assets usually reside in the **assets** subdirectory of a theme directory. - + If the website address is __https://octobercms.com__ and the active theme is called `website` the above example would output the following: @@ -16,7 +16,7 @@ The filter can also be used to combine assets of the same type by passing an arr + ] | theme }}" rel="stylesheet"> > **Note**: You can enable the assets minification with the `enableAssetMinify` parameter in the `config/cms.php` script. By default the minification is disabled. @@ -30,7 +30,7 @@ The asset combiner supports common aliases that substitute file paths, these wil '@framework', '@framework.extras', 'assets/javascript/app.js' - ]|theme }}"> + ] | theme }}"> The following aliases are supported: @@ -49,7 +49,7 @@ The same alias can be used for JavaScript or CSS, for example `@framework.extras In some cases you may wish to combine a file outside the theme, this is achieved by prefixing the path with a symbol to create a dynamic path. For example, a path beginning with `~/` will create a path relative to the application: - + These symbols are supported for creating dynamic paths: diff --git a/services-image-resizing.md b/services-image-resizing.md new file mode 100644 index 00000000..815a8edc --- /dev/null +++ b/services-image-resizing.md @@ -0,0 +1,48 @@ +# Image Resizing + +- [Resize parameters](#resize-parameters) +- [Available modes](#available-modes) +- [Resize sources](#resize-sources) + + +## Resize Parameters + +The basic parameters provided to the ImageResizer are `(int) $width`, `(int) $height`, and `(array) $options`. + +If `$width` or `$height` is falsey or `'auto'`, that value is calculated using original image ratio (automatic proportional scaling). + +The following elements are supported in the options array are supported: + +Key | Description | Default | Options +--- | --- | --- | --- +`mode` | How the image should be fitted to dimensions | `auto` | `exact`, `portrait`, `landscape`, `auto`, `fit`, or `crop` +`offset` | Offset the crop of the resized image | `[0,0]` | [left, top] +`quality` | Quality of the resized image | `90` | `0-100` +`sharpen` | Amount to sharpen the image | `0` | `0-100` + + +### Available Modes + +The `mode` option allows you to specify how the image should be resized. The available modes are as follows: + +Mode | Description +--- | --- +`auto` | Automatically choose between `portrait` and `landscape` based on the image's orientation +`exact` | Resize to the exact dimensions given, without preserving aspect ratio +`portrait` | Resize to the given height and adapt the width to preserve aspect ratio +`landscape` | Resize to the given width and adapt the height to preserve aspect ratio +`crop` | Crop to the given dimensions after fitting as much of the image as possible inside those +`fit` | Fit the image inside the given maximal dimensions, keeping the aspect ratio + + +## Resize sources + +The available sources that images can be resized from are as follows: + +- Plugins +- Themes +- Media Library +- Uploads Directory +- Models that extend the `\October\Rain\Database\Attach\File` model + +Available sources can be extend by listening to the [`system.resizer.getAvailableSources` event](../api/system/resizer/getavailablesources) \ No newline at end of file diff --git a/themes-development.md b/themes-development.md index 9b63c002..5259bb7a 100644 --- a/themes-development.md +++ b/themes-development.md @@ -83,10 +83,10 @@ The following is an example of how to define a website name configuration field label: Site name comment: The website name as it should appear on the front-end default: My Amazing Site! - -> **Note:** If using nested fields with array syntax (`contact[name]`, `contact[email]` etc.) you need to add the top level to the `ThemeData` model's `jsonable` array using the following: - \Cms\Models\ThemeData::extend(function ($model) { +> **Note:** If using nested fields with array syntax (`contact[name]`, `contact[email` etc.) you need to add the top level to the `ThemeData` model's `jsonable` array using the following: + + \Cms\Models\ThemeData::extend(function ($model) { $model->addJsonable('contact'); }); @@ -100,7 +100,7 @@ You may also define the configuration in a separate file, where the path is rela # [...] form: config/fields.yaml - + **config/fields.yaml**: fields: @@ -112,7 +112,7 @@ You may also define the configuration in a separate file, where the path is rela ### Combiner variables -Assets combined using the `|theme` [filter and combiner](../markup/filter-theme) can have values passed to supporting filters, such as the LESS filter. Simply specify the `assetVar` option when defining the form field, the value should contain the desired variable name. +Assets combined using the `| theme` [filter and combiner](../markup/filter-theme) can have values passed to supporting filters, such as the LESS filter. Simply specify the `assetVar` option when defining the form field, the value should contain the desired variable name. form: fields: @@ -125,7 +125,7 @@ Assets combined using the `|theme` [filter and combiner](../markup/filter-theme) In the above example, the color value selected will be available inside the less file as `@link-color`. Assuming we have the following stylesheet reference: - + Using some example content inside **themes/yourtheme/assets/less/theme.less**: