diff --git a/content/3.content/1.explore.md b/content/3.content/1.explore.md index 4f945038..1904d795 100644 --- a/content/3.content/1.explore.md +++ b/content/3.content/1.explore.md @@ -1,22 +1,61 @@ --- -description: +description: Learn to filter, layout, batch edit and more with collections in the collection explorer. --- # Collection Explorer The content module allows users to browse, filter, and search for items held in collections. When users navigate into viewing single items, they use :product-link{product="editor"}. Each page contains data from a single collection, but can display related fields for each item. +To open the collection explorer, click on the content module on the left hand side of the page. + ## Filtering Items + + +You can create custom filters to display items that fulfill certain criteria. + +Click on :icon{name="material-symbols:filter-list"} at the top of the page to create a filter. You can then select a field to filter by and click on the criterion to tweak what should pass for that item to be filtered. + +### And / Or Groups + +`AND` groups give the option to filter for items that meet all of several criteria. On the other hand, `OR` groups filter for items that meet any one of several criteria. + +In order for filters to be included in `AND` or `OR` groups, filters must be indented below them in the filter UI. + +### Dynamic Variables + + + +The following dynamic variables are built into Directus to add extra functionality to filters: + +- **`$CURRENT_USER`** — The primary key of the currently authenticated user. +- **`$CURRENT_ROLE`** — The primary key of the role for the currently authenticated user. +- **`$CURRENT_ROLES`** - An array of roles containing the `$CURRENT_ROLE` and any roles included within it. +- **`$CURRENT_POLICIES`** - An array of policies assigned to the user directly, or through their roles. +- **`$NOW`** — The current timestamp. +- **`$NOW()`** - The current timestamp plus/minus a given distance, for example `$NOW(-1 year)`, `$NOW(+2 hours)`. + ## Layouts +Layouts are customized mechanisms for viewing and interacting with the items in a collection. You can [select a layout](/content/layouts) for displaying your collection. Note that restrictions will apply depending on your collection's [data model](/data-modeling/collections). + ## Batch Editing -## Layout Presets + + +By selecting more than one item in the explorer will allow you to click on :icon{name="material-symbols:filter-list} and edit several items' fields at once to have the same value. + +## Bookmarks + + + +Bookmarks are custom views for your collections that include specified configurations, layouts, visible fields, sorting, filtering and more. + +To create a bookmark, navigate to the Settings -> Bookmarks module. Here, you can create a new one by clicking on :icon{name="material-symbols:add-circle-outline-rounded"}. -## Access Control +You'll see the "Editing Preset" form, where you can set the name and collection, amongst layout and other values for this bookmark. Note that leaving the name field empty will make it so this bookmark is what is viewed for this collection by default. +The item editor is a tailored form for managing individual items and their field values. ## Fields & Data Model - - +You can add fields to items by [configuring the collection's data model](/data-modeling/fields). Here, you can also configure how the fields are displayed in the item editor. ## Creating Items +To create an item, click :icon{name="material-symbols:add-circle-outline-rounded"} in the page header to open the item page. + +Fill in the fields as desired. Note that some of these will be [marked as required](/data-modeling/fields) and need to be filled in, or be dynamic fields. Relations will be filled in here, too. + +::callout{type="info" title="Singletons"} + +If the collection is configured as a [singleton](/data-modeling/collections) in the data model +settings, the App will automatically open the item page when selecting the collection. + +:: + ## Duplicating Items - + + +When editing an item, you can click on :icon{name="material-symbols:more-vert"} to select some advanced options, amongst them "Save as Copy". Selecting this will save a copy. ## Archiving Items - +To archive an item, follow these steps, navigate to the content module and select the desired collection. Select the desired item to open the item editor. Click :icon{name="material-symbols:archive"} located in the header and a popup will appear to confirm the action. + +Archived items will not show up in search results or be returned in API responses. They still exist and can be retrieved using specific queries. Archiving can therefore be seen as a form of "soft deleting" an item. + +::callout{type="info" title="Requires Configuration"} + +Archiving requires an [archive field](/data-modeling/collections) to be configured within the collection's data model +settings. + +:: ## Revisions + + +As you update field values on items, Directus saves these revisions, and they can be compared side-by-side to the current state. + +To revert an item, navigate to the content module and select the desired collection and select the desired item. Click on "Revisions" in the editor sidebar and then on the revision you wish to preview. Go to "Revisions Made" in the side menu and view the revision differences. Click :icon{name="material-symbols:settings-backup-restore"} to revert the item's values and return to the item page. + +::callout{type="info" title="Revision Preview"} + +You will also see a "Revision Preview" button in the side menu navigation, which will let you preview all the item's +values for that revision. + +:: + +::callout{type="info"} + +You can also revert items [programmatically via the API](/api-reference/system/revisions). + +::: + ## Comments + + +You can add comments to items in the sidebar by clicking on "Comments", which will show the form for submitting one. You can use the @ button to tag specific users in your comment. + ## Shares + + +You can create shareable links to view an item in the sidebar by clicking on Shares -> New Share. + +Here, you can specify the name, password, roles allowed to access the item, as well as the start and end dates for the link's validity, followed by the maximum times a link can be used. + +To share the link, click on the new share's :icon{name="material-symbols:more-horiz"} and select either "Copy Link" or "Send Link". You can also edit or destroy the share in this menu. + ## Next Steps - +Learn how to use [content versioning](/content/content-versioning) and the [live preview](/content/live-preview) functionality. diff --git a/content/3.content/3.layouts.md b/content/3.content/3.layouts.md index 17a1d1bb..d5380b45 100644 --- a/content/3.content/3.layouts.md +++ b/content/3.content/3.layouts.md @@ -1,7 +1,249 @@ --- -description: +description: Learn to use layouts for viewing and interacting with items in a collection using Directus. --- # Layouts - +Layouts are customized mechanisms for viewing and interacting with the items in a collection. + +## Adjust a Collection's Layout + + + +To adjust an item's layout, navigate to the content and select the collection you wish to work with. In the page sidebar, click on "Layout Options". Then you can choose the desired layout type you want to use and customize it accordingly. + +Layouts are tailored to work with specific data-models. For example, in order to work properly, the map layout requires +the collection have a map field configured and the calendar layout requires the collection have a datetime field configured. + +Each layout presents data differently, so certain customizations may not be functional with certain layouts. For example, +the map layout displays each item as a pin on a map, so this layout has no controls for sorting. + +Depending on the layout, the same control may be under layout options in the sidebar, the subheader, or on the page area +(and items themselves). For example, the table layout lets you set the field values displayed in the subheader while +the card layout lets you set field values displayed in the layout options menu. + +### Customization Controls + +Customization controls can be found in the following three locations: + +- **Layout Options** — Located in the sidebar. +- **Subheader** — Located just below the page header and above the page area. +- **Page Area** — The center of the webpage, which displays all items. + +These controls typically fall into three general categories. + +| Category | Description | +|------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| Styling and Formatting | These are additional customizations to the way a layout displays such as the size of each Item, how images are cropped, etc. | +| Field Values Displayed | Most layouts allow you to choose which field value(s) are used to represent each item on the collection page. For example, with blog posts, it may be ideal to have the hero image, blog title, date, author, etc. | +| Manual and Automatic Sorting | Certain layouts may allow sorting items by value in ascending and descending order, drag-and-drop repositioning of items, etc. | + +## Table Layout + + + +This layout displays items in a tabular form, making it compatible with all kinds of items. This is the default +layout used in the content module. + +### Layout Options + +| Control | Description | +| --------------- | ----------------------------------------- | +| **Spacing** | Adjust the vertical space a row takes up. | + +### Subheader + +| Control | Description | +| -------------------------------- | ----------------------------------------------------------------------------------------------------------------------- | +| **Adjust Column Width** | Click and drag the column divider to resize as desired. | +| **Add Field** | Select :icon{name="material-symbols:add-circle-outline-rounded"} in the page subheader and select the desired Field(s). | +| **Remove Field** | Select :icon{name="material-symbols:arrow-drop-down-circle"} in the column title and click **"Hide Field"**. | +| **Sort Items by Column** | Select :icon{name="material-symbols:arrow-drop-down-circle"} in the column title and sort ascending or descending. | +| **Set Text Alignment** | Select :icon{name="material-symbols:arrow-drop-down-circle"} in the column title and set left, right, or center. | +| **Toggle & Reorder Columns** | Click the column header, then drag-and-drop as desired. | +| **Select All** | Click :icon{name="material-symbols:check-box-outline"} in the selection column header. | + +### Page Area + +| Control | Description | +| --------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- | +| **Select Item(s)** | Click :icon{name="material-symbols:check-box-outline"} in the selection column for the desired Item(s). | +| **Manually Sort Items** | Toggle :icon{name="material-symbols:check-box-outline"} in the configured Sort column to drag and drop :icon{name="material-symbols:drag-handle"} Items. | + +::callout{type="info" title="Manual Sorting Requires Configuration"} + +Only available if you [configure a sort field](/data-modeling/collections) in the collection's data model +settings. + +:: + +## Card Layout + + + +This tiled layout is ideal for collections that prioritize an image. This is the default +for both the user directory and +file library. It includes the following controls. + +### Layout Options + +| Control | Description | +|---|---| +| **Image Source** | Set the field used as the display image. | +| **Title** | Sets a display template to use as a title. | +| **Subtitle** | Sets a display template to use as a subtitle. | +| **Image Fit** | Set how an image fits inside the card. | +| **Fallback Icon** | Set a default icon to display when an item has no image. | + +### Subheader + +| Control | Description | +|---|---| +| **Card Size** | Toggle the card size as it appears in the page area. | +| **Order Field** | Click to select the field you wish to order by from the dropdown menu. | +| **Order Direction** | Toggle ascending and descending order. | +| **Select All** | Click ":icon{name="material-symbols:check-circle"} Select All" in the selection column header. | + + +### Page Area + +| Control | Description | +|---|---| +| **Select Item(s)** | Click ":icon{name="material-symbols:radio-button-unchecked"} in the selection column for the desired item(s). | + + +## Calendar Layout + + + +This layout is ideal for collections with time-oriented data (e.g. events and appointments). + +### Layout Options + +| Control | Description | +|---|---| +| **Display Template** | Set a mix of field values and text to represent items on the calendar. | +| **Start Date Field** | Choose field to determine each item's beginning time on the calendar. | +| **End Date Field** | Choose field to determine each item's ending time on the calendar. | +| **First Day of The Week** | Defines the beginning of the week on the calendar. | + +### Subheader + +| Control | Description | +|---|---| +| **Toggle Month and Year** | Move across time using the chevrons in the subheader. | +| **Today** | Click to jump to the current date on the calendar. | +| **Month Week Day List** | Adjust the time interval used to display items in the page area. | + +### Page Area + +| Control | Description | +|---|---| +| **Select Item** | Click an item on the calendar to open its item page. | + +::callout{type="info" title="Configuration Requirements"} + +To use this layout, the collection will need at least one datetime [Field](/data-modeling/fields) to set a start time, +but ideally two datetime Fields (to set a start time and end time). + +:: + +## Map Layout + + + +This layout is ideal for collections that emphasize geospatial data. It provides a world map, with items displayed as +points, lines, and other geometry. + +### Layout Options + +| Control | Description | +|---|---| +| **Basemap** | Choose the map provider used for the collection. | +| **Geospatial Field** | Select the geospatial field type to display on screen: | +| **Display Template** | Choose the fields displayed when hovering over an item on the map. | +| **Cluster Nearby Data** | Toggle whether or not nearby items get clustered into a single pin. | + + +### Subheader + +There is no Subheader on the Map Layout. + +### Page Area + +| Control | Description | +|---|---| +| **Zoom** | Click :icon{name="material-symbols:add"} and :icon{name="material-symbols:remove"} in the upper left hand corner of the page area to zoom in and out. | +| **Find my Location** | Click :icon{name="material-symbols:my-location"} to zoom into your current location on the map. | +| **Reframe** | Click the square in the upper left-hand corner to resize and reframe the map area. | +| **Select Item** | Click a single item to enter its item page. | +| **Select Items** | Click and drag to select multiple items at once, opening the item page. | + +::callout{type="info" title="Configuration Requirements"} + +To use this Layout, the collection must have a map field configured. + + + +:: + +## Kanban Layout + + + +This layout is ideal for collections that serve as project management tools or to-do lists, where each item represents a +task, because it groups items onto columns according to their status (e.g. "Not Started", "In Progress", "Under +Review", "Complete", or any other status defined). + +### Layout Options + +| Control | Description | +|---|---| +| **Group By** | Select the field used to define item status. See below for details. | +| **Card Title** | Choose the field use to serve as the title for each kanban board. | +| **Card Text** | Choose a field to display additional text on each item. | + +### Layout Options > Advanced + +| Control | Description | +|---|---| +| **Card Tags** | Choose a tag field to be displayed on the item. | +| **Card Date** | Choose a datetime field to be displayed on each item. | +| **Card Image** | Choose an image field to be displayed on each item. | +| **Card Image Fit** | Toggle whether the image fit is cropped. | +| **Card User** | Choose the user created field to display their avatar in the bottom right corner. | +| **Show Ungrouped** | Toggle display of a column containing Items with no assigned status. | + +### Subheader + +There is no Subheader for the Kanban Layout. + +### Page Area + +| Control | Description | +|---|---| +| **Create Task and Assign Status** | Click :icon{name="material-symbols:add"} in a status column and the item page will open. | +| **Sort Panels** | Drag and drop items to reposition or change task status. | +| **Add Status Panel** | Click :icon{name="material-symbols:add-box"} and add a group name (i.e. new status column). | +| **Edit or Delete Status Column** | Click :icon{name="material-symbols:more-horiz"} and then click :icon{name="material-symbols:edit"} to edit or :icon{name="material-symbols:delete"} to delete. | + +::callout{type="info" title="Configuration Requirements"} + +To make this layout work, you will need to configure an appropriate status [field](/data-modeling/fields) on the +collection, then identify this field under "Group By" in the Layout Options menu. + +:: diff --git a/content/3.content/4.import-export.md b/content/3.content/4.import-export.md index 9109122c..a29aa2f3 100644 --- a/content/3.content/4.import-export.md +++ b/content/3.content/4.import-export.md @@ -1,7 +1,63 @@ --- -description: +description: Learn to import and export multiple items stored as files using Directus. --- # Import & Export - +The content module allows importing and exporting of multiple items from and to files respectively. + +## Import Items + + + +You can import JSON or CSV files into your collection as items. + +To import Items from a file, navigate to the collection and click "Import / Export" in the sidebar. Click into the import search box. A file browser will open. Once a file has been selected, click on "Start Import" to import the items. + +The items will now be in the collection, and the file itself will not be stored in the Directus project. + +::callout{type="warning"} + +The field headers in the imported file must match the field keys of the collection you're importing into. Otherwise, the column will be skipped. + +:: + +::callout{type="info" title="Importing Relational Files"} + +It is possible to import relational field values as well. For this task, the user performing the import will need access +permissions for the related collection. + +:: + +## Export Items + + + +When exporting items, the export items menu provides granular control over exactly which items and +fields are exported, how they are exported, and where they are exported. + +To export items, follow the steps below, navigate to the desired collection and select "Import / Export" from the sidebar. Click on "Export Items" and the export items menu will appear. Select the desired format from CSV, JSON, XML, or YAML and click :icon{name="material-symbols:download-for-offline"} to download the file. + +## Export Items Menu + + + +This menu provides granular control over exactly which items and fields are exported, how they are exported, and where +they are exported. + +| Item | Description | +|---|---| +| **Format** | Choose to export items as CSV, JSON, XML, or YAML. | +| **Limit** | Set the maximum number of items to be exported. | +| **Export Location** | Download the export file directly to your machine or to the file library. | +| **Folder** | Choose the Folder to download to (if export location is the folder library). | +| **Sort Field** | Choose field to sort items by. | +| **Sort Direction** | Choose to sort items in ascending or descending order. | +| **Full-Text Search** | Limit exported Items to ones which matched as search results. | +| **Filter** | Limit exported items with a filter. | +| **Fields** | Add, remove, and re-order the item fields that will be exported. | diff --git a/content/3.content/5.live-preview.md b/content/3.content/5.live-preview.md index dbbf000e..deb69696 100644 --- a/content/3.content/5.live-preview.md +++ b/content/3.content/5.live-preview.md @@ -1,5 +1,43 @@ --- -description: +description: Learn to set up your project for live previewing items from your application. --- # Live Preview + +Live preview allows you to show changes in your website collection before publishing and without the need to refresh the browser. + +## Configure a Live Preview URL + + + +Navigate to Settings -> Data Model and select the collection you wish to configure. In the "Preview URL" section, specify the Preview URL for your project by selecting the field you wish to use to identify your object in your application from the dropdown and entering a URL in this format: +`http://your-website-url/` + +### Using Live Preview with Your Application + +Once configured, Directus will send a request to your application for a page with the specified URL format. For example, if you've configured the URL to be `https://mysite.com/posts/{id}`, and load the preview for the item with the an `id` of `42`, then your application will receive a request to `https://mysite.com/posts/42`. You may choose to add `preview=true` to indicate to your client that it needs to treat this as a live preview. You may also choose to add an access token with the ability to view items as an additional URL query parameter. + +You can then develop your application to handle that request and return a page that shows a preview of the item requested. + +::callout{type="warning" title="Using Live Preview with Static Site Generators"} + +If you're using a static site generator to preview your item data, be sure to develop it to render the item page on load as opposed to on build. Otherwise, it will only show the state of the item when the site itself was last built. + +:: + +::callout{type="info" title="Using Live Preview with Content Versioning"} + +If you've enabled [content versioning](/content/content-versioning), you can pass the version identifier to your live preview URL. + +:: + +## Previewing Item Contents in the Editor + +In an item page, toggle "Enable Preview" at the top of the page. Whenever you create or edit an item in your collection +and “click” save, you should see a live preview of the item on the right-hand side of the screen. + + + +Clicking on :icon{name="material-symbols:devices"} also lets you preview your content on desktop and mobile screens, while :icon{name="material-symbols:open-in-new"} allows you to pop the live preview out into a separate window. diff --git a/content/3.content/6.content-versioning.md b/content/3.content/6.content-versioning.md index 91f2c4be..fe967fed 100644 --- a/content/3.content/6.content-versioning.md +++ b/content/3.content/6.content-versioning.md @@ -1,5 +1,73 @@ --- -description: +description: This guide covers the process of enabling and utilizing Content Versioning in Directus. --- # Content Versioning + +Content versioning allows teams to create and manage different versions of their content. There are several reasons to +use content versioning, including drafting content without publishing it, and more ways to collaborate effectively. + +## Concepts + +- **Version**: A version of an item is a snapshot that gets copied from the current or `main` version, allowing you to safely make changes and later promote to be the main version. Any changes to the main version made in the meantime are updated automatically. +- **Main**: the main version is the original version of a piece of content that has been created. It is the default version that is displayed to users. The main version is the "source of truth" for all other versions. This is often used for published content. +- **Promote**: promoting a version means to make it the new main version. When a new version is promoted, it becomes the main version that is displayed to users, and it replaces the previous main version. + + +::callout{type="info" title="Using Versions in Live Preview" url="/content/live-preview"} + +The version field is a dynamic variable can be added to the live preview URL so you can preview a specific version of an item. Check out more about live previews. + +:: + +## Setting Up Content Versioning + + + +Navigate to **Settings** > **Data Model**, select the collection that you want to enable content versioning for, and scroll down to the content versioning section. Toggle "Enable Versions" and save your data model. + +## Creating a New Version + + + +Open an item within your versioned collection. At the top of the item view, you will notice a dropdown with the main Content Version displayed as "main". Select "Create Version" and provide a key and a name for the new version. You can then save your new version. + +::callout{type="info" title="Version Source"} + +All new versions originate from the main version. This implies that the main version acts as the single source of truth +for other versions. + +:: + +## Making Changes to a Version + + + +Open the item in the newly created version, and make the desired edits to the item's content. + +Upon saving the changes, you'll notice that the main version remains unaffected, while the changes are reflected only in the modified version. + +## Reviewing and Promoting a Version + + + +Promoting a version will turn it into the main version. + +Open the version you want to promote and select the "Promote Version" option from the dropdown. In the "Changes" tab, you can review the changes made for each field in the version and decide which field's changes to accept or reject. Switch to the "Preview" tab to see a preview of the changes you are about to promote. + +After promoting a version, you can choose to keep or delete the version. + +::callout{type="info" title="Programmatically Implement Content Versioning"} + +You have the option to integrate Content Versioning through the API. To learn how to accomplish this, please refer to +our [API reference documentation](/api-reference/system/versions). + +:: + +## Revisions and Content Versioning + +Under the hood, content versions are stored in the `directus_revisions` collection. In bigger projects this collection +can get large. + +This can be mitigated by periodically removing some or all data in this collection. Note that this could +unintentionally remove some content versions. diff --git a/content/3.content/7.translations.md b/content/3.content/7.translations.md index 2ee49634..db2bff40 100644 --- a/content/3.content/7.translations.md +++ b/content/3.content/7.translations.md @@ -1,5 +1,69 @@ --- -description: +description: Both content and the data studio can be translated into multiple languages. --- # Translations + +Localising content in Directus involves using translation strings, which are multilingual key-value pairs that you can use throughout the app. They enable you to translate things like dropdown options, placeholder text, field notes, and more. + + + +::callout{type="info" title="Data Studio Translations"} + +This article refers to translating your content in Directus. Many parts of the Data Studio are already translated into multiple languages via community contribution on Crowdin. + +:: + + +## Create a Translation String + + + +To create a translation string, navigate to Settings > Translation Strings and click on :icon{name="material-symbols:add-circle-rounded"} in the page header and a drawer will open. + +Add a key and click on "Create New" to open another drawer. Select the language and type in the corresponding translation. Click on :icon{name="material-symbols:check-circle"} to confirm and add the translation. + +## Use a Translation String + + + +Throughout the settings module, you will notice certain input fields have a :icon{name="material-symbols:translate"} icon on them, meaning you have the option assign a translation string. + +To assign a translation string, navigate to the input that you'd like to add a translation string to. There are two ways to assign a translation string: + +- Click :icon{name="material-symbols:translate"} and a dropdown menu with all translation strings will appear. +- Type `$t:translation-string-key` and hit enter. + +Choose a translation string key as desired. + +::callout{type="info" title="Switching Language"} + +There are two ways to change the app language. Administrators can set the project's +[default language](/configuration/translations), while users can choose their own personal +language preference. + +:: + +::callout{type="info" title="Adding New Translation Strings"} + +You can also click ":icon{name="material-symbols:add-circle-rounded"} New Translation String" in the :icon{name="material-symbols:translate"} dropdown menu to create a new translation string on the fly. + +:: + +## Content Translations + + + +With Directus, you can localize your content into several languages using a [translations field](/data-modeling/relationships) on a given collection. + +Once this field is added to a collection, a few new collections will be created. One being a pre-populated `languages` collection, as well as a hidden `_translations` collection. + +In the "Data Model" section of the settings module, navigate into the `_translations` collection and add the fields which you'd like to translate. + +Now, when [editing an item](/content/editor) of that collection, you'll be able to add translations for those fields.