From 047c347a713bbe1a0a0dc23071afc52516bfd129 Mon Sep 17 00:00:00 2001
From: Simon Praetorius <simon@praetorius.me>
Date: Thu, 16 Jan 2025 17:21:20 +0100
Subject: [PATCH] [DOCS] Getting started chapter

---
 Documentation/Usage/GettingStarted.rst | 141 +++++++++++++++++++++++--
 1 file changed, 133 insertions(+), 8 deletions(-)

diff --git a/Documentation/Usage/GettingStarted.rst b/Documentation/Usage/GettingStarted.rst
index d5fa29b1..ade0cf8e 100644
--- a/Documentation/Usage/GettingStarted.rst
+++ b/Documentation/Usage/GettingStarted.rst
@@ -6,16 +6,141 @@
 Getting Started
 ===============
 
-TODO
+Before you can start writing your own Fluid template files, you first need to make
+sure that the environment is set up properly. If you are using a framework like
+TYPO3, this might already the case. However, if you are starting from scratch, you
+need do some preparations in PHP first:
 
-* creating a view
-* assigning variables
-* using ViewHelpers
-* using Partials and Layouts
-* debugging, _all
+.. _create-view:
 
+Creating a View
+===============
+
+Fluid comes with a bunch of PHP classes that allow you to open Fluid template files,
+assign variables to them and then render them to get the desired result. To get started,
+you need to be aware of `TemplateView`, the `RenderingContext` and `TemplatePaths`.
+
+*   The `TemplateView` is the "view part" in the Model-View-Controller pattern. It is the
+    main API between your PHP application and the template file. Each `TemplateView` renders
+    exactly one template file (which can have a layout file and can also include other templates,
+    called partials).
+*   The `RenderingContext` is kind of self-describing: It contains all context necessary to
+    render the template. At first, you might only use it to define the path to your Fluid
+    template file via ...
+*   `TemplatePaths`, which is usually a sub-object of the rendering context. It provides multiple
+    ways to define the location(s) to your template files.
+
+To render a template file called `MyTemplate.html`, which is located in `/path/to/templates/`,
+you first create a `TemplateView` object:
+
+.. code-block:: php
+
+    $view = new \TYPO3Fluid\Fluid\View\TemplateView();
+
+Then you can access the `TemplatePaths` and provide the location to your template file, for
+example like this:
+
+.. code-block:: php
+
+    $view->getRenderingContext()->getTemplatePaths()->setTemplateRootPaths(['/path/to/templates/']);
+
+Finally, you can render the desired template:
+
+.. code-block:: php
+
+    $view->render('MyTemplate');
+
+By default, `.html` is used as file extension. If you want to change this, you can specify a different
+format in `TemplatePaths`:
+
+.. code-block:: php
+
+    $view->getRenderingContext()->getTemplatePaths()->setFormat('xml');
+    $view->render('MyTemplate');
+
+Which would then render `MyTemplate.xml`.
+
+.. _assign-variables:
+
+Assigning Variables
+===================
+
+To be able to access data available in your PHP script, you need to assign that data to your view
+as a variable:
+
+.. code-block:: php
+
+    $myData = obtainMyDataFromSomewhere();
+    $view->assign('myData', $myData);
+
+You can also assign multiple variables at once:
+
+.. code-block:: php
+
+    $view->assignMultiple([
+        'title' => $myTitle,
+        'description' => $myDescription,
+    ]);
+
+Those variables can then be accessed in your template file:
+
+.. code-block:: html
+
+    <h1>{title}</h1>
+    <p>{description}</p>
+
+See also the dedicated chapter about :ref:`Variables <variables>`.
+
+.. _using-viewhelpers
+
+Using ViewHelpers
+=================
+
+Within Fluid templates, it is possible to use some controll structures to implement simple
+logic. It is also possible to perform some data modification. Both is possible by using
+so-called ViewHelpers.
+
+With the :ref:`<f:if> ViewHelper <typo3fluid-fluid-if>`, you can implement simple if-then-else
+logic, for example:
+
+.. code-block:: xml
+
+    <f:if condition="{title}">
+        <f:then>
+            <h1>{title}</h1>
+        </f:then>
+        <f:else>
+            <h1>Default Title</h1>
+        </f:else>
+    </f:if>
+
+With the :ref:`<f:format.case> ViewHelper <typo3fluid-fluid-format-case>` you can convert a
+variable to uppercase or lowercase letters:
+
+.. code-block:: xml
+
+    <h1><f:format.case mode="upper">{title}</f:format.case></h1>
+
+Which would result in an all-uppercase headline.
+
+See also the dedicated chapter about :ref:`ViewHelpers <what-are-viewhelpers>` as well
+as the :ref:`ViewHelper reference <viewhelper-reference>` for more details.
+
+.. _debugging
+
+Inspecting and Debugging Templates
+==================================
+
+If you encounter a problem in your template or you just want to know what
+data is available, you can use the :ref:`<f:debug> ViewHelper <typo3fluid-fluid-debug>`:
+
+..  code-block:: xml
+
+    <f:debug>{myVariable}</f:debug>
 
+If you want to get an overview of all available variables, you can use the special
+variable `{_all}`:
 
-debugging
+..  code-block:: xml
 
-_all
+    <f:debug>{_all}</f:debug>