# Media Picker

The media picker formfield allows you to upload/delete/select files directly from the media-manager.\
You can customize the behaviour with the following options:

```php
{
    "max": 10,
    "min": 0,
    "expanded": true,
    "show_folders": true,
    "show_toolbar": true,
    "allow_upload": true,
    "allow_move": true,
    "allow_delete": true,
    "allow_create_folder": true,
    "allow_rename": true,
    "allow_crop": true,
    "allowed": [],
    "hide_thumbnails": false,
    "quality": 90,
    "watermark": {
        "source": "...",
        "position": "top-left",
        "x": 0,
        "y": 0
    }
}
```

| Name                  | Description                                                                                                                            | Type   | Default       |
| --------------------- | -------------------------------------------------------------------------------------------------------------------------------------- | ------ | ------------- |
| base\_path            | The start path relative to the filesystem                                                                                              | String | /bread-slug/  |
| rename                | Rename uploaded files to a given string/expression                                                                                     | String | Original name |
| delete\_files         | <p>Delete files if the BREAD entry is deleted.</p><p>Use with caution!</p>                                                             | bool   | false         |
| show\_as\_images      | Shows stored data as images when browsing                                                                                              | bool   | false         |
| min                   | The minimum amount of files that can be selected                                                                                       | int    | 0             |
| max                   | <p>The maximum amount of files that can be selected.</p><p>0 means infinite</p>                                                        | int    | 0             |
| expanded              | If the media-picker should be expanded by default                                                                                      | bool   | true          |
| show\_folders         | Show subfolders                                                                                                                        | bool   | true          |
| show\_toolbar         | Shows/hides the whole toolbar                                                                                                          | bool   | false         |
| allow\_upload         | Allow users to upload new files                                                                                                        | bool   | true          |
| allow\_move           | Allow users to move files/folders                                                                                                      | bool   | true          |
| allow\_delete         | Allow users to delete files                                                                                                            | bool   | true          |
| allow\_create\_folder | Allow users to create new folders                                                                                                      | bool   | true          |
| allow\_rename         | <p>Allow users to rename files.</p><p>Use with caution!</p>                                                                            | bool   | true          |
| allow\_crop           | Allow users to crop images                                                                                                             | bool   | true          |
| hide\_thumbnails      | Hides known thumbnails and shows them as children of the parent image                                                                  | bool   | true          |
| quality               | Sets the quality of uploaded images and thumbnails                                                                                     | int    | 90            |
| allowed               | <p>The allowed types to be uploaded/selected.</p><p>Empty object means all types.</p><p>Files with other types won't be displayed.</p> | Object | \[]           |

### Allowed types

If you want your users to only be able to upload specific file-types you can do so by passing an object with mime-types to the \`allowed\` prop, for example:

```
["image", "audio", "video"]
```

or

```
["image/jpeg", "image/png", "image/bmp"]
```

### Expressions

The `base_path` and `rename` can contain the following placeholders:

* `{pk}` the primary-key of the entry (only for `base_path`)
* `{uid}` the user-id of the current logged-in user
* `{date:format}` the current date in the format defined in `format`. For example `{date:d.m.Y}`
* `{random:10}` random string with N characters

So a `base_path` can, for example, look like the following:

```
{
    "base_path": "/my-bread/{pk}/{date:Y}/{date:m}/"
}
```

### Watermark

A watermark can be added to uploaded images. To do so, you need to define a `source` property relative to Voyagers storage-disk. There are a few optional arguments you can use:\
**position** the position where the watermark is placed. Can be:

* top-left (default)
* top
* top-right
* left
* center
* right
* bottom-left
* bottom
* bottom-right

**x** Relative offset to the position on the x-axis. Defaults to 0

**y** Relative offset to the position on the y-axis. Defaults to 0

**size** the size (in percent) of the watermark relative to the image. Defaults to 15

### Thumbnails

You can generate thumbnails for each uploaded image.\
A thumbnail can be one of three types:

#### Fit

Fit combines cropping and resizing to find the best way to generate a thumbnail matching your dimensions.\
You have to pass `width` and can pass `height` and `position`.\
An example for `fit` would be:

```
{
    "thumbnails": [
        {
            "type": "fit",
            "name": "fit-500",
            "width": 500, // Required
            "height": 500, // Optional
            "position": "center" // Optional. Refer to http://image.intervention.io/api/fit
        }
    ]
}
```

#### Crop

Crop an image by given dimensions and position. You have to pass `width` and `height` and can pass `x` and `y`.\
An example for `crop` would be:

```
{
    "thumbnails": [
        {
            "type": "crop",
            "name": "crop-500-500",
            "width": 500, // Required
            "height": 500, // Required
            "x": 50, // Optional. Left offset
            "y": 50, // Optional. Top offset
        }
    ]
}
```

#### Resize

Resize the image to the given dimensions. You have to pass `width` and/or `height`.\
Some examples for `resize`:

```
{
    "thumbnails": [
        // Width will be 500px, height will be calculated based on the aspect-ratio
        {
            "type": "resize",
            "name": "resize-500",
            "width": 500,
            "upsize": true, // Optional. Set to false to prevent upsizing
        },
        // Resizes the image to 500x500px
        {
            "type": "resize",
            "name": "resize-500-500",
            "width": 500,
            "height": 500
        },
        // Height will be 500px, width will be auto-calculated
        {
            "type": "resize",
            "name": "resize-500",
            "width": null,
            "height": 500
        }
    ]
}
```

A watermark can also be inserted into each thumbnail. Just define the [watermark-options](#watermark) on the parent and set `watermark` to `true` for each thumbnail you want to insert the watermark to.