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
:doc:`templates` 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.
.. code-block:: xml
Example
example
example
default
search/search
error/error
overview
Mainnavigation
tree_leaf_edit
example
example
example.org
example.lo
.. note::
If you want to match all hosts you can use the ``{host}`` placeholder.
Example: ``{host}/{localization}``
.. 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:
.. code-block:: xml
For a more complete explanation you should have a look at
:doc:`localization`.
Themes (optional)
-----------------
The ``theme`` is described by a key. This key leads to a certain theme,
implemented by a developer in the system. If you use multiple webspaces,
which should have a different look and feel, you can easily accomplish
this with the `SuluThemeBundle`_. Read more about the installation and usage
in the `bundle documentation`_.
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-`` 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 :doc:`templates`) 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.
Navigation
----------
It's also possible to define some so called navigation contexts, which allows
the user to add pages to different kind of navigations. The different contexts
can be defined in the ``navigation``-section, and this selection will be
available to choose from in the administration interface. Afterwards the
developer can retrieve the navigation for a given context by using some
Twig-extensions delivered with Sulu, whereby it is not only possible to
retrieve a flat list of pages, but also to retrieve entire navigation trees.
Resource-Locator (optional)
---------------------------
The URL of a page consists of the configured base URL of the webspace and a
page-specific ``resource-locator``. If the ``resource-locator`` of a page is changed,
Sulu will automatically redirect old URLs to the new URL per default. A webspace can set a
``strategy`` for managing the ``resource-locator`` of its pages.
The default strategy is ``tree_leaf_edit``, which means that the generated
``resource-locator`` of a page includes all ancestors in the content tree, but only
the last part will be editable. If the ``resource-locator`` of a page is changed, this
strategy will also update the ``resource-locator`` of all child pages.
The alternative ``tree_full_edit`` strategy also includes all ancestors when
generating the ``resource-locator``, but it allows to edit the whole ``resource-locator``
afterwards. If the ``resource-locator`` of a page is changed, this strategy does not update
the ``resource-locator`` of the child pages.
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:
.. code-block:: xml
www.example.org
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:
.. code-block:: xml
www.example.org/{localization}
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 | `at` |
| | sense in combination with `{language}` | |
+----------------+----------------------------------------+--------------------+
.. _SuluThemeBundle: https://github.com/sulu/SuluThemeBundle
.. _bundle documentation: https://github.com/sulu/SuluThemeBundle