Media Picker 3 documentation

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

@@ -0,0 +1,157 @@
+---
+versionFrom: 8.13.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 turned on the property editor returns a `IEnumerable<MediaWithCrops>`. You can still set the Maximum Amount to 1, do so if you like to retrive a collection but only allowing the Content Editors to select one Media Item.
+
+### Amount
+
+Use this setting to enforce a certain minimum or maximum amount of selected Media Items, the maximum setting is unuseable when multiple items is disabled.
+
+### Start node
+
+Limit the picker to only work in a certain part of the Media Tree.
+
+### Ignorer user start nodes
+
+Use setting to overrule user permissions, to enable any user of this property to pick any Media Item of the choosen 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.
+
+
+### Image Croppings
+
+Define local image croppings, this data will stay locally, meaning that this will be stored on the document in this property.
+
+## 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)
+    {
+        <p>@typedMediaPickerSingle.MediaItem.Url</p>
+        <img src="@typedMediaPickerSingle.MediaItem.Url" style="width:200px" alt="@typedMediaPickerSingle.MediaItem.Value("alt")" />
+    }
+}
+```
+
+## Multiple disabled with Modelsbuilder
+
+```csharp
+@{
+    var typedMediaPickerSingle = Model.FeaturedBanner;
+    if (typedMediaPickerSingle is MediaWithCrops mediaEntry)
+    {
+        <p>@mediaEntry.MediaItem.Url</p>
+        <img src="@mediaEntry.MediaItem.Url" style="width:200px"/>
+    }
+}
+```
+
+## Using local crops
+
+Local image croppings are stored and retrived different than global crops, below is two examples of how to retrive 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 croppes 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")"/>
+    }
+}
+
+## Add values programmatically
+
+```This is not part of the current Media Picker v3, feel free to provide such.```

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

@@ -98,6 +98,12 @@ 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](Media-Picker-3/index.md)
+
+`Alias: Umbraco.MediaPicker3`
+
+Media picker 3 is the latest Media Picker, which enables to select one or more medias from the Media Section. This Property Editor can be configured to only pick certain Media Types. And its possible to define Local Image Crops.
+
 ## [Media Picker](Media-Picker/index.md)
 
 `Alias: Umbraco.MediaPicker`