Add documentation

sebkln · Aug 21, 2016 · 36660ad · 36660ad
1 parent 56e93fe
commit 36660ad
Show file tree

Hide file tree

Showing 22 changed files with 793 additions and 0 deletions.
diff --git a/Documentation/Administrator/Index.rst b/Documentation/Administrator/Index.rst
@@ -0,0 +1,49 @@
+.. ==================================================
+.. FOR YOUR INFORMATION
+.. --------------------------------------------------
+.. -*- coding: utf-8 -*- with BOM.
+
+.. include:: ../Includes.txt
+
+
+.. _admin-manual:
+
+Administrator Manual
+====================
+
+.. _admin-installation:
+
+Installation
+------------
+
+To install the extension, perform the following steps:
+
+#. Go to the Extension Manager
+#. Load and install the extension
+#. Include the static template *Select list with Ajax call (ajaxselectlist)* into your TypoScript template
+#. Add permissions for the plugin and records for your editors
+
+.. attention::
+
+   The Ajax request that loads the records depends on **jQuery**. You have to include jQuery in your website if not already done. This extension does not implement jQuery for you.
+
+   If you know JavaScript you can just use *XMLHttpRequest()* and ignore jQuery. The JavaScript is part of the *List.html* template.
+
+.. figure:: ../Images/AdministratorManual/ExtensionManager.png
+   :alt: ajaxselectlist in the Extension Manager
+
+   *ajaxselectlist* in the Extension Manager
+
+.. figure:: ../Images/AdministratorManual/IncludeStaticTemplate.png
+   :alt: Include the static template
+
+   Include the static template
+
+.. _admin-configuration:
+
+Configuration
+-------------
+
+After completing the above steps, the plugin and records can be created. The plugin will already load your records in the frontend.
+
+However, you'll want to modify the Fluid templates to fit your design and needs. The :ref:`configuration` covers TypoScript settings and :ref:`configuration-templates`.
diff --git a/Documentation/ChangeLog/Index.rst b/Documentation/ChangeLog/Index.rst
@@ -0,0 +1,14 @@
+.. ==================================================
+.. FOR YOUR INFORMATION
+.. --------------------------------------------------
+.. -*- coding: utf-8 -*- with BOM.
+
+.. include:: ../Includes.txt
+
+
+.. _changelog:
+
+ChangeLog
+=========
+
+You can find an overview of all changes in the `GitHub commit log <https://github.com/sebkln/ajaxselectlist/commits/master>`__
diff --git a/Documentation/Configuration/Constants/Index.rst b/Documentation/Configuration/Constants/Index.rst
@@ -0,0 +1,94 @@
+.. ==================================================
+.. FOR YOUR INFORMATION
+.. --------------------------------------------------
+.. -*- coding: utf-8 -*- with BOM.
+
+.. include:: ../../Includes.txt
+
+
+.. _configuration-constants:
+
+TypoScript Constants Reference
+==============================
+
+:typoscript:`plugin.tx_ajaxselectlist_selectlist`
+
+.. container:: ts-properties
+
+	=========================== ========================================= ===============================================
+	Property                    Data type                                 Default
+	=========================== ========================================= ===============================================
+	view.templateRootPath_      :ref:`t3tsref:data-type-path`             EXT:ajaxselectlist/Resources/Private/Templates/
+	view.partialRootPath_       :ref:`t3tsref:data-type-path`             EXT:ajaxselectlist/Resources/Private/Partials/
+	view.layoutRootPath_        :ref:`t3tsref:data-type-path`             EXT:ajaxselectlist/Resources/Private/Layouts/
+	settings.typeNum_           :ref:`t3tsref:data-type-positive-integer` 427590
+	=========================== ========================================= ===============================================
+
+Property details
+^^^^^^^^^^^^^^^^
+
+.. _templateRootPath:
+
+view.templateRootPath
+"""""""""""""""""""""
+.. container:: table-row
+
+   Property
+         view.templateRootPath
+   Data type
+         path
+   Description
+         Path to the templates for this extension. See :ref:`Changing Templates <configuration-templates>` how to use this.
+   Default
+         :typoscript:`EXT:ajaxselectlist/Resources/Private/Templates/`
+
+.. _partialRootPath:
+
+view.partialRootPath
+""""""""""""""""""""
+.. container:: table-row
+
+   Property
+         view.partialRootPath
+   Data type
+         path
+   Description
+         Path to the partials for this extension. See :ref:`Changing Templates <configuration-templates>` how to use this.
+
+         .. note:: By default no partials are used by this extension. You're free to add some.
+   Default
+         :typoscript:`EXT:ajaxselectlist/Resources/Private/Partials/`
+
+.. _layoutRootPath:
+
+view.layoutRootPath
+"""""""""""""""""""
+.. container:: table-row
+
+   Property
+         view.layoutRootPath
+   Data type
+         path
+   Description
+         Path to the layout for this extension. See :ref:`Changing Templates <configuration-templates>` how to use this.
+   Default
+         :typoscript:`EXT:ajaxselectlist/Resources/Private/Templates/`
+
+.. _settings.typeNum:
+
+settings.typeNum
+""""""""""""""""
+.. container:: table-row
+
+   Property
+         settings.typeNum
+   Data type
+         positive integer
+   Description
+         This determines the ``PAGE`` object that will be used to render the result of the Ajax call.
+
+         .. attention::
+
+           Currently this setting is only used in the Fluid `f:form` Viewhelper. If you have to change it, you'll have to set the new typeNum in the ``PAGE`` object separately. This may be fixed in future versions.
+   Default
+         :typoscript:`427590`
diff --git a/Documentation/Configuration/Index.rst b/Documentation/Configuration/Index.rst
@@ -0,0 +1,20 @@
+.. ==================================================
+.. FOR YOUR INFORMATION
+.. --------------------------------------------------
+.. -*- coding: utf-8 -*- with BOM.
+
+.. include:: ../Includes.txt
+
+
+.. _configuration:
+
+Configuration Reference
+=======================
+
+.. toctree::
+	:maxdepth: 5
+	:titlesonly:
+
+    	Constants/Index
+       	Setup/Index
+       	Templates/Index
diff --git a/Documentation/Configuration/Setup/Index.rst b/Documentation/Configuration/Setup/Index.rst
@@ -0,0 +1,167 @@
+.. ==================================================
+.. FOR YOUR INFORMATION
+.. --------------------------------------------------
+.. -*- coding: utf-8 -*- with BOM.
+
+.. include:: ../../Includes.txt
+
+
+.. _configuration-typoscript:
+
+TypoScript Setup Reference
+==========================
+
+:typoscript:`plugin.tx_ajaxselectlist_selectlist`
+
+Properties
+^^^^^^^^^^
+
+.. container:: ts-properties
+
+	=========================== ================================================= =======================================================
+	Property                    Data type                                         Default
+	=========================== ================================================= =======================================================
+	view.templateRootPaths_     array of file paths with :ref:`stdWrap <stdwrap>` *array with fallback path and constant value*
+	view.partialRootPaths_      array of file paths with :ref:`stdWrap <stdwrap>` *array with fallback path and constant value*
+	view.layoutRootPaths_       array of file paths with :ref:`stdWrap <stdwrap>` *array with fallback path and constant value*
+	persistence.storagePid_     :ref:`t3tsref:data-type-page-id`                  *not set*
+	settings.typeNum_           :ref:`t3tsref:data-type-positive-integer`                      :typoscript:`{$plugin.tx_ajaxselectlist_selectlist.settings.typeNum}`
+	=========================== ================================================= =======================================================
+
+Property details
+^^^^^^^^^^^^^^^^
+
+.. _templateRootPaths:
+
+view.templateRootPaths
+""""""""""""""""""""""
+.. container:: table-row
+
+   Property
+         view.templateRootPaths
+   Data type
+         array of file paths with :ref:`stdWrap <stdwrap>`
+   Description
+         Array of paths to the templates for this extension. See :ref:`Changing Templates <configuration-templates>` how to use this.
+   Default
+         .. code-block:: typoscript
+
+              view.templateRootPaths {
+                 0 = EXT:ajaxselectlist/Resources/Private/Templates/
+                 1 = {$plugin.tx_ajaxselectlist_selectlist.view.templateRootPath}
+              }
+
+.. _partialRootPaths:
+
+view.partialRootPaths
+"""""""""""""""""""""
+.. container:: table-row
+
+   Property
+         view.partialRootPaths
+   Data type
+         array of file paths with :ref:`stdWrap <stdwrap>`
+   Description
+         Array of paths to the partials for this extension. See :ref:`Changing Templates <configuration-templates>` how to use this.
+
+         .. note:: By default no partials are used by this extension. You're free to add some.
+   Default
+         .. code-block:: typoscript
+
+              view.partialRootPaths {
+                 0 = EXT:ajaxselectlist/Resources/Private/Partials/
+                 1 = {$plugin.tx_ajaxselectlist_selectlist.view.partialRootPath}
+              }
+
+.. _layoutRootPaths:
+
+view.layoutRootPaths
+""""""""""""""""""""
+.. container:: table-row
+
+   Property
+         view.layoutRootPaths
+   Data type
+         array of file paths with :ref:`stdWrap <stdwrap>`
+   Description
+         Array of paths to the layout for this extension. See :ref:`Changing Templates <configuration-templates>` how to use this.
+   Default
+         .. code-block:: typoscript
+
+              view.layoutRootPaths {
+                 0 = EXT:ajaxselectlist/Resources/Private/Layouts/
+                 1 = {$plugin.tx_ajaxselectlist_selectlist.view.layoutRootPath}
+              }
+
+.. _tsstoragePid:
+
+persistence.storagePid
+""""""""""""""""""""""
+.. container:: table-row
+
+   Property
+         persistence.storagePid
+   Data type
+         page_id
+   Description
+         Comma-separated list of pages (UIDs) which contain records for this extension.
+
+         .. warning::
+
+            If set, this overwrites all directories you set in the Plugin's backend form!
+   Default
+         *not set*
+
+.. only:: html
+
+	.. contents::
+		:local:
+		:depth: 1
+
+.. _tstypeNum:
+
+settings.typeNum
+""""""""""""""""
+.. container:: table-row
+
+   Property
+         settings.typeNum
+   Data type
+         positive integer
+   Description
+         This determines the ``PAGE`` object that will be used to render the result of the Ajax call.
+
+         .. attention::
+
+           Currently this setting is only used in the Fluid ``f:form`` Viewhelper. If you have to change it, you'll have to set the new typeNum in the ``PAGE`` object separately. This may be fixed in future versions.
+   Default
+         :typoscript:`{$plugin.tx_ajaxselectlist_selectlist.settings.typeNum}`
+
+
+PAGE object
+^^^^^^^^^^^
+
+This is used to render the return of the Ajax call. As TYPO3 would generate header code for every ``PAGE`` object and we only need the record's content, we strip it from all unnecessary code and deactivate the caching.
+
+.. attention::
+   For now, the typeNum isn't loaded with the same TypoScript constant which fills the setting above, because it would result in an error. This may be fixed in future versions.
+
+   Anyway, it is very unlikely that you need to change the typeNum to prevent a conflict with another ``PAGE`` object.
+
+.. code-block:: typoscript
+
+	ajaxselectlist_page = PAGE
+	ajaxselectlist_page {
+	    typeNum = 427590
+
+	    config {
+	        disableAllHeaderCode = 1
+	        additionalHeaders = Content-type:application/html
+	        xhtml_cleaning = 0
+	        debug = 0
+	        no_cache = 1
+	        admPanel = 0
+	    }
+
+	    10 < tt_content.list.20.ajaxselectlist_selectlist
+	}