{% render_blocks value.left %}
{% render_blocks value.right %}
{{ page.title }}
{% render_blocks page.sections %} ``` By default the template of a block is `
{% if value.caption %}{{ block.render }}
{% endif %}
{% endfor %}
```
In Python, `page.sections` is a list of the stored blocks, and
`page.sections.blocks` the same blocks with their values.
## Change blocks later
Existing pages keep the blocks they were saved with:
- **A new field** takes its default on existing blocks. A new required
field without a default asks the editor for a value on the next save.
- **A renamed block class** keeps its stored blocks when `Meta.name` keeps
the old name.
- **A removed block** stays in the stored data. The admin shows it as an
unknown block that editors can remove, the page cannot be saved until
they do, and templates leave it out.
To find the pages that use a block, use a
[JSON containment lookup](https://docs.djangoproject.com/en/stable/topics/db/queries/#contains),
which works on PostgreSQL, MySQL and MariaDB:
`LandingPage.objects.filter(sections__contains=[{"type": "image"}])`.
## Without a block field
A block field is optional. With plain Django, a related model does the same
job: a `Section` model with a foreign key to the page, a type field and a
position field, edited as an [inline](https://djangocontentstudio.org/docs/registering-models.md#inlines)
on the page's studio with `reorder_field = "position"`, so editors can drag
sections into order (see [Reordering](https://djangocontentstudio.org/docs/list-page.md#reordering)).
Each section is then a row in its own table, which you can query and protect
with database constraints.
## Related pages
- [Widgets](https://djangocontentstudio.org/docs/widgets.md)
- [Media library](https://djangocontentstudio.org/docs/media-library.md)
- [System checks](https://djangocontentstudio.org/docs/deployment.md#system-checks)
Source: https://djangocontentstudio.org/docs/block-fields
---
# Media library
The media library is where editors upload and organize files: images,
video, audio and documents, in folders. Fields such as `MediaField` then
pick files from it. The library works with your own media models, or with
the ready-made models Content Studio ships.
## Set it up with your own models
Point the settings at a media item model and, optionally, a folder model:
```python
# mysite/settings.py
CONTENT_STUDIO = {
"MEDIA_LIBRARY_MODEL": "blog.models.MediaItem",
"MEDIA_LIBRARY_FOLDER_MODEL": "blog.models.MediaFolder",
}
```
A media item model needs these fields:
- `file`: the upload, a `FileField` or `ImageField`.
- `name`: shown on the item and used by the search.
- `type`: one of `"image"`, `"video"`, `"audio"` or `"file"`; it decides
the preview.
- `tags` (optional): a list of strings, such as a `JSONField`, an
`ArrayField` or the built-in `TagField`. Searched together with the name.
- `alt_text` (optional): a short text alternative for the file.
- `metadata` (optional): a `JSONField` for the [metadata](#metadata) read
from the file.
- `properties` (optional): a `JSONField` for the [properties](#properties)
editors set, such as an image's focal point.
The fields above apply to every type of media. A value that applies to only some
types of media, such as an image's focal point, belongs in `metadata` when
it is read from the file, and in `properties` when editors set it.
A folder model needs a `name` and a `parent` foreign key to itself. System
check `content_studio.W007` reports missing fields. Without the
`MEDIA_LIBRARY_MODEL` setting, the media library does not appear in the
admin.
## Or use the built-in models
The `content_studio.media_library` app ships media item and folder models
that follow these rules, with migrations. Add the app and point the
settings at its models:
```python
# mysite/settings.py
INSTALLED_APPS = [
# ...
"content_studio",
"content_studio.media_library",
]
CONTENT_STUDIO = {
"MEDIA_LIBRARY_MODEL": "content_studio.media_library.models.Media",
"MEDIA_LIBRARY_FOLDER_MODEL": "content_studio.media_library.models.Folder",
}
```
With [multi-tenancy](https://djangocontentstudio.org/docs/multi-tenancy.md), the media library is shared by
every tenant.
Deleting an item also removes its file from storage, and replacing an item's
file removes the previous one. With your own models, a replaced file is
removed as well; a deleted item's file stays unless your model removes it,
for example in a `post_delete` receiver.
## Working in the media library
Editors upload files with the upload button or by dragging them onto the
library, and add tags in the same step when the model has a `tags` field.
They move files between folders, edit their details, and copy or download a
file from its menu.
The library has three views: a **grid** of thumbnails, a **list** and a
**table** with sortable columns for name, type and size. The admin remembers
the view, the filters and the sort order per media model. The search and the
current folder are part of the URL, so a filtered view survives a reload and
the back button.
The search matches names and tags. Two filters narrow the items further:
- **Type**: image, video, audio or file.
- **Tags**: any of the selected tags.
With folders, the search covers the current folder or the whole library, set
with the toggle next to the search box. Each folder shows how many items it
holds.
Browsing the media library, also from a media field, needs the media
model's view or change permission; that permission also opens the folders.
Select items to delete them or move them to another folder. Deleting needs
the model's delete permission, moving its change permission.
## Uploads
The media library accepts the file types in
[`MEDIA_LIBRARY_ALLOWED_EXTENSIONS`](https://djangocontentstudio.org/docs/settings.md#media_library_allowed_extensions),
up to [`MEDIA_LIBRARY_MAX_UPLOAD_SIZE`](https://djangocontentstudio.org/docs/settings.md#media_library_max_upload_size)
(50 MB by default). It rejects files whose content is markup, such as HTML or
SVG: served from your own domain, such a file could run scripts in your
editors' sessions.
## Thumbnails
The admin shows images in two sizes: small thumbnails in the media library,
pickers and list pages, and large ones in the cover image widget, cropping
and the focal point. With the `images` extra installed, Content Studio makes
both from the uploaded image:
```bash
pip install "django-content-studio[images]"
```
Thumbnails are saved in the image's own storage, in the folder set by
[`THUMBNAIL_FOLDER`](https://djangocontentstudio.org/docs/settings.md#thumbnail_folder). Content Studio makes
them when an image is uploaded, replaced or cropped, and the first time an
image you already have is shown. It removes them with the image.
Making a thumbnail takes a moment, so a library of existing images is slow
the first time the admin shows it. Make the missing thumbnails in advance:
```bash
python manage.py content_studio_thumbnails
```
Pass `--all` to make every thumbnail again.
With several worker processes or servers, configure a shared cache for
[`THUMBNAIL_CACHE`](https://djangocontentstudio.org/docs/settings.md#thumbnail_cache), such as Redis,
Memcached or the database cache.
Without Pillow, with `THUMBNAIL_FOLDER` set to `None`, or for a file it
cannot read, the admin shows the image file itself. To serve thumbnails
another way, override [`get_thumbnail`](#customize-with-site-hooks).
## Image sizes
Thumbnails are for the admin. For your site, apps and other consumers, name
the sizes you need in [`IMAGE_SIZES`](https://djangocontentstudio.org/docs/settings.md#image_sizes), and
Content Studio makes every image in each of them:
```python
CONTENT_STUDIO = {
# ...
"IMAGE_SIZES": {
"card": {"width": 600, "height": 400, "fit": "cover"},
"hero": {"width": 1920},
"share": {"width": 1200, "height": 630, "fit": "cover", "format": "jpeg"},
},
}
```
Each size takes these options:
| Option | Default | Meaning |
|--------|---------|---------|
| `width`, `height` | | The box in pixels. Give one or both; a side left out is free. |
| `fit` | `"contain"` | `"contain"` scales the image to fit inside the box. `"cover"` fills the box exactly, cut around the [focal point](#focal-points); it needs both sides. |
| `format` | `"webp"` | `"webp"`, `"jpeg"`, `"png"`, or `"original"` to keep the uploaded format (WebP for other formats). |
| `quality` | `82` | The quality of WebP and JPEG images, from 1 to 100. |
| `upscale` | `False` | Whether a smaller image is enlarged to the size. Without it, a small image gives a smaller size of the same shape. |
Sizes need the `images` extra and a media model with a metadata field (the
built-in `Media` model has one). Content Studio makes them after an image is
uploaded, replaced, cropped or reset, and makes the `"cover"` sizes again
when its focal point moves. They are saved in the image's own storage, in
the folder set by [`IMAGE_SIZE_FOLDER`](https://djangocontentstudio.org/docs/settings.md#image_size_folder)
(`"content_studio/sizes"` by default), and recorded in the item's metadata.
A size's file name changes whenever its image, its options or its focal
point change, so you can cache the files for as long as you like. Sizes that
are replaced, and the sizes of a deleted image, are removed.
### Use the sizes
`get_image_sizes` returns every size of an image, with its URL and the width
and height it has:
```python
from content_studio.media_library.sizes import get_image_sizes
get_image_sizes(article.cover)
# {"card": {"url": "/media/content_studio/sizes/...-card-....webp",
# "width": 600, "height": 400, "ready": True},
# "hero": {...}, "share": {...}}
```
In templates, use the `image_url` and `image_size` tags of the
`content_studio` library:
```django
{% load content_studio %}