From 2df7dac229da5c22979dedc74ea71dbbb1c70ae3 Mon Sep 17 00:00:00 2001 From: "lina.wolf" Date: Sun, 21 Jul 2024 13:48:16 +0200 Subject: [PATCH] [TASK] Document the viewhelper directive --- .../Reference/Content/ViewHelper.rst | 56 +++++++++++++++++++ .../Content/_ViewHelper/_Content.rst.txt | 5 ++ .../Content/_ViewHelper/_NoIndex.rst.txt | 9 +++ .../Content/_ViewHelper/_SortBy.rst.txt | 22 ++++++++ .../Content/_ViewHelper/_Source.rst.txt | 16 ++++++ .../_ViewHelper/_global_viewhelpers_demo.json | 31 ++++++++++ 6 files changed, 139 insertions(+) create mode 100644 Documentation/WritingReST/Reference/Content/ViewHelper.rst create mode 100644 Documentation/WritingReST/Reference/Content/_ViewHelper/_Content.rst.txt create mode 100644 Documentation/WritingReST/Reference/Content/_ViewHelper/_NoIndex.rst.txt create mode 100644 Documentation/WritingReST/Reference/Content/_ViewHelper/_SortBy.rst.txt create mode 100644 Documentation/WritingReST/Reference/Content/_ViewHelper/_Source.rst.txt create mode 100644 Documentation/WritingReST/Reference/Content/_ViewHelper/_global_viewhelpers_demo.json diff --git a/Documentation/WritingReST/Reference/Content/ViewHelper.rst b/Documentation/WritingReST/Reference/Content/ViewHelper.rst new file mode 100644 index 00000000..5af7944d --- /dev/null +++ b/Documentation/WritingReST/Reference/Content/ViewHelper.rst @@ -0,0 +1,56 @@ +:navigation-title: ViewHelper +.. include:: /Includes.rst.txt +.. _viewhelper: + +============================================= +Display Fluid ViewHelpers in ReStructuredText +============================================= + +The special `.. typo3:viewhelper::` directive can be used to display the +information about a Fluid ViewHelper, including all arguments. + +The information on the available arguments is included from a `.json` file. +See also https://github.com/TYPO3-Documentation/fluid-documentation-generator +on how to generate the input file. + +.. warning:: + Usage of the viewhelper directive outside of the + :ref:`Fluid ViewHelper Reference ` is still considered + experimental. + +.. _viewhelper-example: + +Example: Display a ViewHelper from a JSON include +================================================= + +.. code-block:: rst + :caption: Documentation/MyViewHelper.rst + + .. typo3:viewhelper:: link.external + :source: /resources/global_viewhelpers_demo.json + +.. literalinclude:: _ViewHelper/_global_viewhelpers_demo.json + :language: json + :caption: Documentation/resources/global_viewhelpers_demo.json + + +.. _viewhelper-properties: + +Properties of the `viewhelper` directive +======================================== + +.. confval-menu:: + :display: table + :type: + + .. include:: _ViewHelper/_Content.rst.txt + :show-buttons: + + .. include:: _ViewHelper/_Source.rst.txt + :show-buttons: + + .. include:: _ViewHelper/_SortBy.rst.txt + :show-buttons: + + .. include:: _ViewHelper/_NoIndex.rst.txt + :show-buttons: diff --git a/Documentation/WritingReST/Reference/Content/_ViewHelper/_Content.rst.txt b/Documentation/WritingReST/Reference/Content/_ViewHelper/_Content.rst.txt new file mode 100644 index 00000000..193f705b --- /dev/null +++ b/Documentation/WritingReST/Reference/Content/_ViewHelper/_Content.rst.txt @@ -0,0 +1,5 @@ +.. confval:: [content] + :name: directive-viewhelper-content + :type: string + + Name of the ViewHelper as used as key in the the JSON include file. diff --git a/Documentation/WritingReST/Reference/Content/_ViewHelper/_NoIndex.rst.txt b/Documentation/WritingReST/Reference/Content/_ViewHelper/_NoIndex.rst.txt new file mode 100644 index 00000000..bda69c98 --- /dev/null +++ b/Documentation/WritingReST/Reference/Content/_ViewHelper/_NoIndex.rst.txt @@ -0,0 +1,9 @@ +.. confval:: :noindex: + :name: directive-viewhelper-noindex + :type: bool + + If set the ViewHelper will only be displayed but cannot be linked and is not + added to any indexes. This is useful if the same ViewHelper should be + displayed in several places within the same document. In such a case there + would be a clash of identifiers and warnings in the rendering if `:noindex:` + is not set. diff --git a/Documentation/WritingReST/Reference/Content/_ViewHelper/_SortBy.rst.txt b/Documentation/WritingReST/Reference/Content/_ViewHelper/_SortBy.rst.txt new file mode 100644 index 00000000..51459440 --- /dev/null +++ b/Documentation/WritingReST/Reference/Content/_ViewHelper/_SortBy.rst.txt @@ -0,0 +1,22 @@ +.. confval:: :sortBy: + :name: directive-viewhelper-sortBy + :type: string + :default: `name` + + Ordering of the argument list. + + name + Sort the arguments alphabetically by name + + json + Sort the arguments in the order they appear in the JSON file. + + .. code-block:: rst + + .. typo3:viewhelper:: split + :source: resources/global_viewhelpers_demo.json + :sortBy: name + + .. typo3:viewhelper:: image + :source: resources/global_viewhelpers_demo.json + :sortBy: json diff --git a/Documentation/WritingReST/Reference/Content/_ViewHelper/_Source.rst.txt b/Documentation/WritingReST/Reference/Content/_ViewHelper/_Source.rst.txt new file mode 100644 index 00000000..01c15867 --- /dev/null +++ b/Documentation/WritingReST/Reference/Content/_ViewHelper/_Source.rst.txt @@ -0,0 +1,16 @@ +.. confval:: :source: + :name: directive-viewhelper-source + :type: string, local file path, relative or absolute + + Path to the source JSON file to be included. Can be relative or absolute. + + .. code-block:: rst + + .. viewhelper:: my.viewhelper + :source: /some/absolute/path/_includes/_my_viewhelper.json + + .. viewhelper:: my.viewhelper + :source: ../_includes/_my_viewhelper.json + + The path is calculated starting from the :path:`Documentation` directory. + It is not possible to include files from different locations in an extension. diff --git a/Documentation/WritingReST/Reference/Content/_ViewHelper/_global_viewhelpers_demo.json b/Documentation/WritingReST/Reference/Content/_ViewHelper/_global_viewhelpers_demo.json new file mode 100644 index 00000000..b29f8b1b --- /dev/null +++ b/Documentation/WritingReST/Reference/Content/_ViewHelper/_global_viewhelpers_demo.json @@ -0,0 +1,31 @@ + +{ + "namespace": "http://typo3.org/ns/TYPO3/CMS/Fluid/ViewHelpers", + "viewHelpers": { + "split": { + "className": "TYPO3Fluid\\Fluid\\ViewHelpers\\SplitViewHelper", + "...": "..." + }, + "link.external":{ + "className": "TYPO3\\CMS\\Fluid\\ViewHelpers\\Link\\ExternalViewHelper", + "namespace": "TYPO3\\CMS\\Fluid\\ViewHelpers", + "name": "Link\\ExternalViewHelper", + "tagName": "link.external", + "documentation": "A ViewHelper for creating links to external targets.\n\nExamples\n========\n...", + "xmlNamespace": "http://typo3.org/ns/TYPO3/CMS/Fluid/ViewHelpers", + "docTags": {}, + "argumentDefinitions": { + "uri": { + "name": "uri", + "type": "string", + "description": "The URI that will be put in the href attribute of the rendered link tag", + "required": true, + "defaultValue": null, + "escape": null + } + }, + "allowsArbitraryArguments": true + }, + "...": "..." + } +} \ No newline at end of file