Confessions of an apprentice: Creating a mobile channel (siteaccess) in eZ Publish

Since the last article on this blog was about Going mobile with eZ Publish, I’ll show you how to create a new siteaccess in eZ Publish with an intention of creating a mobile channel. And that’s actually one of the main reasons why eZ Publish is so versatile, since with multiple siteaccesses you can create a site that will cover all of your creative bases.

Creating a new siteaccess in eZ Publish

What’s a siteaccess anyway?

You have probably heard the word siteaccess in the context of eZ Publish programming a lot of times already. But did you stop and consider what this concept actually means? Well, to put it as simple as possible, a siteaccess is a way to handle multiple sites on a single installation of eZ Publish. From a technical standpoint, a siteaccess is just a bunch of INI settings which you set up and then apply necessary changes for these multiple sites. Now, when I say “multiple sites”, you probably think of different content for each site, different design and whatnot. And yes, while you may do stuff like that on a single installation, too, a siteaccess runs deeper than that.

You see, you handle siteaccesses in your day-to-day operations in eZ Publish already! How can this be? Well, for example, the Administration Interface, the place where all of your content comes together, is a siteaccess. If you have a multilingual site, you are using multiple siteaccesses, each siteaccess representing a language in your installation. It’s just a matter of a common design between all of them which defines the whole look-and-feel throughout your siteaccesses.

You can even go so far as to create different channels for different types of users. For example, if you have a news portal, and you have a group of users called Journalists, you can create a siteaccess for them which will serve as an editorial interface, but will be adjusted to their particular needs, which is writing articles and putting them in the right context (topic-based). Also, you can create another group of users called, for example, Photographers, and limit them only to the upload of images and editing existing articles so they can fill them up with images, etc.

Siteaccesses provide us with a possibility to create specialized portions of a site which serves a certain need. In a similar manner, a mobile site based on a large corporate site which was created in eZ Publish serves a certain need, which is delivering content created for the mobile version of our site.

Siteaccesses come in handy in all of those situations because they are relatively easy to set up and all you have to do then is apply whatever changes you need to them, e.g., a new design, a new order in which the content is output, or just a new language.

You can even go so far to link each siteaccess to different subdomains of your site so you can have, for example, your main siteaccess in, say, English, www.example.com, your Administration Interface, admin.example.com, your mobile site, mobile.example.com, and, say, the portion of the site in French, french.example.com. And then, after all that, you can create a completely new siteaccess linked to another domain called, e.g., new.example.com, which will actually output a whole different content in a whole new surrounding.

As far as accessing the website is concerned, eZ Publish has three most commonly used distinct methods of choosing the siteaccess: through the URI, through the host, and through the port. There is a fourth one, servervar, but it is rarely used. The URI is the default and the easiest way to set up your siteaccess. Since the URI is just a part of the URL, all you need to do is add the name of your siteaccess to the main URL (for example: www.example.com/name_of_siteaccess), and the siteaccess matching the URI part will be displayed. Using the host access method is a bit trickier, because you need to set up a subdomain (or subdomains), and the Virtual Host mode on your server. Then you will get the type of example we mentioned earlier (name.example.com). The port access method is linking the various siteaccesses to the ports on your server, so, for example, you can link your main siteaccess to port 80, and the administration siteaccess to port 81. You can even go so far as to combine the URI and host access methods, so that they can both be available to the end-user.

As you can see, a siteaccess is actually a very versatile tool which makes your daily eZ Publish programming a lot easier to manipulate, and in the end, makes your clients more satisfied because the siteaccess system shortens the time necessary to apply multiple solutions to one installation.

How to create a siteaccess

All of the siteaccesses on a site are created in the settings folder of our eZ Publish installation. As you probably can tell just by the look of it, the settings folder has a number of INI files, and two folders in it, siteaccess and override. Now, all of your siteaccess-particular settings are located in the siteaccess folder, and all of the settings regarding the whole eZ installation are located in the override folder.

To create a new siteaccess, go to the mypage/settings/siteaccess folder of your eZ Publish installation and create a new folder here called mobile. We will call it mobile under the assumption that the new channel will handle all of the mobile content for our site.

The next step is actually telling eZ Publish that we want this mobile folder to be a new siteaccess. For that purpose, we need to set up some settings in the site.ini file. So, go to the /settings/override folder of your installation and open the site.ini.append.php file. In it, you have the relevant settings for your whole site. We are interested in the SiteAccessSettings block. Edit the SiteAccessSettings block of the site.ini.append.php file like so:

[SiteAccessSettings]
AvailableSiteAccessList[]=mobile

Just to be clear, don’t delete anthing else you might have under this block, just add this new line so you can prepare your installation for a new siteaccess.

After that, we need some new site settings for the mobile channel. The best way to set up our new siteaccess to use every resource the rest of the siteaccesses use is to copy a site.ini.append.php file from another siteaccess, for example, the most common one, eng. So, we’ll do just that. Go into /settings/siteaccess/eng, copy the site.ini.append.php file and paste it into the /settings/siteaccess/mobile folder. After that, open the new site.ini.append.php file and make the necessary modifications like so:

[SiteAccessSettings]
RequireUserLogin=false
RelatedSiteAccessList[]=eng
RelatedSiteAccessList[]=administration
MatchOrder=uri;host
HostMatchMapItems[]
HostMatchMapItems[]=mobile.mypage.com;mobile
[DesignSettings]
SiteDesign=mobile
AdditionalSiteDesignList[]=mydesign
AdditionalSiteDesignList[]=ezwebin
AdditionalSiteDesignList[]=base

So, what do we have here? Under the SiteAccessSettings block, we have told eZ Publish that a user doesn’t need a username or password to open the mobile channel. Also, content-wise, we have told eZ Publish that eng and administration will be the related siteaccesses which means that their view cache will be cleared when it is cleared for the current siteaccess. Also, we set up the mobile siteaccess so that it will open if the user inputs two possible addresses in the address bar (mobile.mypage.com or mypage.com/mobile). Of course, that’s assuming that the Virtual Host is set up properly. After that, I have assumed that a mobile channel needs to have a new design, therefore, we have set up a new design called mobile which this siteaccess will use. But, no worries, since it will fall back on the list of designs we already use all over the site if eZ Publish doesn’t find the mobile design.

Even though we’ve set up almost everything needed in regards to this siteaccess, there is still a few things we need to do. For example, with these settings we have created a new siteaccess, but it still won’t be visible in the Quick Settings of the Administration Interface. To make it visible, we need to do one last thing in regards to the INI settings. Go into /settings/siteaccess/administration and put your new siteaccess on the RelatedSiteAccess list in the site.ini.append.php here, too. After that, access your Administration Interface through the browser, and clear the INI cache in the Global (override) siteaccess. After that, your new siteaccess will be visible in your Administration.

But, wait! We need to do one more thing. Currently, the way we set up our new siteaccess, no Anonymous User will be able to access it. Why is that? Well, the RequireUserLogin works as a global switch to determine if a user needs to supply credentials to gain entry into a siteaccess. But that doesn’t mean that Anonymous Users really have access to the mobile channel. That’s what Roles and Policies are for. You see, eZ Publish checks two things: does a user need to supply credentials to enter a siteaccess (RequireUserLogin), and can a user truly enter the siteaccess (Roles and Policies). If one of those isn’t set up properly, Anonymous Users won’t be able to view our mobile site. Which is why we need to grant them this privilege. Let’s do that, shall we?

Go to the User Accounts tab in the Administration Interface and click on Roles And Policies. Click on the Anonymous role, and click on Edit. After that, add a new policy. In the Wizard, under Module, click on user, under Function, click on login, and then click on Grant limited access. After that, you’ll get a list of all the siteaccesses of the site. Choose mobile, and click on OK. after that, click on Save.

Now, try to access your site. If you have set up your site locally go to: mypage/mobile, and see if it outputs any errors. If it doesn’t, you have set up your siteaccess, and if it does, go through all of the previously described steps and see if you’ve set everything up properly.

To sum up, setting up a new siteaccess means simply setting up new INI settings and clearing the cache. eZ Publish does everything else for you. And that is the beauty of the siteaccess system. You don’t need to do much to set it up, but it represents, as Igor wrote in the previous article, such a simple way to setup radically different user experiences that can provide you with new possibilities: a new design, a new language, some custom settings, or even a whole new content (a new database and storage). The siteaccess engine is powerful and easy, and that’s what makes it a good practice.

Until next time, I wish you happy coding,
Tomislav