Setup a Webspace¶
In this chapter we will have a look at webspaces. Therefore we will create a configuration for a basic website. This will result in a single portal website with multiple localizations.
As already described in the section before, a webspace also creates a new content tree. These trees are accessible by the navigation in the Sulu administration interface. Sulu allows you to create pages and sub pages in these trees and fill them with content. Have a closer look at Creating a Page Template for more details on the content management process.
Normally you’ll create a webspace for a new website, a landingpage or a portal, that should run on your Sulu instance.
The following file shows a configuration. These lines will be explained in the following paragraphs.
<?xml version="1.0" encoding="utf-8"?>
<webspace xmlns="http://schemas.sulu.io/webspace/webspace"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://schemas.sulu.io/webspace/webspace http://schemas.sulu.io/webspace/webspace-1.1.xsd">
<name>Example</name>
<key>example</key>
<localizations>
<localization language="en"/>
</localizations>
<default-templates>
<default-template type="page">example</default-template>
<default-template type="homepage">default</default-template>
</default-templates>
<templates>
<template type="search">search/search</template>
<template type="error">error/error</template>
</templates>
<excluded-templates>
<excluded-template>overview</excluded-template>
</excluded-templates>
<navigation>
<contexts>
<context key="main">
<meta>
<title lang="en">Mainnavigation</title>
</meta>
</context>
</contexts>
</navigation>
<resource-locator>
<strategy>tree_leaf_edit</strategy>
</resource-locator>
<portals>
<portal>
<name>example</name>
<key>example</key>
<environments>
<environment type="prod">
<urls>
<url language="en">example.org</url>
</urls>
</environment>
<environment type="dev">
<urls>
<url language="en">example.lo</url>
</urls>
</environment>
</environments>
</portal>
</portals>
</webspace>
Note
If you want to match all hosts you can use the {host}
placeholder.
Example: <url>{host}/{localization}</url>
Note
If you add a webspace to an existing installation you also have to set the correct permissions for existing users, otherwise they won’t be able to see it.
As you probably already have encountered, the root tag for our webspace
definition is webspace
. Afterwards you see a name, which is displayed in the
administration interface. But even more important is the key, which is used
internally to generate some files and define some paths. Therefore it is really
important that the webspace key is unique across all webspaces in a single
installation.
Localizations¶
In the localizations
-tag you can list all the available localizations in this
webspace. In the example we are simply adding the English language, but you can
also define country specific language if you add a country attribute to the
localization, so for instance the following tag would add Austrian German to
the available localizations:
<localization language="de" country="at" />
For a more complete explanation you should have a look at Adding localizations.
Themes (optional)¶
The theme
is described by a key. This key leads to a certain theme,
implemented by a developer in the system. Read more about themes in the section
Adding a theme. This feature is default deactivated and therefore in the
example not used. If you have multiple webspaces which should look different,
you can use this feature to do this.
Templates¶
The webspace can also define certain templates in combination with a type.
These templates can then be retrieved from the webspace. E.g. Sulu uses them to
retrieve the correct templates for errors. Therefore it makes use of the
template with type error-<http-code>
respectively it uses the template with
the type error
as a fallback. The other use case is the search. Sulu will
use the template with the type search
from the webspace to display search
results.
Excluded templates (optional)¶
The excluded-templates
node defines which of the templates (the ones
described in Creating a Page Template) should be excluded in the template dropdown of
the page form. The entire node is optional, since especially if you only have
a single webspace this setting does not make a lot of sense.
Resource-Locator (optional)¶
The strategy
for the resource-locator
influences the design of the URLs for
the content. Default value is tree_leaf_edit
, which means that the
resource-locator
will be generated for the whole tree, but only the last part
will be editable.
Currently there is only one alternative tree_full_edit
, which also generates
the whole tree, but lets you edit the whole resource-locator
afterwards.
The strategy
also influences the behavior when renaming or moving a page.
The tree_leaf_edit
(in opposite tree_full_edit
) will also update the
resource-locator
of the children.
Portals¶
A webspace can itself consist of multiple portals. In our simple configuration file we make use of only one portal. The idea is that the same content can be shared among different portals and URLs. The portals can then also define for themselves in which localization they publish the content, so that you can spread different localizations over different URLs.
Our sample file defines just one portal, which includes a name
and a
key
just as the webspace, whereby the key for the portal hast to be unique
for the entire installation, not only within this webspace.
URLs¶
The most important part of the portal configuration are the environments,
because they are including the URLs for the portal. A portal can have multiple
environments, which have to match the environments defined in Symfony. Usually
dev
, stage
and prod
are available. Each environment can define its
own set of URLs.
Note
Please consider that you have to omit the port in the configuration. The system will work with any port, so you don’t have to name it in the configuration.
The URLs also have to include the localization somehow. You have two possibilities to do so:
Fixing an URL to a specific localization¶
The above example shows this possibility, where you fix one URL to exactly one localization. The following fragment shows again how to this:
<url language="de" country="at">www.example.org</url>
Since it is possible to define localizations without a country, this attribute is also optional here. However, the combination of language and country here must result in an existing localization.
Using placeholders in the URL definition¶
Another possibility is to create the URL with a placeholder. Have a look at the following line for an example:
<url>www.example.org/{localization}</url>
Placeholder are expressions in curly braces, which will be expanded to every
possible value. For the above example that means, that an URL for every
localization defined will be generated. So if you have a localization de-at
and en-gb
, the system will create URLs for www.example.org/de-at
and
www.example.org/en-us
.
In the following table all the possible placeholders are listed, and explains
the values of them by using the de-at
-localization:
Placeholder |
Description |
Example for de-at |
---|---|---|
{localization} |
The name of the entire localization |
de-at |
{language} |
The name of the language |
de |
{country} |
The name of the country, only makes sense in combination with {language} |
at |
Now you got your webspace ready, we will create a template for a page that could be added to the webspace.