This page is a starting point for discussion around nicer JCR exports, and exchanging JCR content (in particular templates, definitions, configs, resources) between magnolia instances.
JCR Text export
One of the problems facing templaters, and to some extent also java developers when working with magnolia is that the repository content can't be managed via SCM. You can check it into SCM in the form of XML exports, but they don't compare well so you essentially have to treat them as binary files.
A possible idea to help mitigate this would be to export not to XML, but a more line oriented text format. An added benefit would be smaller exported file sizes. I have some code that does just that:
Developer sync module
I'm working on a module that can import / export and compare content in an "intelligent" way, meaning it has knowledge about the JCR formats of common magnolia "artifacts" like templates, resources, template definitions, etc...
The module can export / import these artifacts to / from the filesystem in a way that leads to a "human readable" representation of the JCR content, while preserving all JCR data.
More information on this as I progress. Feel free to comment and / or contribute.
Phase 1 will produce a version 1.0.0 release with the following features:
- ability to define "packages" in module config (node2bean)
- packages consist of a "left artifact source" and a "right artifact source"
- as well as one or more "roots" defined by a workspace name, a path and a "artifact flavour"
- possible artifact sources will be:
- JCR source (artifacts are read from/written to JCR)
- Filesystem source (artifacts are read from/written to filesystem files and folders, using a text format for nodes/properties and extra files for binary content or template/resource content)
- "artifact flavours" will include:
- Default - just text nodes, split into separate files at mgnl:content / mgnl:folder nodes --> should be good for definitions, dialogs
- Resource - text nodes and text files or binary files for resource content, split at mgnl:content / mgnl:folder nodes
- Template - text nodes and text ftl files for template content, split at mgnl:content / mgnl:folder nodes
- Automatic - chooses the best flavour automatically for you by analyzing JCR
- Simple UI
- an app: "Developer Sync"
- subapp: "Packages" - lists the configured packages, lets you choose one to synchronize
- subapp: "Sync Results" - shows the results of a sync operation as a list of conflicts / differences
- conflicts need to be resolved before sync can proceed - usually to do with UUID problems
- differences can be exported/imported (copied from left to right or vice versa)
- sync operation can be repeated
Phase 1 is in development. Phase 1 features are validated in the sense that I have had this working before, and it is a matter of recoding an improved version and a magnolia 5 UI.
Export format to filesystem is as follows:
- Basic unit of export is a text file with extension .node
- The text file will contain the text representation of the artifact's JCR data, including any sub-nodes that are part of the same artifact
- Normally the file name will equal the JCR node name of the exported artifact with the extension '.node' added, but may be modified to legal character constraints imposed by the file system
- Some artifacts may consist of further files, for example a template would include a freemarker (.ftl) file, with the same filename and ".ftl" extension. So a template called "home" might result in the files:
- If an artifact has children artifacts there will be a folder with the same name, that folder will contain the children (using the same representation)
This format will be:
- human readable
- easily editable with your favorite editors
- perfect for checking into SCM
Phase 2 will be about fixing bugs and adding some quick win features, if easily possible, to produce a quick 1.5 release.
Phase 2 features envisioned:
- See if the DAV2JCR bridge servlet thing can be easily integrated, and add a RemoteJCRArtifactSource --> direct sync between magnolia instances (very cool!)
- UI: Add a compare view/subapp to compare the node and text files (validated, I had this working before, just need to create magnolia 5 UI for it)
- UI: Display roots under packages in Packages sub-app, allow syncing of individual roots
- DAM (mgnl:asset)
- Website (mgnl:page)
- "Export Text" / "Import Text" as generally available action
- TextBootstrapSingleResourceTask --> module bootstrapping from text files, yay!
Phase 3 will work towards a 2.0 release, and will take more time. Focus will be on fixing (even small) bugs, rounding out existing features, and most importantly collecting user feedback for improvements - thereby turning the module into something lots of people actually use!
Feedback, as always, is appreciated!