diff --git a/Documentation/Setup/Page/Index.rst b/Documentation/Setup/Page/Index.rst index 79908e0f0..e1d856a2e 100644 --- a/Documentation/Setup/Page/Index.rst +++ b/Documentation/Setup/Page/Index.rst @@ -1,10 +1,10 @@ -.. include:: /Includes.rst.txt -.. index:: +.. include:: /Includes.rst.txt +.. index:: PAGE Top-level objects; page -.. _page: -.. _page-datatype: -.. _object-type-page: +.. _page: +.. _page-datatype: +.. _object-type-page: ==== PAGE @@ -18,8 +18,8 @@ the content-page on a website. TYPO3 does not initialize :typoscript:`page` by default. You must initialize this explicitly, for example: -.. code-block:: typoscript - :caption: EXT:site_package/Configuration/TypoScript/setup.typoscript +.. code-block:: typoscript + :caption: EXT:site_package/Configuration/TypoScript/setup.typoscript page = PAGE @@ -31,7 +31,7 @@ page is found. Most of this code is executed in the PHP script :php:`\TYPO3\CMS\Frontend\Http\RequestHandler`. -.. _page_output: +.. _page_output: Output of the PAGE object ========================= @@ -39,44 +39,46 @@ Output of the PAGE object An empty :typoscript:`PAGE` object without further configuration renders a HTML page like the following: -.. code-block:: html - - - - - - - Page title - - - - - +.. code-block:: html + + + + + + + Page title + + + + + This default behaviour can be changed by setting the property :ref:`setup-config-disableallheadercode`: -.. code-block:: typoscript - :caption: EXT:site_package/Configuration/TypoScript/setup.typoscript +.. code-block:: typoscript + :caption: EXT:site_package/Configuration/TypoScript/setup.typoscript - page.config.disableAllHeaderCode = 1 + page.config.disableAllHeaderCode = 1 If the output represents another format different from HTML the HTTP header should also be set, for example: -.. code-block:: typoscript - :caption: EXT:site_package/Configuration/TypoScript/setup.typoscript +.. code-block:: typoscript + :caption: EXT:site_package/Configuration/TypoScript/setup.typoscript - page.config.additionalHeaders.10.header = Content-type:application/json + page.config.additionalHeaders.10.header = Content-type:application/json -.. index:: - PAGE; typeNum - PAGE; Multiple pages +.. index:: + PAGE; typeNum + PAGE; Multiple pages + +.. _page_multiple: Multiple pages ============== @@ -92,8 +94,8 @@ the page will be used. Example: -.. code-block:: typoscript - :caption: EXT:site_package/Configuration/TypoScript/setup.typoscript +.. code-block:: typoscript + :caption: EXT:site_package/Configuration/TypoScript/setup.typoscript page = PAGE page.typeNum = 0 @@ -114,6 +116,8 @@ an id parameter (for the page id), example (for json and page id 22): :samp:`/index.php?id=22&type=1` +.. _page_guidelines: + Guidelines ---------- @@ -126,6 +130,7 @@ Good, general PAGE object names to use are: These are just recommendations. However, especially the name page for the content bearing page is very common and most documentation will imply that your main page object is called page. +.. _page_examples: Examples ======== @@ -134,189 +139,140 @@ Please see the dedicated example page about examples of how to use the PAGE object: :ref:`page_examples` -.. index:: PAGE; Properties +.. index:: PAGE; Properties +.. _page_properties: Properties ========== -.. container:: ts-properties - - ============================== ===================================== ====================== ======================== - Property Data Type :ref:`stdwrap` Default - ============================== ===================================== ====================== ======================== - `1,2,3,4...`_ :ref:`cObject ` - `bodyTag`_ :ref:`data-type-tag` - `bodyTagAdd`_ :ref:`data-type-string` - `bodyTagCObject`_ :ref:`cObject ` - `config`_ :ref:`->CONFIG ` - `css\_inlinestyle`_ :ref:`data-type-string` - `cssInline.[array]`_ :ref:`cObject ` - `footerData.[array]`_ :ref:`cObject ` - `headerData.[array]`_ :ref:`cObject ` - `headTag`_ :ref:`data-type-tag` / :ref:`stdwrap` - `includeCSS.[array]`_ :ref:`data-type-resource` - `includeCSSLibs.[array]`_ :ref:`data-type-resource` - `includeJS.[array]`_ :ref:`data-type-resource` - `includeJSFooter.[array]`_ :ref:`data-type-resource` - `includeJSFooterlibs.[array]`_ :ref:`data-type-resource` - `includeJSLibs.[array]`_ :ref:`data-type-resource` - `inlineLanguageLabelFiles`_ (array of strings) - `inlineSettings`_ (array of strings) - `jsFooterInline.[array]`_ :ref:`cObject ` - `jsInline.[array]`_ :ref:`cObject ` - `meta`_ (array of strings) - `shortcutIcon`_ :ref:`data-type-resource` - `stdWrap`_ :ref:`stdwrap` - `typeNum`_ :ref:`data-type-integer` 0 - `wrap`_ :ref:`data-type-wrap` - ============================== ===================================== ====================== ======================== - -.. ### BEGIN~OF~TABLE ### - - -.. index:: PAGE; Content objects -.. _setup-page-1-2-3-4: +.. contents:: + :local: + +.. index:: PAGE; Content objects +.. _setup-page-array: 1,2,3,4... -========== +---------- -.. container:: table-row +.. confval:: 1,2,3,4... + :name: page-array + :type: :ref:`cObject ` - Property - 1,2,3,4... + These properties can be used to define any number of objects, + just like you can do with a :ref:`COA content object `. - Data type - :ref:`cObject ` + The content of these objects will be rendered on the page in the + order of the numbers, not in the order they get defined in the TypoScript + definition. - Description - These properties can be used to define any number of objects, - just like you can do with a :ref:`COA content object `. + It is considered best practice to leave space between the numbers such + that it will be possible to place objects before and after other objects + in the future. Therefore you will often see that people use the number + 10 and no number 1 is found. - The content of these objects will be rendered on the page in the - order of the numbers, not in the order they get defined in the TypoScript - definition. +.. _setup-page-array-example: - It is considered best practice to leave space between the numbers such - that it will be possible to place objects before and after other objects - in the future. Therefore you will often see that people use the number - 10 and no number 1 is found. +Example: Render "Hello World" +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - Example - .. code-block:: typoscript - :caption: EXT:site_package/Configuration/TypoScript/setup.typoscript +.. code-block:: typoscript + :caption: EXT:site_package/Configuration/TypoScript/setup.typoscript - page = PAGE - page.20 = TEXT - page.20.value = World - page.10 = TEXT - page.10.value = Hello + page = PAGE + page.20 = TEXT + page.20.value = World + page.10 = TEXT + page.10.value = Hello - This renders to :html:`HelloWorld`. +This renders to :html:`HelloWorld`. -.. index:: PAGE; bodyTag -.. _setup-page-bodytag: +.. index:: PAGE; bodyTag +.. _setup-page-bodytag: bodyTag -======= +------- -.. container:: table-row +.. confval:: bodyTag + :name: page-bodyTag + :type: :ref:`data-type-tag` + :default: `` - Property - bodyTag + Body tag on the page - Data type - :ref:`data-type-tag` - - Default - +.. _setup-page-bodytag-example: - Description - Body tag on the page +Example: Set a class on the body tag +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - Example - .. code-block:: typoscript - :caption: EXT:site_package/Configuration/TypoScript/setup.typoscript +.. code-block:: typoscript + :caption: EXT:site_package/Configuration/TypoScript/setup.typoscript - # This will lead to if constant "bodyClass" is set accordingly. - page.bodyTag = + # This will lead to if constant "bodyClass" is set accordingly. + page.bodyTag = -.. index:: PAGE; -.. _setup-page-bodytagadd: +.. index:: PAGE; +.. _setup-page-bodytagadd: bodyTagAdd -========== - -.. container:: table-row +---------- - Property - bodyTagAdd +.. confval:: bodyTagAdd + :name: page-bodyTagAdd + :type: :ref:`data-type-string` - Data type - :ref:`data-type-string` + This content is added inside of the opening :html:`` tag right + before the :html:`>` character. This is mostly useful for adding + attributes to the :html:`` tag. - Description - This content is added inside of the opening :html:`` tag right - before the :html:`>` character. This is mostly useful for adding - attributes to the :html:`` tag. +.. _setup-page-bodytagadd-example: - Example - .. code-block:: typoscript - :caption: EXT:site_package/Configuration/TypoScript/setup.typoscript +Example: Add a parameter to the body tag +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - # This will lead to - page.bodyTagAdd = class="example" +.. code-block:: typoscript + :caption: EXT:site_package/Configuration/TypoScript/setup.typoscript + # This will lead to + page.bodyTagAdd = class="example" - -.. index:: PAGE; bodyTagCObject -.. _setup-page-bodytagcobject: +.. index:: PAGE; bodyTagCObject +.. _setup-page-bodytagcobject: bodyTagCObject ============== -.. container:: table-row - - Property - bodyTagCObject +.. confval:: bodyTagCObject + :name: page-bodyTagCObject + :type: cObject - Data type - cObject + This is the default body tag. It is overridden by :ref:`setup-page-bodyTag`, + if that is set. - Description - This is the default body tag. It is overridden by :ref:`setup-page-bodyTag`, - if that is set. + .. note:: Additionally to the body tag properties noted here, + there also is the property :ref:`setup-config-disableBodyTag`, + which, if set, disables body tag generation independently + from what might be set here. - **Note:** Additionally to the body tag properties noted here, - there also is the property :ref:`setup-config-disableBodyTag`, - which, if set, disables body tag generation independently - from what might be set here. - - -.. index:: PAGE; config -.. _setup-page-config: +.. index:: PAGE; config +.. _setup-page-config: config ====== -.. container:: table-row - - Property - config - - Data type - :ref:`->CONFIG ` +.. confval:: config + :name: page-config + :type: :ref:`->CONFIG ` - Description - Configuration for the page. Any entries made here override the same - entries in the top-level object :ref:`config`. + Configuration for the page. Any entries made here override the same + entries in the top-level object :ref:`config`. -.. index:: PAGE; CSS_inlineStyle -.. _setup-page-css-inlinestyle: +.. index:: PAGE; CSS_inlineStyle +.. _setup-page-css-inlinestyle: CSS\_inlineStyle ================ @@ -347,819 +303,770 @@ CSS\_inlineStyle -.. index:: PAGE; cssInline.[array] -.. _setup-page-cssinline: +.. index:: PAGE; cssInline.[array] +.. _setup-page-cssinline: cssInline.[array] ================= -.. container:: table-row +.. confval:: cssInline.[array] + :name: page-cssInline + :type: :ref:`cObject ` - Property - cssInline.[array] + Allows to add inline CSS to the page :html:`` section. + The :typoscript:`cssInline` property contains any number of numeric keys, each representing one cObject. + Internally handled as PHP integer, maximum number is therefore restricted to :php:`PHP_INT_MAX`. - Data type - :ref:`cObject ` - Description - Allows to add inline CSS to the page :html:`` section. - The :typoscript:`cssInline` property contains any number of numeric keys, each representing one cObject. - Internally handled as PHP integer, maximum number is therefore restricted to :php:`PHP_INT_MAX`. +.. _setup-page-cssinline-example: - Example - .. code-block:: typoscript - :caption: EXT:site_package/Configuration/TypoScript/setup.typoscript +Example: Add inline styles for the h1 tag +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - cssInline { - 10 = TEXT - 10.value = h1 {margin:15px;} +.. code-block:: typoscript + :caption: EXT:site_package/Configuration/TypoScript/setup.typoscript - 20 = TEXT - 20.value = h1 span {color: blue;} - } + cssInline { + 10 = TEXT + 10.value = h1 {margin:15px;} + 20 = TEXT + 20.value = h1 span {color: blue;} + } -.. index:: PAGE; footerData.[array] -.. _setup-page-footerdata: + +.. index:: PAGE; footerData.[array] +.. _setup-page-footerdata: footerData.[array] -================== +------------------ -.. container:: table-row +.. confval:: footerData.[array] + :name: page-footerData + :type: :ref:`cObject ` - Property - footerData.[array] + Same as :ref:`setup-page-headerData`, + except that this block gets included at the bottom of the page + (just before the closing :html:`` tag). - Data type - :ref:`cObject ` + The :typoscript:`footerData` property contains any number of numeric keys, each representing one cObject. + Internally handled as PHP integer, maximum number is therefore restricted to :php:`PHP_INT_MAX`. - Description - Same as :ref:`setup-page-headerData`, - except that this block gets included at the bottom of the page - (just before the closing :html:`` tag). +.. _setup-page-footerdata-example: - The :typoscript:`footerData` property contains any number of numeric keys, each representing one cObject. - Internally handled as PHP integer, maximum number is therefore restricted to :php:`PHP_INT_MAX`. +Example: Add a script and a comment to the page footer +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - Example - .. code-block:: typoscript - :caption: EXT:site_package/Configuration/TypoScript/setup.typoscript +.. code-block:: typoscript + :caption: EXT:site_package/Configuration/TypoScript/setup.typoscript - footerData { - 3 = TEXT - 3.value = + footerData { + 3 = TEXT + 3.value = - 50 = TEXT - 50.value = - } + 50 = TEXT + 50.value = + } -.. index:: PAGE; headerData.[array] -.. _setup-page-headerdata: +.. index:: PAGE; headerData.[array] +.. _setup-page-headerdata: headerData.[array] -================== +------------------ -.. container:: table-row +.. confval:: headerData.[array] + :name: page-headerData + :type: :ref:`cObject ` - Property - headerData.[array] + Inserts custom content in the head section of the website. - Data type - :ref:`cObject ` + While you can also use this to include stylesheet references or JavaScript, + you should better use :ref:`page.includeCSS ` + and :ref:`page.includeJS ` for such files. + Features like file concatenation and file compression will not work on files, + which are included using :typoscript:`headerData`. - Description - Inserts custom content in the head section of the website. + For meta tags, use the dedicated configuration :ref:`page.meta `. - While you can also use this to include stylesheet references or JavaScript, - you should better use :ref:`page.includeCSS ` - and :ref:`page.includeJS ` for such files. - Features like file concatenation and file compression will not work on files, - which are included using :typoscript:`headerData`. + By default, gets inserted after all the style definitions. - For meta tags, use the dedicated configuration :ref:`page.meta `. + The :typoscript:`headerData` property contains any number of numeric keys, each representing one cObject. + Internally handled as PHP integer, maximum number is therefore restricted to :php:`PHP_INT_MAX`. - By default, gets inserted after all the style definitions. +.. _setup-page-headerdata-example: - The :typoscript:`headerData` property contains any number of numeric keys, each representing one cObject. - Internally handled as PHP integer, maximum number is therefore restricted to :php:`PHP_INT_MAX`. +Example: Add a script tag and a comment to the head tag +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - Example - .. code-block:: typoscript - :caption: EXT:site_package/Configuration/TypoScript/setup.typoscript +.. code-block:: typoscript + :caption: EXT:site_package/Configuration/TypoScript/setup.typoscript - page.headerData { - 3 = TEXT - 3.value = - - 50 = TEXT - 50.value = - } + page.headerData { + 3 = TEXT + 3.value = + 50 = TEXT + 50.value = + } -.. index:: PAGE; headTag -.. _setup-page-headtag: +.. index:: PAGE; headTag +.. _setup-page-headtag: headTag -======= - -.. container:: table-row +------- - Property - headTag +.. confval:: headTag + :name: page-headTag + :type: :ref:`data-type-tag` / :ref:`stdwrap` + :Default: `` - Data type - :ref:`data-type-tag` / :ref:`stdwrap` + Head-tag if alternatives are wanted - Default - - - Description - Head-tag if alternatives are wanted - - - -.. index:: PAGE; includeCSS.[array] -.. _setup-page-includecss-array: +.. index:: PAGE; includeCSS.[array] +.. _setup-page-includecss-array: includeCSS.[array] -================== - -.. container:: table-row - - Property - includeCSS.[array] +------------------ - Data type - :ref:`data-type-resource` +.. confval:: includeCSS.[array] + :name: page-includeCSS + :type: :ref:`data-type-resource` - Description - Inserts a stylesheet (just like the :typoscript:`stylesheet` property), but allows - setting up more than a single stylesheet, because you can enter files - in an array. + Inserts a stylesheet (just like the :typoscript:`stylesheet` property), but allows + setting up more than a single stylesheet, because you can enter files + in an array. - The file definition must be a valid :ref:`data-type-resource` data type, - otherwise nothing is inserted. + The file definition must be a valid :ref:`data-type-resource` data type, + otherwise nothing is inserted. - Each file has *optional properties*: + Each file has *optional properties*: - **allWrap**: Wraps the complete tag, useful for conditional - comments. + **allWrap**: Wraps the complete tag, useful for conditional + comments. - **allWrap.splitChar**: Defines an alternative splitting character - (default is "\|" - the vertical line). + **allWrap.splitChar**: Defines an alternative splitting character + (default is "\|" - the vertical line). - **alternate**: If set (boolean) then the rel-attribute will be - "alternate stylesheet". + **alternate**: If set (boolean) then the rel-attribute will be + "alternate stylesheet". - **disableCompression**: If :typoscript:`config.compressCss` is enabled, this - disables the compression of this file. + **disableCompression**: If :typoscript:`config.compressCss` is enabled, this + disables the compression of this file. - **excludeFromConcatenation**: If :typoscript:`config.concatenateCss` is - enabled, this prevents the file from being concatenated. + **excludeFromConcatenation**: If :typoscript:`config.concatenateCss` is + enabled, this prevents the file from being concatenated. - **external**: If set, there is no file existence check. Useful for - inclusion of external files. + **external**: If set, there is no file existence check. Useful for + inclusion of external files. - **forceOnTop**: Boolean flag. If set, this file will be added on top - of all other files. + **forceOnTop**: Boolean flag. If set, this file will be added on top + of all other files. - **if**: Allows to define conditions, which must evaluate to TRUE for - the file to be included. If they do not evaluate to TRUE, the file - will not be included. Extensive usage might cause huge numbers of - temporary files to be created. See ->if for details. + **if**: Allows to define conditions, which must evaluate to TRUE for + the file to be included. If they do not evaluate to TRUE, the file + will not be included. Extensive usage might cause huge numbers of + temporary files to be created. See ->if for details. - .. deprecated:: 11.5 - The option to use the `@import` syntax for including external CSS - files through TypoScript has been deprecated. It is recommended to use - the :html:`` tag or instead create an inline CSS entry with TypoScript - to load a file with the `@import` syntax. + .. deprecated:: 11.5 + The option to use the `@import` syntax for including external CSS + files through TypoScript has been deprecated. It is recommended to use + the :html:`` tag or instead create an inline CSS entry with TypoScript + to load a file with the `@import` syntax. - **import**: If set (boolean) then the `@import` way of including a - stylesheet is used instead of :html:`` + **import**: If set (boolean) then the `@import` way of including a + stylesheet is used instead of :html:`` - **inline**: If set, the content of the CSS file is inlined using - :html:`