Magnolia 5.3 reached end of life on June 30, 2017. This branch is no longer supported, see End-of-life policy.
On this page we look at typical Magnolia URLs and learn how the fragment part of a URL makes location tracking possible. With fragments you can pinpoint detailed locations in the system. Users can bookmark their favorite apps, pages and nodes.
A typical AdminCentral URL in the Magnolia back end looks like this:
Parts of a URL:
A servlet responds to a request. Servlets are mapped in the servlet filter chain . By convention, a Magnolia servlet mapping starts with the dot character, for example
/.magnolia/admincentral for AdminCentral resources or
/.rest for REST resources.
A REST URL is a good example of complex servlet mapping. The URL requests the page
/demo-project/about. The servlet mapping part contains detailed information about the requested resource.
Parts of a servlet mapping:
magnoliarepository has the requested content.
#. In AdminCentral URLs, the fragment keeps track of an app's internal state. It identifies the name of the app, the subapp that is open, and optionally a path to the content that is operated on. In public URLs the fragment identifies an anchor.
The parts that come after the hash are separated from each other with a colon
:. The following fragment identifies the Contacts app . The detail subapp is currently open. The user is looking at version 1.0 of the node
Parts of a fragment:
appfor normal apps and
shellfor one of the three special Shell apps: App Launcher, Pulse and Favorites. For your own apps, this part will always be
favorite. Normal apps are also named in a predictable way: Pages is
pages, Assets is
assetsand so on. Magnolia uses the app name to identify the app across the system.
detail. In custom apps you can name your subapps as you want. Magnolia recommends that you name your main subapp
mainfor consistency. The
mainsubapp can be the only subapp if the app does not provide any other subapps.
Pulse shell app.
Pages app with the browser subapp open. The
/demo-project/about page is currently selected in the treeview.
Pages app with an detail subapp open. The
/demo-project/about page is being edited.
Pages app with a detail subapp open. The
/demo-project/about page is being previewed. The
view parameter instructs the app to display the page in preview mode.
The subapp ID part of the fragment holds the subapp’s name and optional parameters. Each subapp ID is unique within the app. This allows the system to recognize a tab that is already open and bring that tab into focus rather than open a duplicate. For example, when the Pages app opens a detail subapp it assigns the subapp a unique ID consisting of the subapp name (
detail ) and the path to the page (
/demo-project/about ). If the user already has the page open the app brings the tab into focus when it is requested.
A node path is the most common example of a parameter. The path identifies the node being viewed or edited, for example
/demo-project/about. The subapp ID and the node path are separated with a semicolon. We cannot use the colon character here as it would break the token.
Here is an example of custom parameters in the fragment. The Preview app is being used to preview personalized content.
previewPersonaassigns a persona who represents the target audience.
previewDateassigns a date.
Here's what the Preview app looks like in the browser.
A selector is a part of a URI between the first selector delimiter
~ (tilde) and the extension.
Selectors are similar to query parameters in that they allow you to pass information to a servlet. The difference is that a query parameter sends input to be processed whereas a selector describes how you want to receive the requested resource. In this respect selectors are like extensions. The extension
.html specifies that you want to receive the resource as an HTML document. Similary, the selector
~Culture~ specifies that you want a list of articles about culture. It is still the same resources (article list page) but instead of all articles you want it filtered by the category Culture.
For more on request parameters vs. selectors see Apache Sling Selectors and Request Parameters: Getting it Straight
Magnolia uses the tilde character
~ as a selector delimiter. In other systems such as Apache Sling you may see the dot character
. used as a delimiter. We can't use the dot in Magnolia because the JCR specification allows dots in node names, and consequently in URIs, with the single limitation that a dot cannot be the first character. This means a page
page.one, a document
jquery.tabtree are all perfectly valid node names and must work in URIs.
~ (tilde) as the delimiter in the
SELECTOR_DELIMITER constant (String).
The whole selector can be split into several selectors separated from each other by the same delimiter
A selector can also be in the form
name=value. For example in
foo=bar is a name-value selector.
Name-value selectors are exposed by
MgnlContext.getAttribute(selectorName) and have a "local" scope similar to HttpServletRequest scope. In the example,
MgnlContext.getAttribute("foo") will return the String
MgnlContext.getAttribute("foo", Context.SESSION_SCOPE) or
MgnlContext.getAttribute("foo", Context.APPLICATION_SCOPE) will return null.
this class exposes some methods to set and get selectors.
setSelector(String selector)is currently used by
info.magnolia.cms.filters.RepositoryMappingFilterwhere the request URI is parsed and the selector part extracted.
String getSelector()returns the whole selector. I.e given the URI
http://myserver/mypage~x~foo=bar~.htmlthis method will return the String x~foo=bar
String getSelectors()returns the selector split into its discrete elements. I.e given the URI
http://myserver/mypage~x~foo=bar~.htmlthis method will return an array of two elements containing the "x" and the "foo=bar" String(s)
SelectorUtil is a utility class already existing before Magnolia 4.5. It provides two methods which are basically shortcuts to the getters in
String getSelector(int index)
Magnolia caches URIs that have selectors by default. Selectors are not a performance constraint. However, when a request parameter is present the URI is excluded from the cache.
/mypage.html?category=Cultureis not cached
The URL fragment can pinpoint very fine-grained locations in the system such as a particular page or configuration node. This makes it possible to build a detailed browsing history. Navigating a browsing history via fragments is not a unique concept. We adopted it from the Google Web Toolkit (GWT) :
For each page that is to be navigable in the history, the application should generate a unique history token. A token is simply a string that the application can parse to return to a particular state. This token will be saved in browser history as a URL fragment (in the location bar, after the "#"), and this fragment is passed back to the application when the user goes back or forward in history, or follows a link.
This is how modern Web applications should work: rather than prevent the user from clicking the Back and Forward buttons, let them do what feels intuitive. If clicking Back seems like the right thing to do to get to the previous state then the application should support that feeling. Using the URL fragment allows the user to use the browser’s own back and forward functionality.
One of the advantages of bookmarking locations in the Favorites app is that they are automatically ported. If you work on multiple computers and different browser, the bookmarks are still available. The favorites functionality is also a relief for system administrators who need to provision functionality to a large user base. An admin can create a set of pre-defined bookmarks that all users get out of the box.