Page tree
Skip to end of metadata
Go to start of metadata

In this unit you get to see how to set up a project and what data you need to supply during the process. 

Why is this important?

Knowing how to work with bootstrap files is a core development skill and is one of the project setup best practices that help to ensure long-term project health. You should also know when to use XML files and when to work with YAML files - a new configuration mechanism.

Scenario

Who?

A developer with a Magnolia International partner wants to add some configuration to a module. The configuration is from another Magnolia project that uses the same module. She has been sent an .xml file from a colleague and needs to add it to her project.

Option

There are two ways she can add the config -

  1. In a running instance she can import the config into the relevant module, publish the changes and (if the changes are not immediate) restart the server.
  2. She can add the files to her project using bootstrapping.

Solution

The developer opts to add the configuration using bootstrapping.

Why?

Because this way she avoids the risk of versioning issues. As a rule it is better to add config as bootstrap files into the project at build time rather than use the import function in a running instance. 

Viewing bootstrap files

You can see the bootstrap files for all of the Magnolia modules by going to http://git.magnolia-cms.com/gitweb/ and navigating the tree of each file.

Bootstrap file functionality

What is bootstrapping?

Bootstrapping allows you to quickly add configuration files to a project. In addition, bootstrapping ensures that the configuration necessary to run the modules can be imported into any other Magnolia instance.

What is the file format for bootstrap files?

Bootstrap files are always .xml files that comply with the JCR system. Do not rename any bootstrap files produced when you compile your project; the file name determines where the configuration is applied. In this example the workspace is config, the location is modules; the name of the module is Pages - 

config.modules.pages.xml

Bootstrap files in modules

Where do bootstrap files go?

Bootstrap files go in the mgnl-bootstrap folder - this can be at webapp or individual module level.

 

How do I export bootstrap files from Magnolia?

Right click on the relevant node and select 'export'.

When exporting bootstrap files directly from within Magnolia (such as module configuration) do not export complete trees; export individual configuration items. This helps to ensure that multiple developers can work on the same module without creating conflicts. When importing config files directly into a live instance via the configuration app, you may need to restart the server for the changes to take effect.

YAML

One of the latest features in Magnolia is 'configuration by file'. We developed this to make it easier for non-Java developers to create templates in Magnolia. Configuration by file eliminates the need to need to use an IDE. With this new functionality came a new configuration export mechanism - download YAML files. Existing app and template configuration can now be converted to YAML for ease of distribution.

We looked at this in Hello Magnolia - No IDE and also in MTE.


Why download configuration as a YAML file and not export as an XML file?
 

  •  Download to YAML is for working in the file system rather than in the Magnolia repository - this makes it ideal for team collaboration as.  YAML based configuration is easier to diff and easier to share with other developer.
  • Exporting to XML is typically done in order to take a backup of configuration, share it with your colleagues or to bootstrap configuration. Importing config is a good 'on the fly' solution in live projects.

Exercise

Casual

Requires a running instance of Magnolia

  1. Navigate to Standard Templating Kit module in your running instance of Magnolia.
  2. Export  the configuration for templates > components > content > stkHTML
  3. Open the xml file and note that:

    • the file name defines the workspace and path where the xml will be bootstrapped to;
    • config is reflected in the content of the bootstrap file;
    • metadata (such as creation date, mod date, activation status etc.) is not displayed in the tree view in the config app, but is displayed in the xml file.

Learn more

Official Documentation

Next unit

Storing and deploying modules.

  • No labels

1 Comment