From 684b062fa3fe42462bf1313074ee59f3db6832b3 Mon Sep 17 00:00:00 2001
From: Brandon Mercier <113701731+bram-odoo@users.noreply.github.com>
Date: Tue, 25 Feb 2025 12:30:28 +0000
Subject: [PATCH] [IMP] Website themes - Pages

[IMP] Website themes - Pages
[FIX] Website Themes - Pages: Anchors
[FIX] Website Themes - Pages: anchors
[FIX] Anchors patterns + code review modifications

closes odoo/documentation#12514

X-original-commit: f0466043365e57a1e753a6da35b4a0bc56afc320
Signed-off-by: Brandon Mercier (bram) <bram@odoo.com>
---
 .../howtos/website_themes/layout.rst          |   2 +-
 .../developer/howtos/website_themes/pages.rst | 158 +++++++++++++-----
 locale/sources/developer.pot                  |   2 +-
 3 files changed, 116 insertions(+), 46 deletions(-)

diff --git a/content/developer/howtos/website_themes/layout.rst b/content/developer/howtos/website_themes/layout.rst
index 5ebfbd2e9..885db2eef 100644
--- a/content/developer/howtos/website_themes/layout.rst
+++ b/content/developer/howtos/website_themes/layout.rst
@@ -574,7 +574,7 @@ Navbar toggler
    </t>
 
 .. seealso::
-   You can add a :ref:`header overlay <header_overlay>` to position your header over the content of
+   You can add a :ref:`header overlay <website_themes/pages/theme_pages/header_overlay>` to position your header over the content of
    your page. It has to be done on each page individually.
 
 .. _website_themes/layout/footer :
diff --git a/content/developer/howtos/website_themes/pages.rst b/content/developer/howtos/website_themes/pages.rst
index 2d25a0cec..fa2de2e7e 100644
--- a/content/developer/howtos/website_themes/pages.rst
+++ b/content/developer/howtos/website_themes/pages.rst
@@ -4,6 +4,8 @@ Pages
 
 In this chapter, you will learn how to declare static pages.
 
+.. _website_themes/pages/default :
+
 Default pages
 =============
 
@@ -11,39 +13,57 @@ In Odoo, websites come with a few default static pages (Home, Contact us, 404, .
 the following way.
 
 .. code-block:: xml
+   :caption: `/website/data/website_data.xml`
 
-   <template id="website.homepage" name="Homepage">
-       <t t-call="website.layout">
-
-           <!-- Variables -->
-           <t t-set="additional_title" t-value="'Home'" />
-
-           <div id="wrap" class="oe_structure oe_empty">
-
-               <!-- Content -->
-
-           </div>
-
-       </t>
+   <template id="website.homepage" name="Home">
+      <t t-call="website.layout">
+         <t t-set="pageName" t-value="'homepage'"/>
+         <div id="wrap" class="oe_structure oe_empty" />
+      </t>
    </template>
 
+Each default page is a template with its own content saved into a record. This is the reason why,
+:ref:`custom pages are created within a record <website_themes/pages/theme_pages>`.
+
+The `<t -call='website.layout'>` has some variables that can be set:
+
 Define the meta title.
 
 .. code-block:: xml
 
-   <t t-set="additional_title" t-value="'...'"/>
+   <t t-set="additional_title">My Page Title</t>
+
+.. tip::
+   The `t-set` here does not pass the value into a `t-value` or a `t-valuef` attribute.
+   This is for translation purpose. The content of a `t-value` or a `t-valuef` is not explicitly
+   exported for translation. Beside that, as it's written in XML, a string located between an opening
+   and a closing tag is considered translatable by default.
+
+   .. example::
+      **Good example:**
+
+      .. code-block:: xml
+
+         <t t-set="additional_title">My title</t>
+
+      **Bad example:**
+
+      .. code-block:: xml
+
+         <t t-set="additional_title" t-valuef="My title"/>
 
 Define the meta description.
 
 .. code-block:: xml
 
-   <t t-set="meta_description" t-value="'...'"/>
+   <t t-set="meta_description">This is the description of the page that will appear on Search
+   Engines.</t>
 
 Add a CSS class to the page.
 
 .. code-block:: xml
 
-   <t t-set="pageName" t-value="'...'"/>
+   <t t-set="pageName" t-valuef="..."/>
 
 Hide the header.
 
@@ -80,21 +100,19 @@ Alternatively, replace the default content of these pages using XPath.
 
    <template id="404" inherit_id="http_routing.404">
        <xpath expr="//*[@id='wrap']" position="replace">
-
            <t t-set="additional_title" t-value="'404 - Not found'"/>
 
            <div id="wrap" class="oe_structure">
                <!-- Content -->
            </div>
-
        </xpath>
    </template>
 
 .. seealso::
-   - `Odoo eLearning: Search Engine Optimization (SEO)
-     <https://www.odoo.com/slides/slide/search-engine-optimization-seo-648>`_
    - :doc:`Odoo Documentation on SEO <../../../applications/websites/website/pages/seo>`
 
+.. _website_themes/pages/theme_pages :
+
 Theme pages
 ===========
 
@@ -106,28 +124,33 @@ page object.
 .. code-block:: xml
    :caption: ``/website_airproof/data/pages/about_us.xml``
 
-   <record id="page_about_us" model="website.page">
-       <field name="name">About us</field>
-       <field name="is_published" eval="True"/>
-       <field name="key">website_airproof.page_about_us</field>
-       <field name="url">/about-us</field>
-       <field name="type">qweb</field>
-       <field name="arch" type="xml">
-           <t t-name="website_airproof.page_about_us">
+   <odoo>
+      <data noupdate="1">
+         <record id="page_about_us" model="website.page">
+               <field name="name">About us</field>
+               <field name="is_published" eval="True"/>
+               <field name="key">website_airproof.page_about_us</field>
+               <field name="url">/about-us</field>
+               <field name="website_id" eval="1" />
+               <field name="type">qweb</field>
+               <field name="arch" type="xml">
+                  <t t-name="website_airproof.page_about_us">
+                     <t t-call="website.layout">
+                        <div id="wrap" class="oe_structure">
+                           <!-- Content -->
+                        </div>
+                     </t>
+                  </t>
+               </field>
+         </record>
+      </data>
+   </odoo>
 
-               <t t-call="website.layout">
-                   <div id="wrap" class="oe_structure">
+.. admonition:: Multiwebsite and `website_id`
 
-                       <!-- Content -->
-
-                   </div>
-               </t>
-
-           </t>
-       </field>
-   </record>
-
-.. todo:: Missing description in table ...
+   In a module context, the record created above is available, by default, on every website
+   available on the database. It's preferable to specify the `website_id` of the website where the
+   page will be findable.
 
 .. list-table::
    :header-rows: 1
@@ -137,21 +160,59 @@ page object.
    * - Field
      - Description
    * - name
-     - Page name.
+     - Page name (human-readable).
    * - is_published
      - Define if the page is published (visible to visitors).
    * - key
      - View key (must be unique)
    * - url
-     - URL where the page is reachable.
+     - Relative path where the page is reachable.
    * - type
      - View type
    * - arch
-     - View architecture
+     - View architecture (the markup of your page)
 
 With `<t t-call="website.layout">` you use the Odoo default page layout with your code.
 
-.. _header_overlay:
+.. _website_themes/pages/theme_pages/noupdate :
+
+`noupdate` attribute
+--------------------
+
+This attribute prevents data overwriting.
+
+.. code-block:: xml
+
+   <data noupdate="1">
+      <!-- Your record -->
+   </data>
+
+**Use case**
+
+There are several static pages created in the module. This one has been installed on the database
+and the end-user has updated some of those pages. Some bug fixes must be applied on the
+static pages while avoiding any loss of changes made by the end-user.
+
+**Problem**
+
+In case of a module update on the database, every record declared into the module will overwrite
+those existing in the database even if the end-user has changed some of these records.
+
+**Solution**
+
+By wrapping the record (or all records declared in the file) into a `<data noupdate="1"></data>`
+tag, the record declared is created at
+the first module installation but not updated after a module update.
+
+.. spoiler:: What happens if the record has been manually deleted (e.g.: a menu item) ?
+
+   The system detects that this record doesn't exist and will re-create it.
+
+.. spoiler:: Is this method only valid on static page records?
+
+   Of course not. It's technically usable for every type of records.
+
+.. _website_themes/pages/theme_pages/header_overlay :
 
 Header overlay
 --------------
@@ -164,3 +225,12 @@ Make the header background transparent and stand on top of the page content.
 
 .. image:: pages/header-overlay.png
    :alt: Header overlay
+
+.. note::
+   To create the content of a static page, use the Odoo way of doing things in order to remain
+   editable by the Website Builder. Please note that Odoo takes advantage of Bootstrap framework (5.1.3).
+
+   Find the available classes and components:
+
+   - `Bootstrap cheat sheet <https://getbootstrap.com/docs/5.1/examples/cheatsheet/>`_
+   - `Bootstrap documentation <https://getbootstrap.com/docs/5.1/getting-started/introduction/>`_
diff --git a/locale/sources/developer.pot b/locale/sources/developer.pot
index 5259304c8..5c853d591 100644
--- a/locale/sources/developer.pot
+++ b/locale/sources/developer.pot
@@ -3745,7 +3745,7 @@ msgid "Navbar toggler"
 msgstr ""
 
 #: ../../content/developer/howtos/website_themes/layout.rst:434
-msgid "You can add a :ref:`header overlay <header_overlay>` to position your header over the content of your page. It has to be done on each page individually."
+msgid "You can add a :ref:`header overlay <howto/website_themes/pages_theme_header_overlay>` to position your header over the content of your page. It has to be done on each page individually."
 msgstr ""
 
 #: ../../content/developer/howtos/website_themes/layout.rst:438