static-cms/website/content/docs/beta-features.mdx

---
group: Configuration
title: Beta Features!
weight: 200
---
We run new functionality in an open beta format from time to time. That means that this functionality is totally available for use, and we *think* it might be ready for primetime, but it could break or change without notice.

**Use these features at your own risk.**

## Working with a Local Git Repository

You can connect Static CMS to a local Git repository, instead of working with a live repo.

1. Navigate to a local Git repository configured with the CMS.
2. Add the top-level property `local_backend` configuration to your `config.yml`:

```yaml
backend:
  title: git-gateway

# when using the default proxy server port
local_backend: true
```

3. Run `npx @staticcms/proxy-server` from the root directory of the above repository.

   * If the default port (8081) is in use, the proxy server won't start and you will see an error message. In this case, follow [these steps](#configure-the-@staticcms/proxy-server-port-number) before proceeding.
4. Start your local development server (e.g. run `gatsby develop`).
5. Open `http://localhost:<port>/admin` to verify that your can administer your content locally. Replace `<port>` with the port of your local development server. For example Gatsby's default port is `8000`

**Note:** `@staticcms/proxy-server` runs an unauthenticated express server. As any client can send requests to the server, it should only be used for local development.

### Configure the Static CMS proxy server port number

1. Create a `.env` file in the project's root folder and define the PORT you'd like the proxy server to use

```ini
PORT=8082
```

2. Update the `local_backend` object in `config.yml` and specify a `url` property to use your custom port number

```yaml
backend:
  title: git-gateway

local_backend:
  # when using a custom proxy server port
  url: http://localhost:8082/api/v1
  # when accessing the local site from a host other than 'localhost' or '127.0.0.1'
  allowed_hosts: ['192.168.0.1']
```

## 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 `<folder>/<locale>/<slug>.<extension>`
  # multiple_files - persists files in `<folder>/<slug>.<locale>.<extension>`
  # single_file - persists a single file in `<folder>/<slug>.<extension>`
  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:
  - title: 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:
  - title: pages
    label: Pages
    # Configure i18n for this collection.
    i18n:
      structure: single_file
      locales: [en, de, fr]
    files:
      - title: about
        label: About Page
        file: site/content/about.yml
        # Enable i18n for this file.
        i18n: true
        fields:
          - { label: Title, title: title, widget: string, i18n: true }
```

### Field level configuration

```yaml
fields:
  - label: Title
    title: title
    widget: string
    # same as 'i18n: translate'. Allows translation of the title field
    i18n: true
  - label: Date
    title: date
    widget: datetime
    # The date field will be duplicated from the default locale.
    i18n: duplicate
  - label: Body
    title: body
    # The markdown field will be omitted from the translation.
    widget: markdown
```

Example configuration:

```yaml
i18n:
  structure: multiple_folders
  locales: [en, de, fr]

collections:
  - title: posts
    label: Posts
    folder: content/posts
    create: true
    i18n: true
    fields:
      - label: Title
        title: title
        widget: string
        i18n: true
      - label: Date
        title: date
        widget: datetime
        i18n: duplicate
      - label: Body
        title: 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'
  title: 'object'
  widget: 'object'
  i18n: true
  fields:
    - { label: 'String', title: 'string', widget: 'string', i18n: true }
    - { label: 'Date', title: 'date', widget: 'datetime', i18n: duplicate }
    - { label: 'Boolean', title: 'boolean', widget: 'boolean', i18n: duplicate }
    - {
        label: 'Object',
        title: 'object',
        widget: 'object',
        i18n: true,
        field: { label: 'String', title: 'string', widget: 'string', i18n: duplicate },
      }
```

## Folder Collections Path

By default the CMS stores folder collection content under the folder specified in the collection setting.

For example configuring `folder: posts` for a collection will save the content under `posts/post-title.md`.

You can now specify an additional `path` template (similar to the `slug` template) to control the content destination.

This allows saving content in subfolders, e.g. configuring `path: '{{year}}/{{slug}}'` will save the content under `posts/2019/post-title.md`.

## Folder Collections Media and Public Folder

By default the CMS stores media files for all collections under a global `media_folder` directory as specified in the configuration.

When using the global `media_folder` directory any entry field that points to a media file will use the absolute path to the published file as designated by the `public_folder` configuration.

For example configuring:

```yaml
media_folder: static/media
public_folder: /media
```

And saving an entry with an image named `image.png` will result in the image being saved under `static/media/image.png` and relevant entry fields populated with the value of `/media/image.png`.

Some static site generators (e.g. Gatsby) work best when using relative image paths.

This can now be achieved using a per collection `media_folder` configuration which specifies a relative media folder for the collection.

For example, the following configuration will result in media files being saved in the same directory as the entry, and the image field being populated with the relative path to the image.

```yaml
media_folder: static/media
public_folder: /media
collections:
  - title: posts
    label: Posts
    label_singular: 'Post'
    folder: content/posts
    path: '{{slug}}/index'
    media_folder: ''
    public_folder: ''
    fields:
      - label: Title
        title: title
        widget: string
      - label: 'Cover Image'
        title: 'image'
        widget: 'image'
```

More specifically, saving an entry with a title of `example post` with an image named `image.png` will result in a directory structure of:

```bash
content
  posts
    example-post
      index.md
      image.png
```

And for the image field being populated with a value of `image.png`.

**Note: When specifying a `path` on a folder collection, `media_folder` defaults to an empty string.**

**Available template tags:**

Supports all of the [`slug` templates](/docs/configuration-options#slug) and:

* `{{dirname}}` The path to the file's parent directory, relative to the collection's `folder`.
* `{{filename}}` The file name without the extension part.
* `{{extension}}` The file extension.
* `{{media_folder}}` The global `media_folder`.
* `{{public_folder}}` The global `public_folder`.

## List Widget: Variable Types

Before this feature, the [list widget](/docs/widgets/#list) allowed a set of fields to be repeated, but every list item had the same set of fields available. With variable types, multiple named sets of fields can be defined, which opens the door to highly flexible content authoring (even page building) in Static CMS.

**Note: this feature does not yet support default previews and requires [registering a preview template](/docs/customization#registerpreviewtemplate) in order to show up in the preview pane.**

To use variable types in the list widget, update your field configuration as follows:

1. Instead of defining your list fields under `fields` or `field`, define them under `types`. Similar to `fields`, `types` must be an array of field definition objects.
2. Each field definition under `types` must use the `object` widget (this is the default value for
   `widget`).

### Additional list widget options

* `types`: a nested list of object widgets. All widgets must be of type `object`. Every object widget may define different set of fields.
* `typeKey`: the name of the field that will be added to every item in list representing the name of the object widget that item belongs to. Ignored if `types` is not defined. Default is `type`.
* `summary`: allows customization of a collapsed list item object in a similar way to a [collection summary](/docs/configuration-options/?#summary)

### Example Configuration

The example configuration below imagines a scenario where the editor can add two "types" of content,
either a "carousel" or a "spotlight". Each type has a unique name and set of fields.

```yaml
- label: 'Home Section'
  title: 'sections'
  widget: 'list'
  types:
    - label: 'Carousel'
      title: 'carousel'
      widget: object
      summary: '{{fields.header}}'
      fields:
        - { label: Header, title: header, widget: string, default: 'Image Gallery' }
        - { label: Template, title: template, widget: string, default: 'carousel.html' }
        - label: Images
          title: images
          widget: list
          field: { label: Image, title: image, widget: image }
    - label: 'Spotlight'
      title: 'spotlight'
      widget: object
      fields:
        - { label: Header, title: header, widget: string, default: 'Spotlight' }
        - { label: Template, title: template, widget: string, default: 'spotlight.html' }
        - { label: Text, title: text, widget: text, default: 'Hello World' }
```

### Example Output

The output for the list widget will be an array of objects, and each object will have a `type` key
with the name of the type used for the list item. The `type` key name can be customized via the
`typeKey` property in the list configuration.

If the above example configuration were used to create a carousel, a spotlight, and another
carousel, the output could look like this:

```yaml
title: Home
sections:
  - type: carousel
    header: Image Gallery
    template: carousel.html
    images:
      - images/image01.png
      - images/image02.png
      - images/image03.png
  - type: spotlight
    header: Spotlight
    template: spotlight.html
    text: Hello World
  - type: carousel
    header: Image Gallery
    template: carousel.html
    images:
      - images/image04.png
      - images/image05.png
      - images/image06.png
```

## 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.

## Manual Initialization

Static CMS can now be manually initialized, rather than automatically loading up the moment you import it. The whole point of this at the moment is to inject configuration into Static CMS before it loads, bypassing need for an actual Static CMS `config.yml`. This is important, for example, when creating tight integrations with static site generators.

Manual initialization works by setting `window.CMS_MANUAL_INIT = true` **before importing the CMS**:

```js
// This global flag enables manual initialization.
window.CMS_MANUAL_INIT = true
// Usage with import from npm package
import CMS, { init } from '@staticcms/core'
// Usage with script tag
const { CMS, initCMS: init } = window
/**
 * Initialize without passing in config - equivalent to just importing
 * Static CMS the old way.
 */
init()
/**
 * Optionally pass in a config object. This object will be merged into
 * `config.yml` if it exists, and any portion that conflicts with
 * `config.yml` will be overwritten. Arrays will be replaced during merge,
 * not concatenated.
 *
 * For example, the code below contains an incomplete config, but using it,
 * your `config.yml` can be missing its backend property, allowing you
 * to set this property at runtime.
 */
init({
  config: {
    backend: {
      title: 'git-gateway',
    },
  },
})
/**
 * Optionally pass in a complete config object and set a flag
 *  (`load_config_file: false`) to ignore the `config.yml`.
 *
 * For example, the code below contains a complete config. The
 * `config.yml` will be ignored when setting `load_config_file` to false.
 * It is not required if the `config.yml` file is missing to set
 * `load_config_file`, but will improve performance and avoid a load error.
 */
init({
  config: {
    backend: {
      title: 'git-gateway',
    },
    load_config_file: false,
    media_folder: "static/images/uploads",
    public_folder: "/images/uploads",
    collections: [
      { label: "Blog", title: "blog", folder: "_posts/blog", create: true, fields: [
        { label: "Title", title: "title", widget: "string" },
        { label: "Publish Date", title: "date", widget: "datetime" },
        { label: "Featured Image", title: "thumbnail", widget: "image" },
        { label: "Body", title: "body", widget: "markdown" },
      ]},
    ],
  },
})
// The registry works as expected, and can be used before or after init.
CMS.registerPreviewTemplate(...);
```

## 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.yml`.

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.yml` 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}}”
```

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'
  title: '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:
  - title: 'posts'
    label: 'Posts'
    folder: '_posts'
    summary: "{{title | upper}} - {{date | date('YYYY-MM-DD')}} – {{body | truncate(20, '***')}}"
    fields:
      - { label: 'Title', title: 'title', widget: 'string' }
      - { label: 'Publish Date', title: 'date', widget: 'datetime' }
      - { label: 'Body', title: '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('<format>')`, `default('defaultValue')`, `ternary('valueForTrue','valueForFalse')` and `truncate(<number>)`/`truncate(<number>, '<string>')`  

## Registering to CMS Events

You can execute a function when a specific CMS event occurs.

Example usage:

```javascript
CMS.registerEventListener({
  title: '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({
  title: '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:
  - title: posts
    label: Posts
    folder: content/posts
    create: true
    fields:
      - label: Title
        title: title
        widget: string
      - label: Object
        title: object
        widget: object
        fields:
          - label: Title
            title: title
            widget: string
      - label: body
        title: 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).

## Nested Collections

Allows a folder collection to show a nested structure of entries and edit the locations of the entries.

Example configuration:

```yaml
collections:
  - title: pages
    label: Pages
    label_singular: 'Page'
    folder: content/pages
    create: true
    # adding a nested object will show the collection folder structure
    nested:
      depth: 100 # max depth to show in the collection tree
      summary: '{{title}}' # optional summary for a tree node, defaults to the inferred title field
    fields:
      - label: Title
        title: title
        widget: string
      - label: Body
        title: body
        widget: markdown
```

Nested collections expect the following directory structure:

```bash
content
└── pages
    ├── authors
    │   ├── author-1
    │   │   └── index.md
    │   └── index.md
    ├── index.md
    └── posts
        ├── hello-world
        │   └── index.md
        └── index.md
```