JCR browser

JCR browser is a Magnolia tool that allows you to view and edit content and associated configuration at the repository level. It allows you to see details that are not readily visible in a specific app's treeview.

A JCR browser displays the content of one workspace at a time. A JCR browser for the website workspace is preconfigured. You can configure a custom JCR browser to display any workspace.

The Configuration app is essentially a JCR browser that displays the config workspace. This is where configuration for Magnolia core and all modules is stored. Configuration specific to Magnolia core is in the server folder. Modules store their configuration in the modules folder.

Website JCR browser

The website JCR browser is accessible in Tools > JCR. The browser shows the content as it is stored in the JCR and is useful for looking at details that you would not see in the Pages app.

The website workspace contains pages, areas and components, and is organized according to the site hierarchy.

• Pages:
  
  • Each page of the site is stored in a folder and page folders have a hierarchical structure.
  • There are content nodes for each area of the page. These are subnodes of the page and all reside at the same level, regardless of whether they are configured as main or nested areas.
  • Page properties reside in property nodes under the page node.
• Areas:
  
  • If an area contains components, there are component subnodes under the area node.
  • Area properties, if any, reside under the area content node.
• Components:
  
  • Each component within an area node has a numbered content node. These nodes display in the same order as on the page. The nodes are numbered sequentially and numbers assigned automatically. The number assigned to a component depends on when the component was created. Therefore, the rendering order may not match the numbering order.  
  • Component properties reside under the component content node.
  • Components that have nested components follow the same structure as area nodes. This coincides with the component definition configuration.

Here's a comparison of the /demo-project/news-and-events/news-overview/news03 on the page and in the JCR. Only two components, the Page Header component in the intro area and Text and Image component in content area, have been added on the page.

• Folder news03 is the page node. It contains area nodes and page properties. The folder tree hierarchy above it is the same as you would see in the Pages app treeview: /demo-project/news-and-events/news-overview.
• The /content area node contains a single stkTextImage news component starting with the words "The main part of news...". The property node names match the field names configured in the stkTextImage dialog in STK > Dialog Definitions /components/content/stkTextImage/form/tabs/tabText/fields.
• All other areas nodes are empty because this news page doesn't have other components, besides inherited ones.
• The data in the page property nodes come from two sources:
  
  • The hideInNav setting is from the  stkNewsProperties properties dialog. The node name matches the corresponding field configured in STK > Dialog Definitions /pages/news/stkNewsProperties.
  • The other page properties are from the stkNewsInfo intro dialog. The node names match the corresponding fields configured in STK > Dialog Definitions /pages/news/stkNewsIntro. The Page Header component is considered part of the page. For more information see intro area.

Editing in the Website JCR browser

You can edit and add content in the JCR browser, but should always do this with caution because you are working a repository level. In some cases, the browser offers a quicker alternative to working in the page editor in the Pages app. There are also certain things that you can do in the browser that are not possible in the editor. Here are a few suggestions:

• Add multiple similar components to a page. Select a component in the browser and execute the Duplicate item action. This saves the time and effort of adding the components from scratch in the editor. You can then amend the duplicates in the editor or the browser. 
• Add the same component to multiple pages. Duplicate a component on page 1 and then drag the duplicate to the same area content node on page 2 or more.

While it is possible to move components from one page area to another, this is not the best practice solution. For seamless publishing your page content should always comply with the options available in the template.

Publishing in the Website JCR browser

Publishing in the Website JCR browser is different from publishing in the Pages app:

• When you publish a page in the JCR Browser, only the page and its properties are published. 
• When you publish a page in the Pages app, the page and ALL its children (properties, areas, components) are published.

Configuring a custom JCR browser

You can configure a JCR browser to display any Magnolia workspace. The most efficient way is to extend the Configuration app and change important properties. This is how the websiteJcrBrowser is configured. You can find these configurations at /modules/ui-admincentrral/apps/configuration and /websiteJCRBrowser.

In Magnolia 5.3+ the nodes and properties discussed below are configured in the content connector definition (contentConnector node) and in Magnolia 5.2+ they are configured in the workbench definition (workbench node).

Important nodes and properties to note and possibly change:

• workspace: Set this property to the workspace you want to browse.

nodeTypes: Define the node types to display in the browser. Each type has it's own configuration node. Add and change node types and behavior as necessary.

• The configuration app works on mgnl:conentNode and mgnl:content node types,
• All JCR browsers by default skip properties starting with jcr: and mgnl:. This is not configurable.
• Most apps define custom node types, for example mgnl:contact, mgnl:asset and mgnl:category.
• To display binary content under jcr:content, for example for the imaging workspace, add mgnl:resource node type.
• Setting the node type to nt:base is extremely dangerous because it enables editing of jcr:system, jcr:versionStorage etc. nodes. This can ruin the workspace completely.
• strict: This property is configured per node type. In the Configuration app it is set to true for both mgnl:conentNode and mgnl:content to prevent node subtypes displaying in list and tree view. In the websiteJcrBrowser configuration it is reversed (set to true) in order to display mgnl;page, mgnl:area and mgnl:component subtypes. Use this property to suit your circumstances.
• includeProperties: Defines whether to display property nodes. In the Configuration app this property is set to true. Set it to false to hide properties in the browser. mgnl:created and mgnl:lastModified properties are filtered (not displayed) regardless of the setting.
• includeSystemNodes: 5.3.2+ 5.2.7 + Default is false. Displays nodes used by the system such as nodes internal to the operations of the JCR implementation. Use this property with caution. It is only required to configure a browser for the dam and imaging workspaces.
• label: Labels cannot be loaded from a message bundle when you extend an app. It is necessary to manually add label properties. See MAGNOLIA-5562 - Getting issue details... STATUS and Adding labels for more.

Configuration example: Contacts JCR browser

This example below shows you how to adapt the websiteJcrBrowser configuration to browse the contacts workspace. You can download the contactsJcrBrowser configuration XML (download 5.3, download 5.2) and import it instead of configuring from scratch.

In /modules/ui-admincentral/apps duplicate the websiteJcrBrowser node and rename it contactsJcrBrowser. Both websiteJcrBrowser and the new contactsJcrBrowser extend the the configuration app.

In 5.3 the workspace property and node type configuration moved from the workbench definition to the content connector definition.

Configuring the content connector in 5.3+

To configure the content connector in 5.3+ in /contactsJcrBrowser/subapps/browser/contentConnector:

1. Change the  /workspace property to contacts.
2. In /nodeTypes/mainNodeType add a name property and set it to mgnl:contact.

Configuring the workbench in 5.2+

To configure the workbench in 5.2+ in /contactsJcrBrowser/subapps/browser/workbench:

1. Change the  /workspace property to contacts.
2. In /nodeTypes/mainNodeType add a name property and set it to mgnl:contact.

Configuring actions

In the Configuration app, the addNode action operates on the mgnl:contentNode node type. See Action availability for more.

To ensure that the addNode action works correctly for mgnl:contact node types in /contactsJcrBrowser/subapps/browser:

1. Add an actions content node with an extends property set to /modules/ui-admincentral/apps/configuration/subApps/browser/actions.
2. Under actions, add an addNode content node with a nodeType propety set to mgnl:contact.

Configuring the action bar

Like the addNode action, the nodes group in the action bar in the Configuration app is available for mgnl:contentNode node types. See Action bar availability for more.

To ensure that the nodes action is available for mgnl:contact node types in /contactsJcrBrowser/subapps/browser/actionbar/

1. Add an extends property and set the value to /modules/ui-admincentral/apps/configuration/subApps/browser/actionbar.
2. Under /sections add a nodes/availability/nodeTypes content node structure with an arbitrarily named property with the value set to mgnl:contact.

Adding labels

Add the following label properties (with supporting content nodes, where required) in /modules/ui-admincentral/apps/contactsJcrBrowser:

1. /label. Displays in the menu in the app launcher. You can also optionally add an icon property set to icon-jcr-app to render the icon in the tile. See Icons for a list of icon names.
2. /subapps/browser/label. Displays above the workbench.
3. /subapps/browser/actionbar/sections:
   
   1. /root/label = Contacts. Displays when no node is selected.
   2. /properties/label = Property. Displays when a property is selected.
   3. /nodes/label = Content node. Displays when a content node is selected.
   4. /folders/label = Folder. Displays when a folder is selected.
   5. /multiple/label=Multiple Items. Displays when multiple mixed items, for example property and content node, are selected.

Adding to the app launcher

Add the new app to the app launcher. In /modules/ui-admincentral/config/appLauncherLayout/groups/tools/apps/ add a new node named contactsJCRBrowser. You can add it to another group if you like.

Viewing the results

Refresh the app launcher. You can do so by adding the restartApplication request-parameter to the URL or refreshing your browser.

Here's the new Contacts JCR Browser.

Configuration example: DAM node types

This example shows you how to configure node types in the  5.3+ content connector and 5.2+ workbench to browse the dam workspace. The purpose is to demonstrate node types in the DAM. It is not a fully usable example because assets can only be uploaded in the Assets app. But, you can for example, use it to view and amend properties.

The example adapts the websiteJcrBrowser configuration to browse the dam workspace.

In /modules/ui-admincentral/apps duplicate the websiteJcrBrowser node and rename it damJcrBrowser. Both websiteJcrBrowser and the new damJcrBrowser extend the the configuration app.

Configuring the content connector in 5.3+

See DAM workspace structure for more about dam node types, Icons for a list of icon names and Configuring a custom JCR browser above for a description of each property..

To configure the content connector in 5.3+ in /damJcrBrowser/subapps/browser/contentConnector:

1. Properties:
   
   1. Change the  /workspace property to dam.
   2. Change the /includeSystemNodes property to true.
   3. Add an /includeProperties property and set it to true.
2. NodeTypes:
   
   1. Delete the nodeTypes/mainNodeType and /folderNodeType nodes. We will add replacement nodes.
   2. Add three content nodes, assetNodeType, folderNodeType and assetResourceNodeType, each with icon, name and strict properties. Set the values as shown below.

Configuring the workbench in 5.2+

See DAM workspace structure for more about dam node types, Icons for a list of icon names and Configuring a custom JCR browser above for a description of each property..

To configure the workbench in 5.2+ in /damJcrBrowser/subapps/browser/workbench:

1. Properties:
   
   1. Change the  /workspace property to dam.
   2. Change the /includeSystemNodes property to true.
   3. Add an /includeProperties property and set it to true.
2. NodeTypes:
   
   1. Delete the nodeTypes/mainNodeType and /folderNodeType nodes. We will add replacement nodes.
   2. Add three content nodes, assetNodeType, folderNodeType and assetResourceNodeType, each with icon, name and strict properties. Set the values as shown below.

Here's the DAM JCR browser after configuring actions and the actionbar, and  adding label properties as demonstrated in the Contacts example above.