diff --git a/Documentation/Functions/Data.rst b/Documentation/Functions/Data.rst index 3442c0343..90d1f6e43 100644 --- a/Documentation/Functions/Data.rst +++ b/Documentation/Functions/Data.rst @@ -6,10 +6,9 @@ Data / getText ============== -:aspect:`Data type:` - getText +.. confval:: data + :name: data -:aspect:`Description:` The getText data type is some kind of tool box allowing to retrieve values from a variety of sources, e.g. from GET/POST variables, from registers, values from the page tree, items in the page menus, records @@ -46,711 +45,799 @@ Data / getText To get the content of the field "header". If "header is empty, "title" is retrieved. If "title" is empty as well, it finally gets the field "uid": - .. code-block:: typoscript - :caption: EXT:site_package/Configuration/TypoScript/setup.typoscript + .. code-block:: typoscript + :caption: EXT:site_package/Configuration/TypoScript/setup.typoscript - lib.foo.data = field : header // field : title // field : uid + lib.foo.data = field : header // field : title // field : uid Properties ========== -.. contents:: - :local: +.. contents:: + :local: -.. _data-type-gettext-applicationcontext: +.. _data-type-gettext-applicationcontext: applicationcontext ------------------ .. versionadded:: 13.0 -:aspect:`getText Key:` - applicationcontext -:aspect:`Description:` - Returns the current :ref:`application context ` - as string. +.. confval:: applicationcontext + :name: data-applicationcontext + + Returns the current :ref:`application context ` + as string. + + +.. _data-type-gettext-applicationcontext-example: + +Example: Evaluate the current application context +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -:aspect:`Example:` - Evaluate if the current application context is "Production": +Evaluate if the current application context is "Production": - .. code-block:: typoscript - :caption: EXT:site_package/Configuration/TypoScript/setup.typoscript +.. code-block:: typoscript + :caption: EXT:site_package/Configuration/TypoScript/setup.typoscript - if { - value.data = applicationcontext - equals = Production - } + if { + value.data = applicationcontext + equals = Production + } -.. _data-type-gettext-cobj: +.. _data-type-gettext-cobj: cObj ---- -:aspect:`getText Key:` - cObj +.. confval:: cObj + :name: data-cObj -:aspect:`Description:` - For :ref:`cobj-content` and :ref:`cobj-records` cObjects that are returned by - a select query, this returns the row number (1,2,3,...) of the current - cObject record. + For :ref:`cobj-content` and :ref:`cobj-records` cObjects that are returned by + a select query, this returns the row number (1,2,3,...) of the current + cObject record. - :typoscript:`parentRecordNumber` is the only key available. + :typoscript:`parentRecordNumber` is the only key available. -:aspect:`Example:` - Get the number of the current cObject record: - .. code-block:: typoscript - :caption: EXT:site_package/Configuration/TypoScript/setup.typoscript +.. _data-type-gettext-cobj-example: - lib.foo.data = cObj : parentRecordNumber +Example: Get the number of the current cObject record +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -.. _data-type-gettext-context: +Get the number of the current cObject record: + +.. code-block:: typoscript + :caption: EXT:site_package/Configuration/TypoScript/setup.typoscript + + lib.foo.data = cObj : parentRecordNumber + +.. _data-type-gettext-context: context ------- -:aspect:`getText Key:` - context +.. confval:: context + :name: data-context + + access values from context API (:ref:`see `). + If a property is an array, it is converted into a comma-separated list. + + Syntax: -:aspect:`Description:` - access values from context API (:ref:`see `). - If a property is an array, it is converted into a comma-separated list. + .. code-block:: none + :caption: TypoScript Syntax - Syntax: + lib.foo.data = context:: - .. code-block:: none - :caption: TypoScript Syntax +.. _data-type-gettext-context-example: - lib.foo.data = context:: +Example: Retrieve current workspace id +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -:aspect:`Example:` - Retrieve current workspace id: +Retrieve current workspace id: - .. code-block:: typoscript - :caption: EXT:site_package/Configuration/TypoScript/setup.typoscript +.. code-block:: typoscript + :caption: EXT:site_package/Configuration/TypoScript/setup.typoscript - page.10 = TEXT - page.10.data = context:workspace:id - page.10.wrap = You are in workspace: | + page.10 = TEXT + page.10.data = context:workspace:id + page.10.wrap = You are in workspace: | -.. _data-type-gettext-current: +.. _data-type-gettext-current: current ------- -:aspect:`getText Key:` - current +.. confval:: current + :name: data-current -:aspect:`Description:` - current (gets the "current" value) + current (gets the "current" value) - .. What is the "current" value? We should explain that. + .. TODO: What is the "current" value? We should explain that. -:aspect:`Example:` - Get the current value: +Example: Get the current value +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - .. code-block:: typoscript - :caption: EXT:site_package/Configuration/TypoScript/setup.typoscript +Get the current value: - lib.foo.data = current +.. code-block:: typoscript + :caption: EXT:site_package/Configuration/TypoScript/setup.typoscript -.. _data-type-gettext-date: + lib.foo.data = current + +.. _data-type-gettext-date: date ---- -:aspect:`getText Key:` - date +.. confval:: date + :name: data-date + :default: :typoscript:`d/m Y` + + Can be used with a colon and :ref:`data-type-date-conf`. -:aspect:`Description:` - Can be used with a colon and :ref:`data-type-date-conf`. +.. _data-type-gettext-date-example: -:aspect:`Default:` - :typoscript:`d/m Y` +Example: Get the current time formatted dd-mm-yy +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -:aspect:`Example:` - Get the current time formatted dd-mm-yy: +Get the current time formatted dd-mm-yy: - .. code-block:: typoscript - :caption: EXT:site_package/Configuration/TypoScript/setup.typoscript +.. code-block:: typoscript + :caption: EXT:site_package/Configuration/TypoScript/setup.typoscript - lib.foo.data = date : d-m-y + lib.foo.data = date : d-m-y -.. _data-type-gettext-db: +.. _data-type-gettext-db: DB -- -:aspect:`getText Key:` - DB +.. confval:: DB + :name: data-db + :Syntax: DB : [table name] : [uid] : [field] + + Value from database. Any record from a table in TCA can be selected here. + Records marked as deleted will not return any value. -:aspect:`Syntax:` - DB : [table name] : [uid] : [field] + In contrast to other keys, colons are used here to get deeper into the + structure, instead of pipes. -:aspect:`Description:` - Value from database. Any record from a table in TCA can be selected here. - Records marked as deleted will not return any value. +.. _data-type-gettext-db-example: - In contrast to other keys, colons are used here to get deeper into the - structure, instead of pipes. +Example: Get a header field value of a record +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -:aspect:`Example:` - Get the value of the header field of record with uid 234 from table - :sql:`tt_content`: +Get the value of the header field of record with uid 234 from table +:sql:`tt_content`: - .. code-block:: typoscript - :caption: EXT:site_package/Configuration/TypoScript/setup.typoscript +.. code-block:: typoscript + :caption: EXT:site_package/Configuration/TypoScript/setup.typoscript - lib.foo.data = DB : tt_content:234:header + lib.foo.data = DB : tt_content:234:header - Get the value of the header field of a record, whose uid is stored in a GET - parameter `myContentId`: +Get the value of the header field of a record, whose uid is stored in a GET +parameter `myContentId`: - .. code-block:: typoscript - :caption: EXT:site_package/Configuration/TypoScript/setup.typoscript +.. code-block:: typoscript + :caption: EXT:site_package/Configuration/TypoScript/setup.typoscript - lib.foo.data.dataWrap = DB : tt_content:{GP : myContentId}:header + lib.foo.data.dataWrap = DB : tt_content:{GP : myContentId}:header - .. note:: - It is safe to directly use a client-/user-provided input for the id of a DB - record here. The function :php:`ContentObjectRenderer->getData` internally - calls the function :php:`PageRepository->getRawRecord`, which converts the - parameter to int via :php:`QueryBuilder->createNamedParameter` +.. note:: + It is safe to directly use a client-/user-provided input for the id of a DB + record here. The function :php:`ContentObjectRenderer->getData` internally + calls the function :php:`PageRepository->getRawRecord`, which converts the + parameter to int via :php:`QueryBuilder->createNamedParameter` -.. _data-type-gettext-debug: +.. _data-type-gettext-debug: debug ----- -:aspect:`getText Key:` - debug -:aspect:`Description:` - Returns HTML-formatted content of the PHP variable defined by the keyword. - Available keywords are :typoscript:`rootLine`, :typoscript:`fullRootLine`, :typoscript:`data`, - :typoscript:`register` and :typoscript:`page`. +.. confval:: debug + :name: data-debug + + Returns HTML-formatted content of the PHP variable defined by the keyword. + Available keywords are :typoscript:`rootLine`, :typoscript:`fullRootLine`, :typoscript:`data`, + :typoscript:`register` and :typoscript:`page`. + +.. _data-type-gettext-debug-example: + +Example: Debug the current root-line +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -:aspect:`Example:` - Outputs the current root-line visually in HTML: - .. code-block:: typoscript - :caption: EXT:site_package/Configuration/TypoScript/setup.typoscript +Outputs the current root-line visually in HTML: - lib.foo.data = debug : rootLine +.. code-block:: typoscript + :caption: EXT:site_package/Configuration/TypoScript/setup.typoscript -.. _data-type-gettext-field: + lib.foo.data = debug : rootLine + +.. _data-type-gettext-field: field ----- -:aspect:`getText Key:` - field +.. confval:: field + :name: data-field + :Syntax: field : [field name from the current :php:`$cObj->data` array in the cObject, multi-dimensional.] + + + This gives read access to the current value of an internal global variable determined by the given key. + + - As default the :php:`$cObj->data` array is :php:`$GLOBALS['TSFE']->page` + (record of the current page) + + - In :ref:`TMENU ` :php:`$cObj->data` is set in a loop to the page-record for + each menu item during its rendering process. -:aspect:`Syntax:` - field : [field name from the current :php:`$cObj->data` array in the cObject, multi-dimensional.] + - In :ref:`cobj-content` / :ref:`cobj-records` :php:`$cObj->data` is set to + the actual record -:aspect:`Description:` - This gives read access to the current value of an internal global variable determined by the given key. + - In :ref:`GIFBUILDER ` :php:`$cObj->data` is set to the data + :ref:`GIFBUILDER ` is supplied with. - - As default the :php:`$cObj->data` array is :php:`$GLOBALS['TSFE']->page` - (record of the current page) +.. _data-type-gettext-field-example: - - In :ref:`TMENU ` :php:`$cObj->data` is set in a loop to the page-record for - each menu item during its rendering process. +Examples +~~~~~~~~ - - In :ref:`cobj-content` / :ref:`cobj-records` :php:`$cObj->data` is set to - the actual record +Example: Get header data +^^^^^^^^^^^^^^^^^^^^^^^^ - - In :ref:`GIFBUILDER ` :php:`$cObj->data` is set to the data - :ref:`GIFBUILDER ` is supplied with. +Get content from :php:`$cObj->data['header']`: -:aspect:`Examples:` - Get content from :php:`$cObj->data['header']`: +.. code-block:: typoscript + :caption: EXT:site_package/Configuration/TypoScript/setup.typoscript - .. code-block:: typoscript - :caption: EXT:site_package/Configuration/TypoScript/setup.typoscript + lib.foo.data = field : header - lib.foo.data = field : header +Example: Get data of a field +^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - Get content from :php:`$cObj->data['fieldname']['level1']['level2']`: +Get content from :php:`$cObj->data['fieldname']['level1']['level2']`: - .. code-block:: typoscript - :caption: EXT:site_package/Configuration/TypoScript/setup.typoscript +.. code-block:: typoscript + :caption: EXT:site_package/Configuration/TypoScript/setup.typoscript - lib.foo.data = field : fieldname|level1|level2 + lib.foo.data = field : fieldname|level1|level2 -.. _data-type-gettext-file: +.. _data-type-gettext-file: file ---- -:aspect:`getText Key:` - file +.. confval:: file + :name: data-file + :Syntax: file : [uid] : [property] -:aspect:`Syntax:` - file : [uid] : [property] + Retrieves a property from a file object (FAL) by identifying it through its + :sql:`sys_file` UID. Note that during execution of the :ref:`cobj-files` cObject, + it is also possible to reference the current file with :confval:`data-current` as UID like + :typoscript:`file : current : size`. -:aspect:`Description:` - Retrieves a property from a file object (FAL) by identifying it through its - sys\_file UID. Note that during execution of the :ref:`cobj-files` cObject, - it's also possible to reference the current file with "current" as UID like - :typoscript:`file : current : size`. + The following properties are available: name, uid, originalUid, size, sha1, + extension, mimetype, contents, publicUrl, modification_date, creation_date - The following properties are available: name, uid, originalUid, size, sha1, - extension, mimetype, contents, publicUrl, modification_date, creation_date + Furthermore when manipulating references (such as images in content elements + or media in pages), additional properties are available (not all are + available all the time, it depends on the setup of *references* of the + :ref:`cobj-files` cObject): title, description, link, alternative. - Furthermore when manipulating references (such as images in content elements - or media in pages), additional properties are available (not all are - available all the time, it depends on the setup of *references* of the - :ref:`cobj-files` cObject): title, description, link, alternative. + Additionally, any data in the "sys_file_metadata" table can be accessed too. - Additionally, any data in the "sys_file_metadata" table can be accessed too. + See the :ref:`FILES ` cObject for usage examples. - See the :ref:`FILES ` cObject for usage examples. +.. _data-type-gettext-file-example: -:aspect:`Example:` - Get the file size of the file with the sys\_file UID 17: +Example: Get the size of a file +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - .. code-block:: typoscript - :caption: EXT:site_package/Configuration/TypoScript/setup.typoscript +Get the file size of the file with the sys\_file UID 17: - lib.foo.data = file : 17 : size +.. code-block:: typoscript + :caption: EXT:site_package/Configuration/TypoScript/setup.typoscript -.. _data-type-gettext-flexform: + lib.foo.data = file : 17 : size + +.. _data-type-gettext-flexform: flexform -------- -:aspect:`getText Key:` - flexform +.. confval:: flexform + :name: data-flexform + :Syntax: flexform : [field containing flexform data].[property of this flexform] + + Access values from FlexForms, for example inside of :sql:`tt_content` record. In contrast + to most parts, deeper levels are accessed through dots, not pipes. -:aspect:`Syntax:` - flexform : [field containing flexform data].[property of this flexform] +.. _data-type-gettext-flexform-example: -:aspect:`Description:` - Access values from flexforms, e.g. inside of tt_content record. In contrast - to most parts, deeper levels are accessed through dots, not pipes. +Example: Get a FlexForm value +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -:aspect:`Example:` - Return the flexform value of given name: +Return the FlexForm value of given name: - .. code-block:: typoscript - :caption: EXT:site_package/Configuration/TypoScript/setup.typoscript +.. code-block:: typoscript + :caption: EXT:site_package/Configuration/TypoScript/setup.typoscript - lib.foo.data = flexform : pi_flexform:settings.categories + lib.foo.data = flexform : pi_flexform:settings.categories -.. _data-type-gettext-fullrootline: +.. _data-type-gettext-fullrootline: fullRootLine ------------ -:aspect:`getText Key:` - fullRootLine - -:aspect:`Syntax:` - fullRootLine : [pointer, integer], [field name], ["slide"] +.. confval:: fullRootLine + :name: data-fullRootLine + :Syntax: fullRootLine : [pointer, integer], [field name], ["slide"] -:aspect:`Description:` - This property can be used to retrieve values from "above" the current page's - root. Take the below page tree and assume that we are on the page "Here you - are!". Using the :ref:`data-type-gettext-levelfield` property, it is possible - to go up only to the page "Site root", because it is the root of a new - (sub-)site. With :typoscript:`fullRootLine` it is possible to go all the way up to page - tree root. The numbers between square brackets indicate to which page each - value of *pointer* would point to: +This property can be used to retrieve values from "above" the current page's +root. Take the below page tree and assume that we are on the page "Here you +are!". Using the :ref:`data-type-gettext-levelfield` property, it is possible +to go up only to the page "Site root", because it is the root of a new +(sub-)site. With :typoscript:`fullRootLine` it is possible to go all the way up to page +tree root. The numbers between square brackets indicate to which page each +value of *pointer* would point to: - .. code-block:: text +.. code-block:: text - - Page tree root [-2] + - Page tree root [-2] |- 1. page before [-1] - |- Site root (root template here!) [0] - |- Here you are! [1] + |- Site root (root template here!) [0] + |- Here you are! [1] +A "slide" parameter can be added just as for the +:ref:`data-type-gettext-levelfield` property. - A "slide" parameter can be added just as for the - :ref:`data-type-gettext-levelfield` property. +.. _data-type-gettext-fullrootline-example: -:aspect:`Example:` - Get the title of the page right before the start of the current website: +Example: Get the title of the previous page +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - .. code-block:: typoscript - :caption: EXT:site_package/Configuration/TypoScript/setup.typoscript +Get the title of the page right before the start of the current website: - lib.foo.data = fullRootLine : -1, title +.. code-block:: typoscript + :caption: EXT:site_package/Configuration/TypoScript/setup.typoscript -.. _data-type-gettext-getenv: + lib.foo.data = fullRootLine : -1, title + +.. _data-type-gettext-getenv: getenv ------ -:aspect:`getText Key:` - getenv +.. confval:: getenv + :name: data-getenv + + Value from PHP environment variables. + + For a cached variation of this feature, please refer to :ref:`getEnv `. -:aspect:`Description:` - Value from PHP environment variables. +.. _data-type-gettext-getenv-example: - For a cached variation of this feature, please refer to :ref:`getEnv `. +Example: Get the HTTP referer +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -:aspect:`Example:` - Get the env var `HTTP_REFERER`: +Get the environment var `HTTP_REFERER`: - .. code-block:: typoscript - :caption: EXT:site_package/Configuration/TypoScript/setup.typoscript +.. code-block:: typoscript + :caption: EXT:site_package/Configuration/TypoScript/setup.typoscript - lib.foo.data = getenv : HTTP_REFERER + lib.foo.data = getenv : HTTP_REFERER -.. _data-type-gettext-getindpenv: +.. _data-type-gettext-getindpenv: getIndpEnv ---------- -:aspect:`getText Key:` - getIndpEnv - -:aspect:`Syntax:` - getIndpEnv : - -:aspect:`Description:` - Returns the value of a *System Environment Variable* denoted by - *name* regardless of server OS, CGI/MODULE version etc. The result is - identical to the :php:`$_SERVER` variable in most cases. This method should - be used instead of *getEnv* to get reliable values for all situations. The - internal processing is handled by - :php:`TYPO3\CMS\Core\Utility\GeneralUtility::getIndpEnv()` - - Available names: - - ===================== ============================================================================= ================= - Name Definition Example or result - ===================== ============================================================================= ================= - \_ARRAY Return an array with all available key-value pairs for debugging purposes - HTTP_ACCEPT_LANGUAGE language(s) accepted by client - HTTP_HOST [host][:[port]] :samp:`example.org:8080` - HTTP_REFERER [scheme]://[host][:[port]][path] :samp:`https://example.org:8080/typo3/32/temp/phpcheck/index.php/arg1/arg2/arg3/?arg1,arg2,arg3&p1=parameter1&p2[key]=value` - HTTP_USER_AGENT client user agent - PATH_INFO [path_info] :samp:`/arg1/arg2/arg3/` - QUERY_STRING [query] :samp:`arg1,arg2,arg3&p1=parameter1&p2[key]=value` - REMOTE_ADDR client IP - REMOTE_HOST client host - REQUEST_URI [path]?[query] :samp:`/typo3/32/temp/phpcheck/index.php/arg1/arg2/arg3/?arg1,arg2,arg3&p1=parameter1&p2[key]=value` - SCRIPT_FILENAME absolute filename of script - SCRIPT_NAME [path_script] :samp:`/typo3/32/temp/phpcheck/[index.php]` - TYPO3_DOCUMENT_ROOT absolute path of root of documents - TYPO3_HOST_ONLY [host] :samp:`example.org` - TYPO3_PORT [port] `8080` - TYPO3_REQUEST_DIR [scheme]://[host][:[port]][path_dir] - TYPO3_REQUEST_HOST [scheme]://[host][:[port]] - TYPO3_REQUEST_SCRIPT [scheme]://[host][:[port]][path_script] - TYPO3_REQUEST_URL [scheme]://[host][:[port]][path]?[query] - TYPO3_REV_PROXY TRUE if this session runs over a well known proxy - TYPO3_SITE_SCRIPT [script / Speaking URL] of the TYPO3 website - TYPO3_SITE_URL [scheme]://[host][:[port]][path_dir] of the TYPO3 website frontend - TYPO3_SSL TRUE if this session uses SSL/TLS (https) - ===================== ============================================================================= ================= - -:aspect:`Example:` - .. code-block:: typoscript - :caption: EXT:site_package/Configuration/TypoScript/setup.typoscript - - # get and output the client IP - page = PAGE - page.10 = TEXT - page.10.stdWrap.data = getIndpEnv : REMOTE_ADDR - page.10.stdWrap.htmlSpecialChars = 1 - -.. _data-type-gettext-global: +.. confval:: getIndpEnv + :name: data-getgetIndpEnvenv + :Syntax: getIndpEnv : + + Returns the value of a *System Environment Variable* denoted by + *name* regardless of server OS, CGI/MODULE version etc. The result is + identical to the :php:`$_SERVER` variable in most cases. This method should + be used instead of *getEnv* to get reliable values for all situations. The + internal processing is handled by + :php:`TYPO3\CMS\Core\Utility\GeneralUtility::getIndpEnv()` + + Available names: + + ===================== ============================================================================= ================= + Name Definition Example or result + ===================== ============================================================================= ================= + \_ARRAY Return an array with all available key-value pairs for debugging purposes + HTTP_ACCEPT_LANGUAGE language(s) accepted by client + HTTP_HOST [host][:[port]] :samp:`example.org:8080` + HTTP_REFERER [scheme]://[host][:[port]][path] :samp:`https://example.org:8080/typo3/32/temp/phpcheck/index.php/arg1/arg2/arg3/?arg1,arg2,arg3&p1=parameter1&p2[key]=value` + HTTP_USER_AGENT client user agent + PATH_INFO [path_info] :samp:`/arg1/arg2/arg3/` + QUERY_STRING [query] :samp:`arg1,arg2,arg3&p1=parameter1&p2[key]=value` + REMOTE_ADDR client IP + REMOTE_HOST client host + REQUEST_URI [path]?[query] :samp:`/typo3/32/temp/phpcheck/index.php/arg1/arg2/arg3/?arg1,arg2,arg3&p1=parameter1&p2[key]=value` + SCRIPT_FILENAME absolute filename of script + SCRIPT_NAME [path_script] :samp:`/typo3/32/temp/phpcheck/[index.php]` + TYPO3_DOCUMENT_ROOT absolute path of root of documents + TYPO3_HOST_ONLY [host] :samp:`example.org` + TYPO3_PORT [port] `8080` + TYPO3_REQUEST_DIR [scheme]://[host][:[port]][path_dir] + TYPO3_REQUEST_HOST [scheme]://[host][:[port]] + TYPO3_REQUEST_SCRIPT [scheme]://[host][:[port]][path_script] + TYPO3_REQUEST_URL [scheme]://[host][:[port]][path]?[query] + TYPO3_REV_PROXY TRUE if this session runs over a well known proxy + TYPO3_SITE_SCRIPT [script / Speaking URL] of the TYPO3 website + TYPO3_SITE_URL [scheme]://[host][:[port]][path_dir] of the TYPO3 website frontend + TYPO3_SSL TRUE if this session uses SSL/TLS (https) + ===================== ============================================================================= ================= + +.. _data-type-gettext-getindpenv-example: + +Example: Get the remote address +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. code-block:: typoscript + :caption: EXT:site_package/Configuration/TypoScript/setup.typoscript + + # get and output the client IP + page = PAGE + page.10 = TEXT + page.10.stdWrap.data = getIndpEnv : REMOTE_ADDR + page.10.stdWrap.htmlSpecialChars = 1 + +.. _data-type-gettext-global: global ------ -:aspect:`getText Key:` - global +.. confval:: global + :name: data-global + :Syntax: global : [variable] -:aspect:`Syntax:` - global : [variable] + Deprecated, use :ref:`data-type-gettext-gp`, :ref:`data-type-gettext-tsfe` or + :ref:`data-type-gettext-getenv`. -:aspect:`Description:` - Deprecated, use :ref:`data-type-gettext-gp`, :ref:`data-type-gettext-tsfe` or - :ref:`data-type-gettext-getenv`. - -.. _data-type-gettext-gp: +.. _data-type-gettext-gp: GP -- -:aspect:`getText Key:` - GP +.. confval:: GP + :name: data-gp + :Syntax: GP : [Value from GET or POST method] + + Get a variable from :php:`$_GET` or :php:`$_POST` where a variable, which + exists in both arrays, is returned from :php:`$_POST`. -:aspect:`Syntax:` - GP : [Value from GET or POST method] +.. _data-type-gettext-gp-example: -:aspect:`Description:` - Get an variable from :php:`$_GET` or :php:`$_POST` where a variable, which - exists in both arrays, is returned from :php:`$_POST`. +Example: Get the input value from query string +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -:aspect:`Examples:` - Get input value from query string &stuff=... +Get input value from query string `&stuff=...` - .. code-block:: typoscript - :caption: EXT:site_package/Configuration/TypoScript/setup.typoscript +.. code-block:: typoscript + :caption: EXT:site_package/Configuration/TypoScript/setup.typoscript - lib.foo.data = GP : stuff + lib.foo.data = GP : stuff - Get input value from query string &stuff[bar]=... +Get input value from query string `&stuff[bar]=...` - .. code-block:: typoscript - :caption: EXT:site_package/Configuration/TypoScript/setup.typoscript +.. code-block:: typoscript + :caption: EXT:site_package/Configuration/TypoScript/setup.typoscript - lib.foo.data = GP : stuff|bar + lib.foo.data = GP : stuff|bar -.. _data-type-gettext-level: +.. _data-type-gettext-level: level ----- -:aspect:`getText Key:` - level +.. confval:: level + :name: data-level + + Get the root line level of the current page. -:aspect:`Description:` - Get the root line level of the current page. +.. _data-type-gettext-level-example: -:aspect:`Example:` - Get the root line level of the current page: +Example: Get the root line level of the current page +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - .. code-block:: typoscript - :caption: EXT:site_package/Configuration/TypoScript/setup.typoscript +.. code-block:: typoscript + :caption: EXT:site_package/Configuration/TypoScript/setup.typoscript - lib.foo.data = level + lib.foo.data = level -.. _data-type-gettext-levelfield: +.. _data-type-gettext-levelfield: levelfield ---------- -:aspect:`getText Key:` - levelfield +.. confval:: levelfield + :name: data-levelfield + :Syntax: levelfield : [pointer, integer], [field name], ["slide"] + + Like :ref:`data-type-gettext-leveltitle` but the field do be fetched from the + record is configurable. + +.. _data-type-gettext-levelfield-example: -:aspect:`Syntax:` - levelfield : [pointer, integer], [field name], ["slide"] +Example: Get a field from a page up in the root-line +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -:aspect:`Description:` - levelfield: Like :ref:`data-type-gettext-leveltitle` et al. but where the - second parameter is the root line field to fetch. +Get the value of the user defined field :sql:`tx_myextension_myfield` in the root line. -:aspect:`Example:` - Get the value of the user defined field user_myExtField in the root line. - Requires additional configuration in - :php:`$GLOBALS['TYPO3_CONF_VARS']['FE']['addRootLineFields']` to include - field. In order that you can use this function, your fieldname 'user_myExtField' needs be included in the comma - separated list of ['addRootLineFields']: +.. code-block:: typoscript + :caption: EXT:my_extension/Configuration/TypoScript/setup.typoscript - .. code-block:: typoscript - :caption: EXT:site_package/Configuration/TypoScript/setup.typoscript + lib.foo.data = levelfield : -1, tx_myextension_myfield, slide - lib.foo.data = levelfield : -1, user_myExtField, slide +Requires additional configuration in +:php:`$GLOBALS['TYPO3_CONF_VARS']['FE']['addRootLineFields']` to include +field. In order that you can use this function, your field-name +:sql:`tx_myextension_myfield` needs be included in the comma +separated list of ['addRootLineFields']: -.. _data-type-gettext-levelmedia: -.. _data-type-gettext-leveluid: -.. _data-type-gettext-leveltitle: +.. code-block:: php + :caption: EXT:my_extension/ext_localconf.php -leveltitle, leveluid, levelmedia --------------------------------- + $GLOBALS['TYPO3_CONF_VARS']['FE']['addRootLineFields'] .= ',tx_myextension_myfield'; -:aspect:`getText Key:` - leveltitle, leveluid or levelmedia +.. _data-type-gettext-levelmedia: + +levelmedia +---------- + +.. confval:: levelmedia + :name: data-levelmedia + :Syntax: levelmedia : [pointer, integer], ["slide"] -:aspect:`Syntax:` - leveltitle, leveluid, levelmedia: [levelTitle, uid or media in - root line, 0- , negative = from behind, " , slide" parameter forces a - walk to the bottom of the root line until there's a "true" value to - return. Useful with levelmedia.] -:aspect:`Description:` - Returns values from up or down the page tree. + Get the media field of a page in the root-line. -:aspect:`Examples:` - Get the title of the page on the first level of the root line: + * Use an absolute level with 0 or a positive integer. + * With a negative integer got x levels up + * The slide parameter slides until there is a non-empty value found. + +.. _data-type-gettext-leveltitle: + +leveltitle +---------- - .. code-block:: typoscript - :caption: EXT:site_package/Configuration/TypoScript/setup.typoscript +.. confval:: leveltitle + :name: data-leveltitle + :Syntax: leveltitle : [pointer, integer], ["slide"] - lib.foo.data = leveltitle : 1 + Get the title of a page in the root-line. - Get the title of the page on the level right below the current page AND if - that is not present, walk to the bottom of the root line until there's a - title: + * Use an absolute level with 0 or a positive integer. + * With a negative integer got x levels up + * The slide parameter slides until there is a non-empty value found. - .. code-block:: typoscript - :caption: EXT:site_package/Configuration/TypoScript/setup.typoscript +Example: Get the title of a page up in the rootline +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - lib.foo.data = leveltitle : -2, slide +Get the title of the page on the first level of the root line: - Get the id of the root-page of the website (level zero): +.. code-block:: typoscript + :caption: EXT:site_package/Configuration/TypoScript/setup.typoscript - .. code-block:: typoscript - :caption: EXT:site_package/Configuration/TypoScript/setup.typoscript + lib.foo.data = leveltitle : 1 - lib.foo.data = leveluid : 0 +Get the title of the page on the level right below the current page AND if +that is not present, walk to the bottom of the root line until there's a +title: + +.. code-block:: typoscript + :caption: EXT:site_package/Configuration/TypoScript/setup.typoscript + + lib.foo.data = leveltitle : -2, slide + +.. _data-type-gettext-leveluid: + +leveluid +-------- -.. _data-type-gettext-lll: +.. confval:: leveluid + :name: data-leveluid + :Syntax: leveluid : [pointer, integer] + + Get the UID of a page in the root-line. + + * Use an absolute level with 0 or a positive integer. + * With a negative integer got x levels up + +.. _data-type-gettext-leveluid-example: + +Example: Get the id of the root-page of the page-tree +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Get the id of the root-page of the website (level zero): + +.. code-block:: typoscript + :caption: EXT:site_package/Configuration/TypoScript/setup.typoscript + + lib.foo.data = leveluid : 0 + + +.. _data-type-gettext-lll: LLL --- -:aspect:`getText Key:` - LLL +.. confval:: LLL + :name: data-lll + :Syntax: LLL: [fileref]:[labelkey] -:aspect:`Description:` - LLL: Reference to a locallang (xlf, xml or php) label. Reference consists of - [fileref]:[labelkey] + Reference to a locallang (xlf, xml or php) label. Reference consists of + [fileref]:[labelkey] -:aspect:`Example:` - Get localized label for logout button: +Example: Get a localized label +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - .. code-block:: typoscript - :caption: EXT:site_package/Configuration/TypoScript/setup.typoscript +Get localized label for logout button: - lib.foo.data = LLL : EXT:felogin/pi1/locallang.xlf:logout +.. code-block:: typoscript + :caption: EXT:site_package/Configuration/TypoScript/setup.typoscript -.. _data-type-gettext-page: + lib.foo.data = LLL : EXT:felogin/Resources/Private/Language/locallang.xlf:logout + +.. _data-type-gettext-page: page ---- -:aspect:`getText Key:` - page +.. confval:: page + :name: data-page + :Syntax: page: [field in the current page record] + + Get the specified field from the current page -:aspect:`Description:` - page: [field in the current page record] +.. _data-type-gettext-page-example: -:aspect:`Example:` - Get the current page title: +Example: Get the current page title +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - .. code-block:: typoscript - :caption: EXT:site_package/Configuration/TypoScript/setup.typoscript +Get the current page title: - lib.foo.data = page : title +.. code-block:: typoscript + :caption: EXT:site_package/Configuration/TypoScript/setup.typoscript -.. _data-type-gettext-pagelayout: + lib.foo.data = page : title + +.. _data-type-gettext-pagelayout: pagelayout ---------- -:aspect:`getText Key:` - pagelayout +.. confval:: pagelayout + :name: data-pagelayout + + Get the current backend layout + +.. _data-type-gettext-pagelayout-example: -:aspect:`Description:` - pagelayout +Example: Get the current backend layout +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -:aspect:`Example:` - Get the current backend layout: +Get the current backend layout: - .. code-block:: typoscript - :caption: EXT:site_package/Configuration/TypoScript/setup.typoscript +.. code-block:: typoscript + :caption: EXT:site_package/Configuration/TypoScript/setup.typoscript - lib.foo.data = pagelayout + lib.foo.data = pagelayout -.. _data-type-gettext-parameters: +.. _data-type-gettext-parameters: parameters ---------- -:aspect:`getText Key:` - parameters +.. confval:: parameters + :name: data-parameters + :Syntax: parameters: [field name from the current :php:`$cObj->parameters` array in the cObject.] -:aspect:`Syntax:` - parameters: [field name from the current :php:`$cObj->parameters` array in the cObject.] + Get the content of a key in :php:`parameters` array of the current cObject. -:aspect:`Description:` - See :ref:`parsefunc`. +.. _data-type-gettext-parameters-examples: - .. Why is parsefunc useful here? +Example: Get the parameter `color` +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -:aspect:`Example:` - Get content from :php:`$cObj->parameters['color']`: +Get content from :php:`$cObj->parameters['color']`: - .. code-block:: typoscript - :caption: EXT:site_package/Configuration/TypoScript/setup.typoscript +.. code-block:: typoscript + :caption: EXT:site_package/Configuration/TypoScript/setup.typoscript - lib.foo.data = parameters : color + lib.foo.data = parameters : color -.. _data-type-gettext-path: +.. _data-type-gettext-path: path ---- -:aspect:`getText Key:` - path +.. confval:: path + :name: data-path -:aspect:`Description:` - Path to a file, possibly placed in an extension, returns empty if the file - does not exist. + Path to a file, possibly placed in an extension, returns empty if the file + does not exist. -:aspect:`Example:` - Get path to file rsaauth.js (inside extension rsaauth) relative to siteroot: +.. _data-type-gettext-path-example: - .. code-block:: typoscript - :caption: EXT:site_package/Configuration/TypoScript/setup.typoscript +Example: Resolve the path to a file +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - lib.foo.data = path : EXT:rsaauth/resources/rsaauth.js +Get path to file rsaauth.js (inside extension rsaauth) relative to siteroot: - It can also be helpful in combination with the stdWrap function - :ref:`stdwrap-insertData`: +.. code-block:: typoscript + :caption: EXT:site_package/Configuration/TypoScript/setup.typoscript - .. code-block:: typoscript - :caption: EXT:site_package/Configuration/TypoScript/setup.typoscript + lib.foo.data = path : EXT:rsaauth/resources/rsaauth.js - page.headerData.10 = TEXT - page.headerData.10 { - value = - insertData = 1 - } +It can also be helpful in combination with the stdWrap function +:ref:`stdwrap-insertData`: -.. _data-type-gettext-register: +.. code-block:: typoscript + :caption: EXT:site_package/Configuration/TypoScript/setup.typoscript + + page.headerData.10 = TEXT + page.headerData.10 { + data = path : EXT:site/Resources/Public/Images/logo.png + wrap = + } + +.. _data-type-gettext-register: register -------- -:aspect:`getText Key:` - register +.. confval:: register + :name: data-register + :Syntax: register: [field name from the :php:`$GLOBALS['TSFE']->register`] + + See :ref:`LOAD_REGISTER `. -:aspect:`Syntax` - register: [field name from the :php:`$GLOBALS['TSFE']->register`] +.. _data-type-gettext-register-example: -:aspect:`Description:` - See :ref:`LOAD_REGISTER `. +Example: Get the content of a register +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -:aspect:`Example:` - Get content from :php:`$GLOBALS['TSFE']->register['color']`: +Get content from :php:`$GLOBALS['TSFE']->register['color']`: - .. code-block:: typoscript - :caption: EXT:site_package/Configuration/TypoScript/setup.typoscript +.. code-block:: typoscript + :caption: EXT:site_package/Configuration/TypoScript/setup.typoscript - lib.foo.data = register : color + lib.foo.data = register : color -.. _data-type-gettext-session: +.. _data-type-gettext-session: session ------- -:aspect:`getText Key:` - session +.. confval:: session + :name: data-session + :Syntax: session : [key] -:aspect:`Syntax:` - session : [key] + The `key` refers to the session key used to store the value. -:aspect:`Description:` - The :typoscript:`key` refers to the session key used to store the value. +.. _data-type-gettext-session-example: -:aspect:`Example:` - Get the number of items of a stored shopping cart array/object: +Example: Get a value stored in the current session +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - .. code-block:: typoscript - :caption: EXT:site_package/Configuration/TypoScript/setup.typoscript +Get the number of items of a stored shopping cart array/object: - lib.foo.data = session : shop_cart|itemCount +.. code-block:: typoscript + :caption: EXT:site_package/Configuration/TypoScript/setup.typoscript + + lib.foo.data = session : shop_cart|itemCount .. _data-type-site: @@ -758,14 +845,15 @@ session site ---- -:aspect:`Data type:` - site +.. confval:: site + :name: data-site + :Syntax: site : [key] -:aspect:`Description:` Accessing the current :ref:`site configuration `. -:aspect:`Possible values:` + .. rubric:: Possible keys: + :typoscript:`attributes` Additional parameters configured for this site. @@ -784,22 +872,26 @@ site :typoscript:`websiteTitle` The website title of this site. -:aspect:`Example:` - .. code-block:: typoscript - :caption: EXT:site_package/Configuration/TypoScript/setup.typoscript +.. _data-type-site-example: - page.10 = TEXT - page.10.data = site:base - page.10.wrap = This is your base URL: | +Example: Get values from the current site +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - Where :typoscript:`site` is the keyword for accessing an aspect, and the - following parts are the configuration key(s) to access. +.. code-block:: typoscript + :caption: EXT:site_package/Configuration/TypoScript/setup.typoscript - .. code-block:: typoscript - :caption: EXT:site_package/Configuration/TypoScript/setup.typoscript + page.10 = TEXT + page.10.data = site:base + page.10.wrap = This is your base URL: | - page.10 = TEXT - page.10.data = site:customConfigKey.nested.value +Where :typoscript:`site` is the keyword for accessing an aspect, and the +following parts are the configuration key(s) to access. + +.. code-block:: typoscript + :caption: EXT:site_package/Configuration/TypoScript/setup.typoscript + + page.10 = TEXT + page.10.data = site:customConfigKey.nested.value .. _data-type-siteLanguage: @@ -807,14 +899,16 @@ site siteLanguage ------------ -:aspect:`Data type:` - siteLanguage +.. confval:: siteLanguage + :name: data-siteLanguage + :Syntax: siteLanguage : [key] -:aspect:`Description:` Accessing the current :ref:`site language configuration `. -:aspect:`Possible values:` + + .. rubric:: Possible keys: + :typoscript:`attributes` Additional parameters configured for this site language. @@ -858,21 +952,25 @@ siteLanguage The website title for this language. No automatic fallback to the :typoscript:`site:websiteTitle`! -:aspect:`Example:` - .. code-block:: typoscript - :caption: EXT:site_package/Configuration/TypoScript/setup.typoscript +.. _data-type-siteLanguage-example: - page.10 = TEXT - page.10.data = siteLanguage:navigationTitle - page.10.wrap = This is the title of the current site language: | +Example: Get values from the current site language +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - page.20 = TEXT - page.20.dataWrap = The current site language's locale is {siteLanguage:locale} +.. code-block:: typoscript + :caption: EXT:site_package/Configuration/TypoScript/setup.typoscript - # Website title for the current language with fallback - # to the website title of the site configuration. - page.30 = TEXT - page.30.data = siteLanguage:websiteTitle // site:websiteTitle + page.10 = TEXT + page.10.data = siteLanguage:navigationTitle + page.10.wrap = This is the title of the current site language: | + + page.20 = TEXT + page.20.dataWrap = The current site language's locale is {siteLanguage:locale} + + # Website title for the current language with fallback + # to the website title of the site configuration. + page.30 = TEXT + page.30.data = siteLanguage:websiteTitle // site:websiteTitle .. _data-type-siteSettings: @@ -881,43 +979,36 @@ siteSettings .. versionadded:: 12.1 -:aspect:`Data type:` - siteSettings +.. confval:: siteSettings + :name: data-siteSettings -:aspect:`Description:` Access the :ref:`site settings ` for the current site. -:aspect:`Example:` - .. code-block:: typoscript - :caption: EXT:site_package/Configuration/TypoScript/setup.typoscript +.. _data-type-siteSettings-example: - page.10 = TEXT - page.10.data = siteSettings:redirects.httpStatusCode +Example: Access the redirects HTTP status code +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.. code-block:: typoscript + :caption: EXT:site_package/Configuration/TypoScript/setup.typoscript -.. _data-type-gettext-tsfe: + page.10 = TEXT + page.10.data = siteSettings:redirects.httpStatusCode -TSFE ----- - -:aspect:`getText Key:` - TSFE -:aspect:`Syntax:` - TSFE: [value from the :php:`$GLOBALS['TSFE']` array, multi-dimensional] +.. _data-type-gettext-tsfe: -:aspect:`Description:` - Returns a value from - :php:`TYPO3\CMS\Frontend\Controller\TypoScriptFrontendController`. +TSFE +---- -:aspect:`Example:` - Get the "username" field of the current FE user: +.. confval:: TSFE + :name: data-tsfe + :Syntax: TSFE: [value from the :php:`$GLOBALS['TSFE']` array, multi-dimensional] - .. code-block:: typoscript - :caption: EXT:site_package/Configuration/TypoScript/setup.typoscript + Returns a value from + :php:`TYPO3\CMS\Frontend\Controller\TypoScriptFrontendController`. - lib.foo.data = TSFE : fe_user|user|username .. versionchanged:: 13.0 The following properties within TypoScriptFrontendController (TSFE) have @@ -932,3 +1023,16 @@ TSFE Migrate these properties to use the config property. You can access the TypoScript properties directly, for example, via :typoscript:`lib.something.data = TSFE:config|config|fileTarget` + + +.. _data-type-gettext-tsfe-example: + +Example: Get the username field of the current frontend user +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Get the "username" field of the current FE user: + +.. code-block:: typoscript + :caption: EXT:site_package/Configuration/TypoScript/setup.typoscript + + lib.foo.data = TSFE : fe_user|user|username