Document new Image Resizing functionality

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:
 
-    <script src="{{ 'assets/javascript/jquery.js'|theme }}"></script>
+    <script src="{{ 'assets/javascript/jquery.js' | theme }}"></script>
 
     {% framework %}
 

backend-lists.md

@@ -187,6 +187,7 @@ There are various column types that can be used for the **type** setting, these
 
 <div class="content-list collection-method-list" markdown="1">
 - [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)
 
+<a name="column-image"></a>
+### 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
+
 <a name="column-number"></a>
 ### 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'

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"

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"

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');
-    
+
 
 <a name="viewing-attachments"></a>
 ### 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:
-
-    <img src="{{ model.avatar.getThumb(100, 100, {'mode':'exact', 'quality': 80, 'extension': 'webp'}) }}" alt="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.
 
 <a name="attachments-usage-example"></a>
 ### 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)
 
 <a name="attachments-validation-example"></a>
@@ -206,20 +180,20 @@ 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;
 
         public $attachMany = [
             'photos' => File::class
         ];
-    
+
         public $rules = [
             'photos'   => 'required',
             'photos.*' => 'image|max:1000|dimensions:min_width=100,min_height=100'
         ];
-    
+
         /* some other code */
     }
 

markup-filter-app.md

@@ -1,16 +1,16 @@
-# |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.
 
-    <link rel="icon" href="{{ '/favicon.ico'|app }}" />
+    <link rel="icon" href="{{ '/favicon.ico' | app }}" />
 
 If the website address is __http://octobercms.com__ the above example would output the following:
 
     <link rel="icon" href="http://octobercms.com/favicon.ico" />
 
 It can also be used for static URLs:
 
-    <a href="{{ '/about-us'|app }}">
+    <a href="{{ '/about-us' | app }}">
         About Us
     </a>
 
@@ -20,4 +20,4 @@ The above would output:
         About us
     </a>
 
-> **Note**: The `|page` filter is recommended for linking to other pages.
+> **Note**: The `| page` filter is recommended for linking to other pages.

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') }}

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) %}
+    <img src="{{ resizedImage }}" height="{{ resizedImage | imageHeight }}" />
+
+See the [image resizing docs](../services/image-resizing#resize-sources) for more information on what image sources are supported.

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) %}
+    <img src="{{ resizedImage }}" width="{{ resizedImage | imageWidth }}" />
+
+See the [image resizing docs](../services/image-resizing#resize-sources) for more information on what image sources are supported.

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:
 

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.
 
-    <img src="{{ 'banner.jpg'|media }}" />
+    <img src="{{ 'banner.jpg' | media }}" />
 
-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:
 
-    <img src="http://cdn.octobercms.com/banner.jpg" />
+    <img src="https://cdn.octobercms.com/banner.jpg" />

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:
 
-    <a href="{{ 'about'|page }}">About Us</a>
+    <a href="{{ 'about' | page }}">About Us</a>
 
 Remember that if you refer a page from a subdirectory you should specify the subdirectory name:
 
-    <a href="{{ 'contacts/about'|page }}">About Us</a>
+    <a href="{{ 'contacts/about' | page }}">About Us</a>
 
 > **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')`:
-    
+
     ==
     <?php
     function onStart() {
@@ -23,8 +23,8 @@ To access the link to a certain page from the PHP section, you can use `$this->p
 
 You can create a link to the current page by filtering an empty string:
 
-    <a href="{{ ''|page }}">Refresh page</a>
-    
+    <a href="{{ '' | page }}">Refresh page</a>
+
 To get the link to the current page in PHP, you can use `$this->pageUrl('')` with an empty string.
 
     ==
@@ -39,15 +39,15 @@ To get the link to the current page in PHP, you can use `$this->pageUrl('')` wit
 <a name="reverse-routing"></a>
 ## 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"
     ==
     [...]
 
 Given the above content is found in a CMS page file **post.htm** you can link to this page using:
 
-    <a href="{{ 'post'|page({ post_id: 10 }) }}">
+    <a href="{{ 'post' | page({ post_id: 10 }) }}">
         Blog post #10
     </a>
 
@@ -60,15 +60,15 @@ If the website address is __http://octobercms.com__ the above example would outp
 <a name="persistent-parameters"></a>
 ## 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"
 
     url = "/blog/post/edit/:post_id"
 
 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.
 
-    <a href="{{ 'post-edit'|page }}">
+    <a href="{{ 'post-edit' | page }}">
         Edit this post
     </a>
 
@@ -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`:
 
-    <a href="{{ 'post'|page(false) }}">
+    <a href="{{ 'post' | page(false) }}">
         Unknown blog post
     </a>
 
 Or by defining a different value:
 
-    <a href="{{ 'post'|page({ post_id: 6 }) }}">
+    <a href="{{ 'post' | page({ post_id: 6 }) }}">
         Blog post #6
     </a>

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 = '<strong>Hello</strong>' %}
     {% set hola = '<strong>Hola</strong>' %}
 
-    {{ false ? '<strong>Hola</strong>' : hello|raw }}
+    {{ false ? '<strong>Hola</strong>' : 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 }}