the slick yaml based configuration by file in magnolia 5.4

THE SLICK, YAML-BASEDCONFIGURATION BY FILE IN MAGNOLIA 5.4

#mconf15 Basel, 11 June 2015

Photo Credit:

Mikaël Geljić

SENIOR SOFTWARE ENGINEERMAGNOLIA

@mikaelgeljic

SPECIAL STAGESConfiguration by File, the story The new configuration (framework) YAML format and integration Demo

#registries #definitions #configSources #YAML

CONFIGURATION BY FILE THE STORY

Photo Credit:

THE MASTER PLANMagnolia 5.4, a release for developers Overarching stories:

- Configure by file (or code) - Trouble-free and safe configuration - Develop sites without knowing Java - Streamline working with resources

#easeOfDevelopment #lightModules

"LIGHT MODULES"Maven module <maven-module-name>/ ├── pom.xml └── src/ └── main/ ├── java/ └── resources/ ├── META-INF/ │ └── magnolia/ │ └── module-name.xml └── <module-name>/ ├── apps/ ├── dialogs/ │ └── myDialog.yaml ├── resources/ └── templates/ ├── components/ │ ├── myComponent.ftl │ └── myComponent.yaml └── pages/ ├── myTemplate.ftl └── myTemplate.yaml

Light module ${magnolia.resources.dir}/└── <module-name>/ ├── apps/ ├── dialogs/ │ └── myDialog.yaml ├── resources/ └── templates/ ├── components/ │ ├── myComponent.ftl │ └── myComponent.yaml └── pages/ ├── myTemplate.ftl └── myTemplate.yaml

Photo Credit:

WHY CONFIG BY FILE?Hassles with JCR config

Lengthily crafted in the Configuration app verbose raw JCR exports: bootstrap files "persisted flavor of config"

- painful while developing (merge changes, wipe repo) - painful to upgrade, version-handlers

CONFIG BY FILEA lean, readable format: YAML Ease of editing Config files next to template scripts, all in one place File observation, instant changes Easier collaboration for dev teams (diff, no import/export) Greater validation capabilities

Photo Credit:

DATE FIELD CONFIG, BOOTSTRAP FILE

DATE FIELD CONFIG, YAML FILE

THE NEW CONFIGURATION(FRAMEWORK)

Photo Credit:

REGISTRIES IN MAGNOLIACollect various types of elements in the system

- e.g. templates, dialogs, apps

Up to 5.3 - no common ancestor, all duplicated! - paired with so-called (observing) managers - knows nothing if bean resolution fails

REGISTRY OUTLOOK (5.3)

JCR

Managers

Node2Bean

Registries

Server config

Modules config

JCR Config app

💩

💩

REGISTRY OUTLOOK (5.4)

JCR

Configuration Sources

File

Node2Bean

Registries

Server config

Modules config

Code

{}

Map2Bean

Config app

THE REGISTRY API

Registry - type() - metadataBuilder() - register() - getProvider()

info.magnolia.config.registry

Metadata id, module, location

DefinitionProvider bean, isValid

Raw view map representation

DEFINITION ID (STRATEGIES)Reference string glueing definitions together

- e.g. in template dialog: mte:components/textImage

Two approaches module + relativePath

- e.g. for templates, dialogs - <sample-module>:pages/article

name - e.g. for apps, field-types - pages, assets

Sample Registry impl@Singleton public class FieldTypeDefinitionRegistry extends AbstractRegistry<FieldTypeDefinition> {

@Override public DefinitionType type() { return DefinitionTypes.FIELD_TYPE; }

@Override public DefinitionMetadataBuilder newMetadataBuilder() { return DefinitionMetadataBuilder.usingNameAsId(); } }

THE CONFIGURATION SOURCEReplaces old managers Binds itself to a Registry ConfigurationSourceFactory

• JCR / YAML default binding settings (conventions)

e.g. in module start configSourceFactory.yaml().bindWithDefaults(dialogRegistry);

MINISTER OF REGISTRIESRegistryFacade Query definitions by module, source or type Guice multi-bindings to the rescue

RegistryFacade

info.magnolia.config.registry

TemplateRegistry DialogRegistry AppRegistry

THE CONFIG OVERVIEW APP

SHOWTIMEPhoto Credit:

SHOWTIMEPhoto Credit:

YAML FORMAT AND INTEGRATION

Photo Credit:

YAML: THE SPECyaml.org/spec/1.1/ indentation over enclosure marks scalars, sequences, mappings

key : valuetitle : Magnolia 5.4year : 2015boolean : true

F1Teams: - Ferrari - Williams - Lotus

subApps: browser: class: (...) actions: addItem : (...) editItem: (...) imageProvider: class: (...)

INTEGRATION WITH CONFIGCollect "resources" by matching pattern

- e.g. <module>/<deftype>/<relPath>/<name>.yaml

NamedDefinition - name property is inferred from file name - may still be overridden in file - e.g. <module>/apps/resources.yaml

Map2Bean

YAML VS. JCRYAML JCR

Map2Bean Node2Bean

bean instantiation as per target-types, class property, type-mappings

!include, references, merge keys extends

sequences, mappings nodes/sub-nodes for both lists/maps

LISTS VS. MAPS

public interface TabDefinition { List<FieldDefinition> getFields();}

fields: - name: title class: info.magnolia.ui.form.field.definition.TextFieldDefinition - name: text class: info.magnolia.ui.form.field.definition.RichTextFieldDefinition

Photo Credit:

LISTS VS. MAPS

public interface DialogDefinition { Map<String, ActionDefinition> getActions();}

actions: commit: class: info.magnolia.ui.admincentral.dialog.action.SaveDialogActionDefinition cancel: class: info.magnolia.ui.admincentral.dialog.action.CancelDialogActionDefinition

Photo Credit:

ADVANCED YAMLdocument references

- same document only

browser contentConnector: &contentConnector implementationClass: info.magnolia.resources.app.ResourcesContentConnector detail: contentConnector: *contentConnector

ADVANCED YAMLmerge keys

- good for appending - not suited for merging nested structures

fields: - &codeField name: content class: info.magnolia.ui.form.field.definition.CodeFieldDefinition fileNameProperty: name height: 500 - <<: *codeField readOnly: true

MODULARIZING YAML FILESThe !include directive

- Magnolia-specific, at YAML-reader level - caters to external file reference

columns: - name: name class: info.magnolia.ui.workbench.column.definition.PropertyColumnDefinition - !include /resources-app/generic/column/originName.yaml

THE JOURNEY ONLY BEGINSUpdated selected registries so far

- renderers, templates - dialogs, apps, fieldTypes, mediaeditors, messageViews

Will move more typical configurations to registries - e.g. appLauncherLayout, server config

Will productize and bundle the Config Overview app How about auto-suggest?

THANK YOU! QUESTIONS?

Photo Credit:

@mikaelgeljic

#mconf15 Basel, 11 June 2015