-
Bartosz StarygaFront-End Solution Architect, Magnolia
Headless Magnolia: Mapping Virtual URIs
If you want to learn about Magnolia’s take on headless content management but don't know where to start, you've come to the right place. As part of our “Headless Magnolia” series, we’ll break down relevant features that allow you to use Magnolia as a headless CMS.
In this article, we will look at how to redirect an incoming request to a target destination, also known as virtual URI mapping, for example:
From: /ilm
To: /product/i_love/magnolia
Where to Use Virtual URI Mappings
Virtual URIs are commonly used in marketing to shorten the length of a URL, for example, for:
Microsites
Landing pages
Product pages
Campaign and conversion pages
Downloads
Events and conferences
Vanity URLs
Other reasons for redirecting URLs are related to day-to-day site maintenance, such as:
1. A page has moved due to site re-organization. However, users still have the old URL bookmarked and so do search engine indexes. Without redirection, traffic to your old page location would be lost.
2. If you own several domain extensions like example.net and example.org, you probably want to redirect these to your primary website example.com. You can map multiple domain names to a site in your Magnolia site definition. This can be a major time-saver for a CMS team since there is no need to configure a web server.
Note that you need to register the domains with a registrar first and make sure that the DNS entries for the domains point to the server hosting your Magnolia instance.
Finally, you can use URI mappings to turn a template-based JSON provider into a RESTful API, for example, an FTP Magnolia page that returns JSON:
Original path: /getjson/tours/magnolia-travels/Kyoto
Target path: /getjson?workspace=tours&path=/magnolia-travels/Kyoto
Headless Magnolia: Building a Basic SPA Using Magnolia Templates
In this article of our Headless Magnolia series, we'll create a basic Singe Page Application (SPA) that you can edit in the Magnolia Pages App.
Configuration
You can create virtual URI mappings by creating a YAML configuration file in the virtualUriMappings folder in your module’s configuration. Every URI mapping requires a separate file.
Please note that the folder name must be plural and use camel case for “URI”, making it “Uri”.
File: <my-module>/virtualUriMappings/enterprise-edition.yaml
class: info.magnolia.virtualuri.mapping.DefaultVirtualUriMapping
fromUri: /ilm
toUri: forward:/product/i_love/magnolia
The properties are:
class: The class that performs the mapping. Check the section on mapping classes below.
fromUri: The pattern to match in the requested URI.
toUri: The URI that the request shall be mapped to with an action prefix name.
site: Required for the MultiSiteRegexpVirtualUriMapping class to specify the site that should be used for the mapping.
Mapping Classes and Actions Prefixes
Magnolia provides a number of classes that perform virtual URI mapping.
These are the most commonly used ones:
info.magnolia.virtualuri.mapping.DefaultVirtualUriMapping maps a virtual URI to a content path. This is the simplest and most common type.
info.magnolia.virtualuri.mapping.RegexpVirtualUriMapping allows you to specify a regular expression pattern that matches a sequence of characters. A regexp pattern can match a variety of URIs, which saves time and effort as you would otherwise have to create default mappings for each. toUri can contain back-references to the regexp matches.
info.magnolia.multisite.mapping.MultiSiteRootVirtualUriMapping is a special class that specifies the root of a site if site matching returns null.
info.magnolia.multisite.mapping.MultiSiteRegexpVirtualUriMapping adds a site condition to the URI check. A mapping will only match the request if both the specified regular expression and the specified site match.
In toUri you can use these action prefixes:
forward hides the target URL from the visitor. The URL that the user typed in the browser address bar or the link they clicked does not change for them.
redirect returns the HTTP response status code “302 Found” to the client. While this is ok for human visitors, this method is not ideal for search engine optimization (SEO) as search engines do not transfer the page rank of the old URL to the new URL when receiving this code.
permanent is a search-engine-friendly redirect option. It returns the HTTP response status code “301 Moved Permanently” and preserves your search engine ranking for the redirected page.
proxy forwards the original URL to an external URL.
Examples
class: info.magnolia.virtualuri.mapping.RegexpVirtualUriMapping
fromUri: ^/static/(.*)
toUri: redirect:https://external-domain.com/static/$1
class: info.magnolia.virtualuri.mapping.RegexpVirtualUriMapping
fromURI: ^/profile/(.*)/(.*)$
toURI: forward:/people-profile-page
class: info.magnolia.virtualuri.mapping.DefaultVirtualUriMapping
fromUri: /foo
toUri: forward:/bar
class: info.magnolia.virtualuri.mapping.MultiSiteRootVirtualUriMapping
site: site-one
fromUri: /lorem
toUri: redirect:https://www.magnolia-cms.com
Learn more about Magnolia’s headless features
This Headless Magnolia series will cover the following topics:
Mapping Virtual URIs (you are here)
Nodes Endpoint API and Commands Endpoint API
