This talk was given by Mikael Geljic, Magnolia, at Magnolia Conference 2015 in Basel, Switzerland. With Magnolia, it is easy to forget configuration changes you make in the tree. When you forget to export them into XML and check into version control, they are not part of the software development lifecycle and get lost. This talk will show how we rethought configuration for Magnolia 5.4, and how we made it easier and more transparent. We now enable developers to provide configuration by file, from their module or webapp, while also allowing them to see every definition that is registered in the system, whether it comes from files, JCR or code. This allows for better teamwork and smoother developer workflow, resulting in more agile deployment.

1. THE SLICK, YAML-BASED
CONFIGURATION BY FILE
IN MAGNOLIA 5.4
#mconf15
Basel, 11 June 2015
Photo Credit:

2. Mikaël
Geljić
SENIOR SOFTWARE
ENGINEER
MAGNOLIA
@mikaelgeljic

3. SPECIAL STAGES
Configuration by File, the story
The new configuration (framework)
YAML format and integration
Demo
#registries #definitions #configSources #YAML

4. CONFIGURATION BY FILE
THE STORY
Photo Credit:

5. THE MASTER PLAN
Magnolia 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

6. "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

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

8. CONFIG BY FILE
A 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:

9. DATE FIELD CONFIG, BOOTSTRAP FILE

10. DATE FIELD CONFIG, YAML FILE

11. THE NEW CONFIGURATION
(FRAMEWORK)
Photo Credit:

12. REGISTRIES IN MAGNOLIA
Collect 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

13. REGISTRY OUTLOOK (5.3)
JCR
Managers
Node2Bean
Registries
Server
config
Modules
config
JCR Config
app
💩
💩

14. REGISTRY OUTLOOK (5.4)
JCR
Configuration Sources
File
Node2Bean
Registries
Server
config
Modules
config
Code
{}
Map2Bean
Config app

15. THE REGISTRY API
Registry
- type()
- metadataBuilder()
- register()
- getProvider()
info.magnolia.config.registry
Metadata
id, module, location
DefinitionProvider
bean, isValid
Raw view
map representation

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

17. 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();
}
}

18. THE CONFIGURATION SOURCE
Replaces old managers
Binds itself to a Registry
ConfigurationSourceFactory
• JCR / YAML default binding settings (conventions)
e.g. in module start
configSourceFactory.yaml().bindWithDefaults(dialogRegistry);

19. MINISTER OF REGISTRIES
RegistryFacade
Query definitions by module, source or type
Guice multi-bindings to the rescue
RegistryFacade
info.magnolia.config.registry
TemplateRegistry DialogRegistry AppRegistry

20. THE CONFIG OVERVIEW APP

21. SHOWTIME
Photo Credit:

22. SHOWTIME
Photo Credit:

23. YAML FORMAT AND INTEGRATION
Photo Credit:

24. YAML: THE SPEC
yaml.org/spec/1.1/
indentation over enclosure marks
scalars, sequences, mappings
key : value
title : Magnolia 5.4
year : 2015
boolean : true
F1Teams:
- Ferrari
- Williams
- Lotus
subApps:
browser:
class: (...)
actions:
addItem : (...)
editItem: (...)
imageProvider:
class: (...)

25. INTEGRATION WITH CONFIG
Collect "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

26. YAML VS. JCR
YAML 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

27. 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:

28. 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:

29. ADVANCED YAML
document references
- same document only
browser
contentConnector: &contentConnector
implementationClass: info.magnolia.resources.app.ResourcesContentConnector
detail:
contentConnector: *contentConnector

30. ADVANCED YAML
merge 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

31. MODULARIZING YAML FILES
The !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

33. THE JOURNEY ONLY BEGINS
Updated 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?

34. THANK YOU!
QUESTIONS?
Photo Credit:
@mikaelgeljic
#mconf15
Basel, 11 June 2015