# Configuration
A bolt extension that adds complex configuration settings, either globally or as a field type inside a contenttype.
The editor used is [ jdorn/json-editor https://github.com/jdorn/json-editor]. Extensive information on schema
and available options can be found on it's GitHub page.

## Global Configurations 
The configuration for the global version (below the men entry **Extend/Configuration**) is done in the extensions's 
configuration yml file under app/config/extensions/configuration.cnd.yml.

Each available configuration block consists of these parameters:
 * **label** the displayed label for this configuration block
 * **icon** a FontAwesome icon class
 * **description** A short description of this configuration block
 * **permissions** A list of user roles, that have read and/or write access on this configuration
 * **schema** A filepath to a valid json schema. This path has to be relative to the extensions config folder (ex: app/config/extensions)
 * **options** A set of key/value pairs that will be passed to the json-editor
 
**Sample**
```
data:

    config-one:
        label: Config One
        icon: fa-trash
        description: A very brief description about this beautiful bucket
        permissions:
            read:     [ admin, developer, chief-editor, editor ]    # See all configuration data
            write:    [ admin, developer, chief-editor ]            # Update existing configuration data
        schema: schema/sample.json
        options:
            hello: world

    config-two:
        label: Config Two
        icon: fa-suitcase
        description: A very brief description about this yet another slightly less beautiful bucket
        permissions:
            read:     [ admin, developer, chief-editor, editor ]    # See all configuration data
            write:    [ admin, developer, chief-editor ]            # Update existing configuration data
        schema: schema/sample.json
 
```
 
## FieldType Configurations 
The configuration for the fieltype version is done inside your contenttype.yml.

The field can have these parameters in addition to the usual field parameters: 
 * **schema** A filepath to a valid json schema. This path has to be relative to the extensions config folder (ex: app/config/extensions)
 * **options** A set of key/value pairs that will be passed to the json-editor
 
**Sample**
```
articles:
    name: Artikel
    singular_name: Artikel
    fields:
        title:
            type: text
            class: large
        myconfig:
            type: configuration
            schema: schema/myconfig.yml
            options:
                something: special
```

## Special field type lookup
This special field is used for finding content from internal or external sources. 
An URL must be provided and an optional data block containing URL parameters that 
will always be submitted to the request url.

**Sample**
```
{
  "properties": {
    "location": {
      "type": "object",
      "title": "World City",
      "properties": {
        "category": {
          "type": "lookup",
          "url": "/bolt/extend/configuration/async/taxonomy/categories"
        },
        "relatedarticle": {
          "type": "lookup",
          "url": "/bolt/extend/configuration/async/content/find",
          "data": {
            "contentTypes": ["articles", "cities"]
          }
        }
    }
  }
}
```

The object "Wolrd City" has two properties, a category (bolt taxonomy) and a related article field (bolt content-type from the content.yml).

Taxonomies: 
    * The category, gets content from the taxonomy storage of Bolt. 
    * The extension comes with a predefined url for the different 
      taxonomies: /bolt/extend/configuration/async/taxonomy/{taxonomy-type}
      where {taxonomy-type} is a taxonomy name defined in your taxonomy.yml

Content:
    * The extension also provides an URL, that delivers a Content, filtered by
      a search parameter and a contentTypes parameter, that is defined in the YML schema.  
    * The additional url parameters are to be found within the data property of the lookup definition.
    
When you edit the field, you will find out that after saving, the data that has been saved, is actually a 
JSON string, containing the ID, Label and an Image representing the chosen item form the dropdown list. 
Wherever you need the saved data, you first need to parse the string in order to be able to use it. 
This structure is a result of the simple rule, that the JSON-editor saves properties as simple key:value pairs. 
In order to save intensive Backend communication on initialising numerous lookup fields, the extension saves 
the additional data as a JSON-string.

## Creating your own asyncronious (ajax) data endpoints. 
The extension calls the provided url, passing only a search parameter, containing the string that the user has typed in, and 
the parameters defined in the data section of the the field definition. In this case contentTypes[]=articles&contentTypes=cities

**Sample**
```
...
        "relatedarticle": {
          "type": "lookup",
          "url": "/bolt/extend/configuration/async/content/find",
          "data": {
            "contentTypes": ["articles", "cities"]
          }
        }
...

```

The backend should return data in the following format:

```
{
    "page": {
        "total": INT, 
        "limit": INT,
        "offset": INT
    },
    "items" : [
        // External image
        {
            "id": "xxxxxx",
            "label": "Label",
            "image": "http://subdomain.domain/path/to/image"
        },
        // Internal Image 
        {
            "id": "yyyyyy",
            "label": "Label other",
            "image": "/files/path/to/image"
        }
    ]
}

```