Posted by rah003
on May 3, 2010 at 12:38 AM PDT
What I realized shortly after we put out Magnolia 4.3 is that while we tried to explain new multisite support for example in this screencast there are still plenty of grey areas and lot of confusion when people actually get to use the multisite support. And I think I wrote and talked about this topic earlier as well.
Of course as with any new functionality, there are still some rough edges that needed to be smoothened out. I would be doing you bad service, trying to deny this. On the first sight the feature seems to be quite simple - you have multiple domains that are served by Magnolia so you assign each of those domain into any site defined in Magnolia and in turn Magnolia will ensure that the URLs are shortened for that site and that the site configuration is applied properly to all the content that is requested using given domain. So far so good. And I think everybody got this piece without any confusion, if not below is the simple sketch that should help - no matter how many domains you use or how many subtrees you have, the one mapped to the site will be shortened and will not anymore appear in the URL (on the left). Those who used older versions of Magnolia before, know that to achieve the same result, one had to use Apache mod-rewrite. Now the same is supported by Magnolia directly.
What on the other hand caused a lot of confusion and is not shown in any screencast or other place is how you deal with the feature and its configuration on the author instance. Since your author instance is usually accessed with a single domain name only, the recognition of the site based on the domain is not applicable here.
There are number of possible approaches to work around the single domain limitation:
- map the domain under which author is accessed to all of the defined sites. Unfortunately this doesn't work. Each domain can belong to only one site. If any domain is mapped to more then one site, the first site found that has the domain assigned to,is the one that will be used by the system.
- assign multiple domains to the author instance, one for each site you have and havethe authors to log in via these particular domains. That would actually work, but is quite cumbersome and is very unfriendly towards the admins or the editors that need to edit more then just one site.
- do nothing and have Magnolia take care of the things. I guess this is the preferred option for the most of the users. And while this can be done there are some peculiarities about this solution which I'll try to shed more light on below.
Lets step back for a second and reiterate what the site definition is all responsible for in 4.3:
- the theme assignment. Theme is assigned via site configuration and it means as much as CSS, JS and image variation rules.
- the internationalization. I18n configuration is also assigned via the site configuration. While prior 4.3, this meant only a definition of default language for given site, with 4.3 you can assign all languages supported by the given site as well as default and fallback language.
- the domains. I already mentioned this one earlier, but for the sake of completeness, you can assign multiple domains to a given site, but each domain can belong to one site and one site only.
- the content tree mapping. For each repository, you can assign site specific subtree in given repository. This assignment is then used to shorten the URLs.
- the template assignment. You've all seen that you can have different kinds of templates at different levels. You can also limit the visibility of the templates by user role. Now with 4.3 you can also easily set different set of templates for different sites and be able to assign them in the given site content only, no matter through which domain you logged in.
As you can see from the list above it is quite essential for Magnolia to recognize the site definition belonging to the site content/tree in order to be able to render it properly at all times, no matter which domain is used while authoring the content.
Let me now try to explain how this is achieved.
When a request comes, Magnolia first tries to look at the domain for which the request is addressed. If the match between requested content and the mapping prefix of that domain is found, everything is cool, the proper site is assigned to the request.
The next check is whether the URL have been shortened for this site or not and the internal content handle is set properly based on that.
Should one of the above checks fail, Magnolia will treat this as something Philipp nicknamed cross-site access.
In the cross-site access mode, Magnolia will try to look next at the first segment of the URI to see if this segment does match any site definition name. This is a new thing in 4.3 which didn't exist before and it is also the plug that allows Magnolia to find out the correct site definition no matter what domain is used to access the content.
The third test in case the site definition name is not found in the first URI segment is to see if the URI matches repository mapping prefix of any site definition's mappings. When such mapping is found, the site is assigned based on that result. This is the common case when opening the page from the AdminCentral tree view. Since the tree itself is utterly unaware of the site definition mechanism.
And of course if all the above fails, the default site is used.
Now let's try to illustrate those scenario's with few examples: Imagine we have a site definition called <MySite> and it is mapped to the site-tree named <myCoolSite>. And in the site definition <MySite> we have also assigned domain mapping to the domain www.coolSite.com
At first we access this instance with the domain name http://www.coolSite.com
That would give us a shortened home page which it's name is in fact myCoolSite. The URL in browser is just the site name exactly as it was entered (no more any redirection!), while the content displayed on the page is that of /myCoolSite page.
Of course this is all irrelevant when accessing the public site and you would use only the URL. However it is important when accessing the author instance. Let me leave out the reasons why, but assume that you are managing multiple sites from the author instance and there is no possibility to get multiple domain names for it.
All you have is http://magnoliaAuthor.mycompany.com
Now to access the "cool site" content you log in, and in the AdminCentral you click on <myCoolSite> to display the site home page. URL generated by the tree is http://magnoliaAuthor.mycompany.com/myCoolSite.html Because of the 3rd mechanism of recognizing the site, the proper site is assigned to this content and it is styled properly and correct language choices are displayed. You go back to the AdminCentral and decide to see the about page of your site /myCoolSite/about when you click on it the http://magnoliaAuthor.mycompany.com/myCoolSite/about.html URL is opened. Again this works because of the 3rd mechanism to recognize the sites.
While looking at the about page you decide you need to translate it to other locale you have defined for your site, say Spanish. In the language selector you choose Spanish and you are redirected to a page at http://magnoliaAuthor.mycompany.com/MySite/es/about.html What has happened here? First you can see that the generated URL contains the site name. This is so the Magnolia can use the 2nd mechanism for resolving the sites to find your site. Second thing you see is that the locale is included in the URL. This is because you requested to display the page in other then default locale. Third there is no home page in the URL. This is because the site is clearly identified so Magnolia have applied URL shortening and has hidden the site home page name from the URL.
You could observe the same also for all the generated links on given page. Say the link to the home page would now look as http://magnoliaAuthor.mycompany.com/MySite/es/ and if looked at before switching the language that link would have looked exactly the same just without the language selector. Also imagine there was a cross site link to a page belonging to another site also managed by Magnolia. And imagine this site
doesn't support Spanish locale. The link would look like http://magnoliaAuthor.mycompany.com/AnotherSite/path/to/the/page.html. Should the locale have been supported the link would include the locale as well.
The main thing to remember here is that the generated URLs with the multisite support enabled and cross site access (i.e. access from other then defined domain), the same page is reachable under multitude of different URLs in order to cover all possible scenarios of access. Just refuse to get confused by the generated links. Also remember that on public site, you always use the proper domain name so there is no need to think about any of this.
To give you another summary of the whole thing, the URLs can look like anything matching the following pattern: