Media Picker 3 documentation

Getting-Started/Backoffice/Property-Editors/Built-in-Property-Editors/Image-Cropper/index.md

@@ -8,6 +8,14 @@ versionFrom: 8.7.0
 
 Returns a path to an image, along with information about focal point and available crops
 
+When image Cropper is used on a Media Type the crops are shared between all usages of a Media Item. This is called global crops.
+
+If Image Cropper is used on a Document Type, the file and crops will be local to the Document.
+
+Notice its possible make local crops on shared Media Items via the Media Picker 3 Property Editor.
+
+[Read about the Media Picker 3](../Media-Picker-3/index.md)
+
 ## Settings
 
 ### Prevalues
@@ -59,7 +67,7 @@ The Url Helper method can be used to replace the IPublishedContent extension met
 For rendering a cropped media item, the `.GetCropUrl` is used:
 
 ```csharp
-@Url.​GetCropUrl​(mediaItem: Model.Image, cropAlias: ​"Grid"​, htmlEncode: true); 
+@Url.​GetCropUrl​(mediaItem: Model.Image, cropAlias: ​"Grid"​, htmlEncode: true);
 ```
 
 `HtmlEncode` is by default set to true, which means you only need to define the parameter if you wan't to disable HTML encoding.
@@ -91,7 +99,7 @@ Set the `htmlEncode` to false so that the URL is not HTML encoded
 
 ```csharp
 @{
-    
+
     if (Model.Image != null)
     {
         var cropUrl = Url.GetCropUrl(Model.Image, "banner", false);
@@ -131,7 +139,7 @@ See the example below to see how a value can be added or changed programmaticall
 
     // Create a variable for the GUID of the media item you want to use
     var mediaKey = Guid.Parse("8835014f-5f21-47b7-9f1a-31613fef447c");
-
+    
     // Get the desired media file
     var media = Umbraco.Media(mediaKey);
 
@@ -153,7 +161,7 @@ Although the use of a GUID is preferable, you can also use the numeric ID to get
 ```csharp
 @{
     // Get the page using it's id
-    var content = contentService.GetById(1234); 
+    var content = contentService.GetById(1234);
 }
 ```
 

Getting-Started/Backoffice/Property-Editors/Built-in-Property-Editors/Media-Picker-3/index.md

@@ -0,0 +1,165 @@
+---
+versionFrom: 8.14.0
+---
+
+# Media Picker #
+
+`Alias: Umbraco.MediaPicker3`
+
+`Returns: IEnumerable<MediaWithCrops>` or `MediaWithCrops`
+
+This property editors returns a single `MediaWithCrops` item if the "Pick multiple items" data type setting is disabled or a collection if it is enabled.
+
+## Data Type Definition Example
+
+![Media Picker Data Type Definition](images/Media-Picker3-DataType.jpg)
+
+### Accepted types
+
+Use setting to limit the picker to only select Media Items of these types.
+
+### Pick multiple items
+
+Use this setting to enable the property to contain multiple items. When this is enabled the property editor returns an `IEnumerable<MediaWithCrops>`.
+
+You can still set the maximum amount to 1. Do so when you want to retrieve a collection but only allow the Content Editors to select one Media Item.
+
+### Amount
+
+Use this setting to enforce a minimum and/or maximum amount of selected Media Items. Note that it is not possible to set a maximum when the "Pick multiple items" feature is disabled.
+
+### Start node
+
+This setting is used to limit the Media Picker to certain parts of the Media Tree.
+
+### Ignorer user start nodes
+
+Use this setting to overrule user permissions, to enable any user of this property to pick any Media Item of the chosen Start node.
+
+When this setting is enabled, a user who doesn't normally have access to the media selected as "Start Node" (/Design in this case), can access the media when using this particular Media Picker. If no Start node has been defined for this property any content can be viewed and selected of this property.
+
+
+### Enable Focal Point
+
+Enable the focal point setter, do only enable this if the focal point is used or if you have Image crops defined.
+
+### Image Crops
+
+Define local image crops. Local image crop data is stored on the document in this property. This means it can differentiate between documents.
+
+This is different from Global crops as they are defined on the Media Item, making the crops shared between all usage of that Media Item.
+
+Global crops are configured on the Image Cropper property of the Image Media Type
+
+[Read about the Image Cropper here](../Image-Cropper/index.md)
+
+## Content Example
+
+![Media Picker Content](images/Media-Picker3-Content.jpg)
+
+## MVC View Example
+
+### Multiple enabled without Modelsbuilder
+
+```csharp
+@{
+    var typedMultiMediaPicker = Model.Value<IEnumerable<MediaWithCrops>>("medias");
+    foreach (var entry in typedMultiMediaPicker)
+    {
+        <img src="@entry.MediaItem.Url" style="width:200px"/>
+    }
+}
+```
+
+### Multiple enabled with Modelsbuilder
+
+```csharp
+@{
+    var typedMultiMediaPicker = Model.Medias;
+    foreach (var entry in typedMultiMediaPicker)
+    {
+        <img src="@entry.MediaItem.Url" style="width:200px" />
+    }
+}
+```
+
+### Multiple disabled without Modelsbuilder
+
+```csharp
+@{
+    var typedMediaPickerSingle = Model.Value<MediaWithCrops>("media");
+    if (typedMediaPickerSingle != null)
+    {
+        <img src="@typedMediaPickerSingle.MediaItem.Url" style="width:200px" alt="@typedMediaPickerSingle.MediaItem.Value("alt")" />
+    }
+}
+```
+
+### Multiple disabled with Modelsbuilder
+
+```csharp
+@{
+    var typedMediaPickerSingle = Model.Media;
+    if (typedMediaPickerSingle is MediaWithCrops mediaEntry)
+    {
+        <img src="@mediaEntry.MediaItem.Url" style="width:200px"/>
+    }
+}
+```
+
+## Using local crops
+
+Local image crops are stored and retrieved differently than global crops. Below are two examples of how to retrieve local crops.
+
+### Using GetLocalCropUrl
+
+```csharp
+@{
+    foreach (var entry in Model.Medias)
+    {
+        <img src="@entry.GetLocalCropUrl("cropAlias")"/>
+    }
+}
+```
+
+### Using UrlHelper
+
+```csharp
+@{
+    foreach (var entry in Model.Medias)
+    {
+        <img src="@Url.GetCropUrl(entry.LocalCrops, "cropAlias")"/>
+    }
+}
+```
+
+## Use global crops
+
+Global image croppings are crops stored on the Media Item, by the Property Editor `Image Cropper`, making it shared between all usages of the media Item.
+
+The global crops are configured on the DataType of the `umbracoFile` property on the Media Type `Image`
+
+[Read about the Image Cropper here](../Image-Cropper/index.md)
+
+### Using GetCropUrl
+
+```csharp
+@{
+    foreach (var entry in Model.Medias)
+    {
+        <img src="@entry.MediaItem.GetCropUrl("cropAlias")"/>
+    }
+}
+```
+
+### Using UrlHelper
+
+```csharp
+@{
+    foreach (var entry in Model.Medias)
+    {
+        <img src="@Url.GetCropUrl(entry.MediaItem, "cropAlias")"/>
+    }
+}
+
+```

Getting-Started/Backoffice/Property-Editors/Built-in-Property-Editors/Media-Picker/index.md

@@ -10,6 +10,10 @@ versionFrom: 8.1.0
 
 This property editors returns a single item if the "Pick multiple items" data type setting is disabled or a collection if it is enabled.
 
+:::note 
+As of Umbraco 8.14, this Media Picker has been replaced by [Media Picker 3](Media-Picker-3). This updated property contains more customizable features, and we recommend using this over the Media Picker, which is also marked as the *old* version of the picker.
+:::
+
 ## Data Type Definition Example
 
 ![Media Picker Data Type Definition](images/Media-Picker-DataType-8_1.png)

Getting-Started/Backoffice/Property-Editors/Built-in-Property-Editors/index.md

@@ -104,12 +104,22 @@ This control gives the same functionality as the standard listview, but allows y
 
 The markdown editor will be interpreted by the Models Builder. Behind the scenes, Umbraco uses the [Markdown NuGet package](https://www.nuget.org/packages/Markdown/).
 
+## [Media Picker 3 (Recommended)](Media-Picker-3/index.md)
+
+`Alias: Umbraco.MediaPicker3`
+
+Media Picker 3 is the latest Media Picker, which enables you to select one or more media items from the Media Section. This Property Editor can be configured to only pick certain Media Types and it's possible to define Local Image Crops.
+
 ## [Media Picker](Media-Picker/index.md)
 
 `Alias: Umbraco.MediaPicker`
 
 The media picker displays the current selected media and provides the option to open the mediaPicker dialog to select existing or upload new media files. There is a setting to enable multiple media items to be selected.
 
+:::note 
+As of Umbraco 8.14, this Media Picker has been replaced by [Media Picker 3](Media-Picker-3). This updated property contains more customizable features, and we recommend using this over the Media Picker, which is also marked as the *old* version of the picker.
+:::
+
 ## [Member Group Picker](Member-Group-Picker/index.md)
 
 `Alias: Umbraco.MemberGroupPicker`