--- group: Intro title: Beta Features weight: 200 --- Static CMS runs new functionality in an open beta format from time to time. That means that this functionality is totally available for use, an it might be ready for primetime, but it could break or change without notice. **Use these features at your own risk.** ## i18n Support The CMS can provide a side by side interface for authoring content in multiple languages. Configuring the CMS for i18n support requires top level configuration, collection level configuration and field level configuration. ### Top level configuration ```yaml i18n: # Required and can be one of multiple_folders, multiple_files or single_file # multiple_folders - persists files in `//.` # multiple_files - persists files in `/..` # single_file - persists a single file in `/.` structure: multiple_folders # Required - a list of locales to show in the editor UI locales: [en, de, fr] # Optional, defaults to the first item in locales. # The locale to be used for fields validation and as a baseline for the entry. defaultLocale: en ``` ```js i18n: { /** * Required and can be one of multiple_folders, multiple_files or single_file * multiple_folders - persists files in `//.` * multiple_files - persists files in `/..` * single_file - persists a single file in `/.` */ structure: 'multiple_folders', // Required - a list of locales to show in the editor UI locales: ['en', 'de', 'fr'], /** * Optional, defaults to the first item in locales. * The locale to be used for fields validation and as a baseline for the entry. */ defaultLocale: 'en' }, ``` ### Collection level configuration ```yaml collections: - name: i18n_content # same as the top level, but all fields are optional and defaults to the top level # can also be a boolean to accept the top level defaults i18n: true ``` ```js collections: [ { name: 'i18n_content', /** * same as the top level, but all fields are optional and defaults to the top level * can also be a boolean to accept the top level defaults */ i18n: true }, ], ``` When using a file collection, you must also enable i18n for each individual file: ```yaml collections: - name: pages label: Pages # Configure i18n for this collection. i18n: structure: single_file locales: [en, de, fr] files: - name: about label: About Page file: site/content/about.yml # Enable i18n for this file. i18n: true fields: - { label: Title, name: title, widget: string, i18n: true } ``` ```js collections: [ { name: 'pages', label: 'Pages', // Configure i18n for this collection. i18n: { structure: 'single_file', locales: ['en', 'de', 'fr'] }, files: [ { name: 'about', label: 'About Page', file: 'site/content/about.yml', // Enable i18n for this file. i18n: true, fields: [ { label: 'Title', name: 'title', widget: 'string', i18n: true } ], }, ], }, ], ``` ### Field level configuration ```yaml fields: - label: Title name: title widget: string # same as 'i18n: translate'. Allows translation of the title field i18n: true - label: Date name: date widget: datetime # The date field will be duplicated from the default locale. i18n: duplicate - label: Body name: body # The markdown field will be omitted from the translation. widget: markdown ``` ```js fields: [ { label: 'Title', name: 'title', widget: 'string', // same as 'i18n: translate'. Allows translation of the title field i18n: true }, { label: 'Date', name: 'date', widget: 'datetime', // The date field will be duplicated from the default locale. i18n: 'duplicate' }, { label: 'Body', name: 'body', // The markdown field will be omitted from the translation. widget: 'markdown' }, ], ``` Example configuration: ```yaml i18n: structure: multiple_folders locales: [en, de, fr] collections: - name: posts label: Posts folder: content/posts create: true i18n: true fields: - label: Title name: title widget: string i18n: true - label: Date name: date widget: datetime i18n: duplicate - label: Body name: body widget: markdown ``` ```js i18n: { structure: 'multiple_folders', locales: ['en', 'de', 'fr'] }, collections: [ { name: 'posts', label: 'Posts', folder: 'content/posts', create: true, i18n: true, fields: [ { label: 'Title', name: 'title', widget: 'string', i18n: true }, { label: 'Date', name: 'date', widget: 'datetime', i18n: 'duplicate' }, { label: 'Body', name: 'body', widget: 'markdown' }, ], }, ], ``` ### Limitations 1. File collections support only `structure: single_file`. 2. List widgets only support `i18n: true`. `i18n` configuration on sub fields is ignored. 3. Object widgets only support `i18n: true` and `i18n` configuration should be done per field: ```yaml - label: 'Object' name: 'object' widget: 'object' i18n: true fields: - { label: 'String', name: 'string', widget: 'string', i18n: true } - { label: 'Date', name: 'date', widget: 'datetime', i18n: duplicate } - { label: 'Boolean', name: 'boolean', widget: 'boolean', i18n: duplicate } - { label: 'Object', name: 'object', widget: 'object', i18n: true, field: { label: 'String', name: 'string', widget: 'string', i18n: duplicate }, } ``` ```js { label: 'Object', name: 'object', widget: 'object', i18n: true, fields: [ { label: 'String', name: 'string', widget: 'string', i18n: true }, { label: 'Date', name: 'date', widget: 'datetime', i18n: 'duplicate' }, { label: 'Boolean', name: 'boolean', widget: 'boolean', i18n: 'duplicate' }, { label: 'Object', name: 'object', widget: 'object', i18n: true, field: { label: 'String', name: 'string', widget: 'string', i18n: 'duplicate' }, }, ], }, ``` ## Folder Collections Path See [Folder Collections Path](/docs/collection-types#folder-collections-path). ## Nested Collections Seed [Nested Collections](/docs/collection-types#nested-collections). ## Custom Mount Element Static CMS always creates its own DOM element for mounting the application, which means it always takes over the entire page, and is generally inflexible if you're trying to do something creative, like injecting it into a shared context. You can now provide your own element for Static CMS to mount in by setting the target element's ID as `nc-root`. If Static CMS finds an element with this ID during initialization, it will mount within that element instead of creating its own. ## Commit Message Templates You can customize the templates used by Static CMS to generate commit messages by setting the `commit_messages` option under `backend` in your Static CMS `config`. Template tags wrapped in curly braces will be expanded to include information about the file changed by the commit. For example, `{{path}}` will include the full path to the file changed. Setting up your Static CMS `config` to recreate the default values would look like this: ```yaml backend: commit_messages: create: Create {{collection}} "{{slug}}" update: Update {{collection}} "{{slug}}" delete: Delete {{collection}} "{{slug}}" uploadMedia: Upload "{{path}}" deleteMedia: Delete "{{path}}" ``` ```js backend: { commit_messages: { create: 'Create {{collection}} "{{slug}}"', update: 'Update {{collection}} "{{slug}}"', delete: 'Delete {{collection}} "{{slug}}"', uploadMedia: 'Upload "{{path}}"', deleteMedia: 'Delete "{{path}}"', }, }, ``` Static CMS generates the following commit types: | Commit type | When is it triggered? | Available template tags | | ------------- | ---------------------------- | ----------------------------------------------------------- | | `create` | A new entry is created | `slug`, `path`, `collection`, `author-login`, `author-name` | | `update` | An existing entry is changed | `slug`, `path`, `collection`, `author-login`, `author-name` | | `delete` | An existing entry is deleted | `slug`, `path`, `collection`, `author-login`, `author-name` | | `uploadMedia` | A media file is uploaded | `path`, `author-login`, `author-name` | | `deleteMedia` | A media file is deleted | `path`, `author-login`, `author-name` | Template tags produce the following output: - `{{slug}}`: the url-safe filename of the entry changed - `{{collection}}`: the name of the collection containing the entry changed - `{{path}}`: the full path to the file changed - `{{message}}`: the relevant message based on the current change (e.g. the `create` message when an entry is created) - `{{author-login}}`: the login/username of the author - `{{author-name}}`: the full name of the author (might be empty based on the user's profile) ## Image widget file size limit You can set a limit to as what the maximum file size of a file is that users can upload directly into a image field. Example config: ```yaml - label: 'Featured Image' name: 'thumbnail' widget: 'image' default: '/uploads/chocolate-dogecoin.jpg' media_library: config: max_file_size: 512000 # in bytes, only for default media library ``` ```js { label: 'Featured Image', name: 'thumbnail', widget: 'image', default: '/uploads/chocolate-dogecoin.jpg', media_library: { config: { max_file_size: 512000 // in bytes, only for default media library }, }, }, ``` ## Summary string template transformations You can apply transformations on fields in a summary string template using filter notation syntax. Example config: ```yaml collections: - name: 'posts' label: 'Posts' folder: '_posts' summary: "{{title | upper}} - {{date | date('YYYY-MM-DD')}} - {{body | truncate(20, '***')}}" fields: - { label: 'Title', name: 'title', widget: 'string' } - { label: 'Publish Date', name: 'date', widget: 'datetime' } - { label: 'Body', name: 'body', widget: 'markdown' } ``` ```js collections: [ { name: 'posts', label: 'Posts', folder: '_posts', summary: "{{title | upper}} - {{date | date('YYYY-MM-DD')}} - {{body | truncate(20, '***')}}", fields: [ { label: 'Title', name: 'title', widget: 'string' }, { label: 'Publish Date', name: 'date', widget: 'datetime' }, { label: 'Body', name: 'body', widget: 'markdown' }, ], }, ], ``` The above config will transform the title field to uppercase and format the date field using `YYYY-MM-DD` format. Available transformations are `upper`, `lower`, `date('')`, `default('defaultValue')`, `ternary('valueForTrue','valueForFalse')` and `truncate()`/`truncate(, '')` ## Registering to CMS Events You can execute a function when a specific CMS event occurs. Example usage: ```javascript CMS.registerEventListener({ name: 'prePublish', handler: ({ author, entry }) => console.info(JSON.stringify({ author, data: entry.data })), }); ``` Supported events are `prePublish`, `postPublish`, `preSave` and `postSave`. The `preSave` hook can be used to modify the entry data like so: ```javascript CMS.registerEventListener({ name: 'preSave', handler: ({ entry }) => { return entry.data.set('title', 'new title'); }, }); ``` ## Dynamic Default Values When linking to `/admin/#/collections/posts/new` you can pass URL parameters to pre-populate an entry. For example given the configuration: ```yaml collections: - name: posts label: Posts folder: content/posts create: true fields: - label: Title name: title widget: string - label: Object name: object widget: object fields: - label: Title name: title widget: string - label: body name: body widget: markdown ``` ```js collections: [ { name: 'posts', label: 'Posts', folder: 'content/posts', create: true, fields: [ { label: 'Title', name: 'title', widget: 'string' }, { label: 'Object', name: 'object', widget: 'object', fields: [ { label: 'Title', name: 'title', widget: 'string' } ], }, { label: 'body', name: 'body', widget: 'markdown' }, ], }, ], ``` clicking the following link: `/#/collections/posts/new?title=first&object.title=second&body=%23%20content` will open the editor for a new post with the `title` field populated with `first`, the nested `object.title` field with `second` and the markdown `body` field with `# content`. **Note:** URL Encoding might be required for certain values (e.g. in the previous example the value for `body` is URL encoded).