Update localization.rst: Added a note how to get the current locale

book/extend-admin.rst

@@ -435,8 +435,14 @@ Finally the ``View`` object has to be added to the ``ViewCollection``, which is
 ``configureViews`` method. This has been implemented like this to allow other bundles to further manipulate views that
 have already been added by bundles registered previously.
 
-After that an empty list should appear on ``/admin/#/events``. But if you add some data to the ``event`` table it
-should be listed:
+The debug command can be used to check whether your view has been created correctly. ``sulu:admin:debug-view``
+
+.. code-block:: bash
+
+    $ bin/adminconsole sulu:admin:debug-view | grep event
+      app.events_list     sulu_admin.list   /events
+
+After that, an empty list should appear on ``/admin/#/events``. Once you add data to the `event` table, the list will populate with the new information:
 
 .. figure:: ../img/extend-admin-list.jpg
 

book/image-formats.rst

@@ -116,6 +116,7 @@ This file does not exist by default and must be created on your own.
             default_imagine_options:
                 jpeg_quality: 80
                 webp_quality: 80
+                avif_quality: 80
                 png_compression_level: 6
 
 Its recommended to have `jpeg_quality` between 70-90 as this is the best compromise between quality and image size.
@@ -137,6 +138,7 @@ A image compression can also be set on a specific image format the following way
             <options>
                 <option name="jpeg_quality">80</option>
                 <option name="webp_quality">80</option>
+                <option name="avif_quality">80</option>
                 <option name="png_compression_level">6</option>
             </options>
         </format>

book/localization.rst

@@ -70,6 +70,8 @@ For the developer the only touching points with localizations are the
 configuration and the eventual use of a language switcher on the homepage.
 For the language switcher the ``localizations`` variable delivered to the twig template
 can be used, which contains an associative array with the parameters ``locale``, ``url`` and ``country``.
+The currently active locale can be obtained from the underlying Symfony Request object with
+``app.request.locale``.
 
 .. code-block:: twig
 

book/templates.rst

@@ -382,7 +382,7 @@ from within a block.
 
 .. note::
 
-    Because the ``&`` character needs to be escaped inside of XML files, you have to use ``AND`` instead of ``&&`` 
+    Because the ``&`` character needs to be escaped inside of XML files, you have to use ``AND`` instead of ``&&``
     if you want to connect conditions using a logical and. Additionally, you can use ``OR`` instead of ``||``.
 
 Language Independent Properties
@@ -641,6 +641,12 @@ type:
     More details about blocks, such as the available parameters, can be found on
     the :doc:`reference <../reference/content-types/block>` page.
 
+.. note::
+
+    If you want to use a block-type in multiple templates, you can define it as a
+    global block. More information about global blocks can be found in the
+    :ref:`templates-global-blocks` section.
+
 Aligning Fields on the Grid
 ---------------------------
 
@@ -885,6 +891,66 @@ You can also match multiple elements of different types. Use the wildcard
         </properties>
     </template>
 
+.. _templates-global-blocks:
+
+Using Global blocks
+-------------------
+
+Global blocks define a set of properties that can be used as type inside of a block or any other property. This is
+useful if you want to reuse a block type in multiple templates.
+
+To define a global block, you have to create a new XML file in the ``config/templates/blocks`` directory. The following
+file is an example and defines a global block with the name ``text_block``:
+
+.. code-block:: xml
+
+    <?xml version="1.0" ?>
+    <template xmlns="http://schemas.sulu.io/template/template"
+              xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+              xsi:schemaLocation="http://schemas.sulu.io/template/template http://schemas.sulu.io/template/template-1.0.xsd">
+
+        <key>text_block</key>
+
+        <meta>
+            <title lang="en">Text Block</title>
+            <title lang="de">Text Block</title>
+        </meta>
+
+        <properties>
+            <property name="title" type="text_line" mandatory="true">
+                <meta>
+                    <title lang="en">Title</title>
+                    <title lang="de">Titel</title>
+                </meta>
+
+            </property>
+
+            <property name="description" type="text_editor">
+                <meta>
+                    <title lang="en">Description</title>
+                    <title lang="de">Beschreibung</title>
+                </meta>
+            </property>
+        </properties>
+    </template>
+
+This block can be used in any other template by using the ``<block>`` or ``<property>`` element within the ``type``
+node and the ``ref`` attribute:
+
+.. code-block:: xml
+
+    <block name="blocks" default-type="text_block" minOccurs="0">
+        <types>
+            <type ref="text_block" />
+        </types>
+    </block>
+
+.. note::
+
+    Mixing global and local block types is supported, but it is recommended to keep your block type names unique
+    to avoid confusion. This approach also simplifies the transition to global blocks in the future, eliminating the need
+    for data migrations.
+
 Caching
 -------
 

bundles/index.rst

@@ -23,6 +23,7 @@ documented the most important ones.
     page/index
     persistence
     preview/index
+    reference
     route/index
     search
     security/index

bundles/location.rst

@@ -17,6 +17,9 @@ Configuration
                 endpoint:             'https://nominatim.openstreetmap.org/search'
             google:
                 api_key:              ''
+            mapquest:
+                api_key:              ''
+                endpoint:             'https://www.mapquestapi.com/geocoding/v1/address'
 
 Services
 --------

bundles/markup/link.rst

@@ -76,7 +76,6 @@ Now you will be able to target the links in CSS and Javascript by using the data
         font-color: green;
     }
 
-
 How the tag is processed
 ------------------------
 
@@ -86,3 +85,23 @@ linked pages from the PHPCR in a *single* query.
 
 If a twig function would be used to generate the links, each call would trigger a
 request to the PHPCR which would worsen the performance.
+
+Removing invalid links
+----------------------
+
+By default Sulu will remove links if the target they are linking to does not exist anymore:
+
+.. code-block:: html
+
+    <sulu-link provider="page" href="123-123-123">Link Text</sulu-link>
+
+    <!-- If the page does not exist, it will render plain text -->
+    Link Text
+
+If you want to completely remove the link text as well you can add the "remove-if-not-exists":
+
+.. code-block:: html
+
+    <sulu-link provider="page" href="123-123-123" remove-if-not-exists="true">Link Text</sulu-link>
+
+    <!-- If the page does not exist, it will render anything -->

bundles/reference.rst

@@ -0,0 +1,61 @@
+ReferenceBundle
+===============
+
+The ReferenceBundle is tasked with tracking references among entities within the application.
+It enables developers and maintainers to quickly determine the relationships between entities and understand the manner
+and location in which an entity is utilized. Presently, the ReferenceBundle is capable of monitoring the usage of Snippets and
+Media within PHPCR entities such as `pages` and `snippets`. These references are managed distinctly for the draft
+state within the `admin context` and the live state within the `website context`.
+
+The main reason we need this bundle is that, unlike traditional database references, our content management system
+operates on an unstructured data model. Therefore, we cannot rely solely on database references, which are usually preferred.
+It is essential to note that the ReferenceBundle should only be used for unstructured data, where database relations are
+not feasible.
+
+Content maintainers are able to see the references to a specific entity in the `Insights` tab of an entity like `Snippet`.
+
+.. figure:: ../img/snippet-insights.png
+    :alt: Snippet References
+
+    Snippet References
+
+Refresh references
+------------------
+
+The references are automatically updated upon saving an entity. You also have the option to manually update the
+references by executing the `bin/console sulu:references:refresh` command. This command optionally accepts the
+<resource-key> argument. When this argument is provided, only the references for the specified resource key will be refreshed.
+
+.. code-block:: bash
+
+    bin/console sulu:references:refresh <resource-key>
+
+.. note::
+
+    Please note that references are only refreshed for the current context. To refresh the references for both the
+    admin and website contexts, you will need to execute the command twice via the `bin/adminconsole` and the `bin/websiteconsole`.
+
+Integrating references for custom content-types
+-----------------------------------------------
+
+To integrate the ReferenceBundle for custom content-types, you need to implement the `ReferenceContentTypeInterface` in your
+content-type class. The interface requires you to implement the `getReferences` method. The method already receives the
+`ReferenceCollector` which you can use to add references to the collector.
+
+Example implementation for a custom content-type:
+
+.. code-block:: php
+
+        public function getReferences(PropertyInterface $property, ReferenceCollectorInterface $referenceCollector, string $propertyPrefix = ''): void
+        {
+            $data = $property->getValue();
+            if (!\is_array($data) || !isset($data['id'])) {
+                return;
+            }
+
+            $referenceCollector->addReference(
+                CustomEntity::RESOURCE_KEY,
+                (string) $data['id'],
+                $propertyPrefix . $property->getName()
+            );
+    }

bundles/security/index.rst

@@ -106,6 +106,51 @@ the object type and id are also passed the permissions of the security contexts
 from the role might be overridden by the permissions from this specific object
 (which are handled by the previously mentioned ``AccessControlManager``).
 
+Single-Sign-On Authentication
+------------------------------
+
+Sulu supports authentication via Single-Sign-On (SSO).
+To enable it, the security configuration needs to be adjusted to allow SSO in the admin firewall.
+This can be configured in the ``config/packages/security.yaml``:
+
+.. code-block:: diff
+
+    security:
+        # ...
+
+        firewalls:
+            # ...
+            admin:
+
+                # ...
+                logout:
+                    path: sulu_admin.logout
+   +            access_token:
+   +                token_handler: sulu_security.single_sign_on_token_handler
+   +                token_extractors: sulu_security.single_sign_on_token_extractor
+
+    # ...
+    sulu_security:
+        checker:
+            enabled: true
+        password_policy:
+            enabled: true
+   +    single_sign_on:
+   +        providers:
+   +            'sulu.io':
+   +                dsn: 'openid://%env(resolve:SULU_OPEN_ID_CLIENT_ID)%:%env(resolve:SULU_OPEN_ID_CLIENT_SECRET)%@%env(resolve:SULU_OPEN_ID_ENDPOINT)%'
+   +                default_role_key: 'USER'
+
+After adjusting the configuration and clearing the symfony cache,
+you only see the ``username or email`` field when you try to login to the administration interface.
+When the user email matches the configured domain,
+the user is then redirected to the SSO provider to authenticate. After successful authentication, the system redirects the user back to the administration interface.
+If the domain does not match the configured domain, the user is authenticated using the standard login form.
+On password reset, when the domain matches, the user is also redirected to the SSO provider.
+
+.. note::
+
+    At the moment, only the OpenID protocol is supported for Single-Sign-On authentication in Sulu.
 
 Two-Factor Authentication
 -------------------------

conf.py

@@ -59,9 +59,9 @@
 # built documents.
 #
 # The short X.Y version.
-version = '2.5'
+version = '2.6'
 # The full version, including alpha/beta/rc tags.
-release = '2.5'
+release = '2.6'
 
 # The language for content autogenerated by Sphinx. Refer to documentation
 # for a list of supported languages.

cookbook/build-admin-frontend.rst

@@ -76,6 +76,34 @@ on your computer.
     npm install
     npm run build
 
+Solution 4: Build manually locally with bun
+-------------------------------------------
+
+As an alternative to node/npm Sulu also supports to use `bun`_ to build the administration interface.
+The support for bun is experimental and can be removed in future versions of Sulu.
+
+1. Install Bun
+
+If not yet installed on your computer you would need to install `bun`_
+on your computer.
+
+2. Cleanup previously created node_modules folders and bun.lockb files
+
+.. code-block:: bash
+
+    cd /var/project
+    rm -rf assets/admin/node_modules && rm -rf vendor/sulu/sulu/node_modules && rm -rf vendor/sulu/sulu/src/Sulu/Bundle/*/Resources/js/node_modules
+    rm -rf assets/admin/bun.lockb && rm -rf vendor/sulu/sulu/bun.lockb && rm -rf vendor/sulu/sulu/src/Sulu/Bundle/*/Resources/js/bun.lockb
+
+3. Create the administration interface build
+
+.. code-block:: bash
+
+    cd /var/project/assets/admin
+    bun run preinstall
+    bun install
+    bun run build
+
 Common errors
 -------------
 
@@ -110,3 +138,4 @@ If this does not solve the problem, you can try to clean the npm cache on your m
 .. _Test Application workflow: https://github.com/sulu/sulu/blob/2.x/.github/workflows/test-application.yaml
 .. _sulu/skeleton repository: https://github.com/sulu/skeleton
 .. _node: https://nodejs.org/en/
+.. _bun: https://bun.sh/

cookbook/cleanup-phpcr-database.rst

@@ -0,0 +1,14 @@
+Cleanup PHPCR database
+======================
+
+If you have an older installation of Sulu, you may be dealing with a database cluttered with outdated PHPCR properties.
+This is particularly common if you’ve made significant changes to your templates or content types over time.
+To tidy up your database, try running the following command:
+
+.. code-block:: bash
+
+    php bin/console sulu:document:phpcr-cleanup
+
+The command is quite powerful, but exercise caution when deploying it in a production environment. 
+It will remove all properties not currently utilized in your templates. To avoid potential pitfalls, ensure you have a 
+backup of your database in place before executing this command.