This page describes how to use the Stories app, an example of a custom content editor that authors can use to quickly create and publish flexible content in Magnolia.
Use the Stories app to create and edit stories on a Magnolia author instance. Complete the structured outline to give the story a set of key static properties. Then, build up the unstructured body of your story using content blocks you want: images, texts, videos and links. You can save and publish in one click to get your content on your website fast.
Compared to pages, stories are ideal for quickly producing free-form content without any page-hierarchy constraints. Stories, with a clear distinction between formatting and content, can then be published to different destinations: from a web page to a mobile app or as an article for an online newspaper.
Stories app is a feature available only in DX Core.
You create stories in the Stories app.
You can organize your stories by adding folders. To add a new story, click Add story.
If you have the Magnolia demo modules installed, the Stories app contains some sample blogposts to show what you can do with the Stories app. Without the demo modules, the Stories app does not contain any content by default.
In the demo, the Stories app has been decorated (
/travel-demo-stories-app/decorations/stories-app/apps/stories.yaml) to extend the default functionality described on this page. The customization of the Stories app mainly introduces two new blocks,
When you create a new story, it provides the title and lead text fields as well as several collapsible multi-field sections where you can fill in some key properties.
By default, the outline consists of the following fields and collapsible sections:
Title* - The title of the story.
Lead text* - The lead text for the story.
Lead visual - Collapsible section where you can select the Embed, Image or Video visual option:
For the Embed option, you can embed HTML code and add an asset as an Alternate image.
For the Image option, you can select an asset from the Assets chooser dialog and add Alt text.
For the Video option, you can select a video asset from the Assets chooser dialog and add another asset as an Alternate image.
In all cases, you can add a Caption and Credits.
Author - Collapsible section where you can add:
Author profile image with Assets chooser.
Author short bio - A text field with a maximum of 300 characters.
Author lives in - For the location of the author.
Related content - Collapsible section where you can add a list of related stories.
Dates & URL - Collapsible section where you can add:
Story created on*
Story updated on
URL slug - Used as the name of the story and in the URL. If you leave this field empty, the URL slug is automatically generated from the story’s Title when you first save the story.
Mandatory fields are indicated by an asterisk.
Once you have completed the outline, you can add, reorder and delete content blocks to suit your requirements.
See the shortcuts below to work even faster.
Magnolia provides the following block types out-of-the-box:
Content from another website
The following two are provided by the Travel Demo:
To add blocks to your story, click the plus icon in your story to expand the Block chooser menu and select the block type you want.
The … Others option at the bottom of the menu opens the Block chooser dialog.
The types of block available may vary depending on what your development team has configured.
To delete a block, click the trash icon to the right of the block or use the backspace shortcut.
Add text blocks to write paragraphs or headings. Each paragraph or heading must be a separate text block. To enter a line break within a block, press Shift+Enter. If you press Enter while typing, a new text block is created at the cursor position.
You can format the text and insert or remove links to external content or to Magnolia items using the formatting bar displayed when you are editing a text block.
If you apply a header style to text in a block, the entire block becomes a heading.
If you paste text from another source into a text block, all formatting is removed. If you paste several paragraphs at the same time, multiple corresponding blocks are created.
When you are typing in a text block, press Enter to add a new text box.
If you insert links in a text block:
The list of apps with content you can link to may vary depending on what your development team has configured.
Add image or video blocks to select an existing asset or upload a new one.
Click browse to open the Assets chooser dialog and select an asset for your story or upload a new one. You can also add image-related or video-related metadata.
Use the Embedded content block to embed content from another external website. This block type uses link unfurling: it scans the URL you enter for metadata and provides a preview in the story. For example, this YouTube link displays a thumbnail preview, title and lead text:
The preview displayed for external links depends on the metadata the site owner embedded in their web page header.
When you have finished writing your story, you can directly click Save and publish at the bottom of the story. Alternatively, you can select a story in the workbench and click Publish. The publication process and statuses are explained here.
You must publish any assets you use in your stories separately.
The Stories app does not provide any default page or component templates to render the stories. The templates to render the stories must be configured by your development team.
You can see an example of published stories in the Magnolia demo.
The Stories app supports a few keyboard shortcuts to speed up content editing.
Tab key to select the next block and, after pressing the key again, to enter the edit mode in the selected block.
Esc key functions as a toggle key for block select and block edit modes.
Internationalization (i18n) of content is not supported in the
2.0.x versions of the Content Editor module and its Stories app submodule.
The feature will only be enabled in version
2.1. Until it is released for production-ready use, you cen test it out in version
2.1-beta. This version is available on Magnolia Nexus under the following coordinates:
<dependency> <groupId>info.magnolia.editor</groupId> <artifactId>content-editor-parent</artifactId> <version>2.1-beta</version> </dependency>
Before adding this beta into your webapp, you must remove the bundled version of the module.
The data model for the internationalized Content Editor stories is different in the beta version. Whereas in
mgnl:block elements are stored in a flat node structure,
stories └── story1 ├── 0 └── 1
in the i18n-supported version, the nodes are locale-nested under intermediate nodes of type
custom in this example:
stories └── story1 └── custom_de │ ├── 0_de │ └── 1_de └── custom ├── 0 └── 1
This must be reflected in your
MultiJcrBlockDefinition, where you need to add and enable the
Instead of the
CompatibleBlockProvider is set as the default provider, which can resolve both flat and nested block nodes. You do not need to declare it in your block definition.
- Example definition
custom: label: Blocks $type: multiJcrBlock i18n: true blocks: - text
This applies only to the
There are two ways you can migrate the non-i18n blocks to the i18n-compatible hierarchy: using a version handler or a Groovy script.
When upgrading the Stories app submodule to version
2.1 once available), all block nodes in the
stories workspace will be moved to intermediate nodes, see the
You can run the migration task in the Groovy app, especially in case a block node is stored in another workspace.
- Example Groovy script
import info.magnolia.editor.setup.MigrateBlockToIntermediateParentTask import info.magnolia.module.InstallContextImpl import info.magnolia.module.ModuleRegistryImpl import info.magnolia.objectfactory.Components import javax.jcr.Session Session session = MgnlContext.getJCRSession("stories"); task = new MigrateBlockToIntermediateParentTask("stories", "/", "custom"); task.execute(Components.newInstance(InstallContextImpl.class)); session.save();
The parameters in the
stories- workspace name
custom- name of the intermediate node, the name of the
multiJcrBlockfield, see https://git.magnolia-cms.com/projects/ENTERPRISE/repos/content-editor/browse/stories-app/src/main/resources/stories-app/apps/stories.yaml#555.
Editing and publishing aspects