[TASK] Move documentation to reST 24/42824/2
authorFrancois Suter <francois@typo3.org>
Fri, 21 Aug 2015 20:36:22 +0000 (22:36 +0200)
committerFrancois Suter <francois@typo3.org>
Fri, 21 Aug 2015 20:38:07 +0000 (22:38 +0200)
Releases: 2.0
Resolves: #69245
Change-Id: Iaa223e5497706b982e84b40228cd128df0eb01c0
Reviewed-on: http://review.typo3.org/42824
Reviewed-by: Francois Suter <francois@typo3.org>
Tested-by: Francois Suter <francois@typo3.org>
15 files changed:
ChangeLog
Documentation/.gitignore [new file with mode: 0644]
Documentation/Developer/Api/Index.rst [new file with mode: 0644]
Documentation/Developer/Index.rst [new file with mode: 0644]
Documentation/Developer/Introduction/Index.rst [new file with mode: 0644]
Documentation/Developer/OverlayRecords/Index.rst [new file with mode: 0644]
Documentation/Includes.txt [new file with mode: 0644]
Documentation/Index.rst [new file with mode: 0644]
Documentation/Installation/Index.rst [new file with mode: 0644]
Documentation/Introduction/Index.rst [new file with mode: 0644]
Documentation/KnownProblems/Index.rst [new file with mode: 0644]
Documentation/Limitations/Index.rst [new file with mode: 0644]
Documentation/Settings.yml [new file with mode: 0644]
doc/manual.pdf [deleted file]
doc/manual.sxw [deleted file]

index f6f3d3b..f8f5b83 100644 (file)
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,6 +1,7 @@
 2015-08-21 Francois Suter (Cobweb)  <typo3@cobweb.ch>
 
        * Moved to namespaces, verified compatibility with TYPO3 CMS 7, resolves #69244
+       * Moved documentation to reStructuredText, resolves #69245
 
 2014-05-09 Francois Suter (Cobweb)  <typo3@cobweb.ch>
 
diff --git a/Documentation/.gitignore b/Documentation/.gitignore
new file mode 100644 (file)
index 0000000..704981a
--- /dev/null
@@ -0,0 +1 @@
+_make
diff --git a/Documentation/Developer/Api/Index.rst b/Documentation/Developer/Api/Index.rst
new file mode 100644 (file)
index 0000000..d76c965
--- /dev/null
@@ -0,0 +1,424 @@
+.. ==================================================
+.. FOR YOUR INFORMATION
+.. --------------------------------------------------
+.. -*- coding: utf-8 -*- with BOM.
+
+.. include:: ../../Includes.txt
+
+
+.. _developers-api:
+
+The full API
+------------
+
+On top of the method demonstrated above, class :code:`\Cobweb\Overlays\OverlayEngine` provides a full toolbox related to
+getting overlaid records in the TYPO3 CMS frontend. This API is described below.
+
+:code:`\Cobweb\Overlays\OverlayEngine` is a fully static class. As such it cannot be XCLASSed.
+
+
+.. _developers-api-getallrecordsfortable:
+
+getAllRecordsForTable
+~~~~~~~~~~~~~~~~~~~~~
+
+This method returns an array with all records properly
+overlaid with their translations and filtered according
+to the table's enable fields.
+
+.. note::
+
+   This will not work properly using implicit joins
+   (i.e. :code:`SELECT * FROM foo, bar ...`) as neither enable
+   fields, nor translations, nor versions will be cleanly
+   applied to both tables.
+
+This method takes the following parameters:
+
+$selectFields (string)
+  Comma-separated list of fields to select from the table.
+
+$fromTable (string)
+  Table from which to select.
+
+$whereClause (string)
+  Additional WHERE clause for the query. Enable fields are handled automatically.
+  Optional, defaults to empty string.
+
+$groupBy (string)
+  GROUP BY field(s).
+  Optional, defaults to empty string.
+
+$orderBy (string)
+  ORDER BY field(s).
+  Optional, defaults to empty string.
+
+$limit (string)
+  LIMIT value ([begin,]max).
+  Optional, defaults to empty string.
+
+$indexField (string)
+  Optional, name of a field to use as an index for the result array.
+  **Must be included in the list of select fields.**
+
+
+.. _developers-api-getsinglerecordfortable:
+
+getSingleRecordForTable
+~~~~~~~~~~~~~~~~~~~~~~~
+
+Similar to getAllRecordsForTable(), but returns a
+single record by automatically applying a limit of 1 to
+the underlying SQL query.
+
+This method takes the following parameters:
+
+$selectFields (string)
+  Comma-separated list of fields to select from the table.
+
+$fromTable (string)
+  Table from which to select.
+
+$whereClause (string)
+  Additional WHERE clause for the query. Enable fields are handled automatically.
+  Optional, defaults to empty string.
+
+$groupBy (string)
+  GROUP BY field(s).
+  Optional, defaults to empty string.
+
+$orderBy (string)
+  ORDER BY field(s).
+  Optional, defaults to empty string.
+
+
+.. _developers-api-getenabledfieldscondition:
+
+getEnabledFieldsCondition
+~~~~~~~~~~~~~~~~~~~~~~~~~
+
+This method returns the complete SQL condition needed
+to respect all enable fields as defined in the TCA of
+the table. Essentially this method is a wrapper around
+:code:`\TYPO3\CMS\Frontend\Page\PageRepository::enableFields()`.
+The only difference is that it removes the " AND " at the beginning of the
+condition, so that it's not necessary to prepare for
+such condition by adding things like "1=1" to your
+SQL statements.
+
+For more details look at what happens inside
+:code:`\TYPO3\CMS\Frontend\Page\PageRepository::enableFields()`.
+
+This method takes the following parameters:
+
+$table (string)
+  Name of the table to build the condition for.
+
+$showHidden (boolean)
+  Set to TRUE to force the display of hidden records.
+
+$ignoreArray (array)
+  Defines which enable fields to ignore. Use keys like "disabled", "starttime",
+  "endtime", "fe_group" (i.e. keys from "enablecolumns" in TCA) and set values
+  to TRUE to exclude corresponding conditions from WHERE clause.
+
+
+.. _developers-api-getlanguagecondition:
+
+getLanguageCondition
+~~~~~~~~~~~~~~~~~~~~
+
+This method returns the SQL condition necessary to
+select the correct records with records to their
+language, based on the table's TCA and the currently
+selected language in the FE.
+
+This method takes the following parameters:
+
+$table (string)
+  Name of the table to build the condition for.
+
+$alias (string)
+  Alias of the table to be used in the SQL condition.
+
+
+.. _developers-api-getversioningcondition:
+
+getVersioningCondition
+~~~~~~~~~~~~~~~~~~~~~~
+
+This method assembles the SQL condition necessary to
+select the correct records for the live web site or for
+the current workspace.
+
+This method takes the following parameters:
+
+$table (string)
+  Name of the table to build the condition for.
+
+$alias (string)
+  Alias of the table to be used in the SQL condition.
+
+$getOverlaysDirectly (boolean)
+  Set to TRUE to directly get the overlays, instead of the placeholders
+  to overlay (check the method's comments in the code for
+  a deeper discussion). Leave the default value of FALSE if unsure.
+
+
+.. _developers-api-getallfieldsfortable:
+
+getAllFieldsForTable
+~~~~~~~~~~~~~~~~~~~~
+
+This method returns the list of all fields for a given
+table (based on querying the database, not analyzing
+the TCA).
+
+This method takes the following parameters:
+
+$table (string)
+  Name of the table to get the fields for.
+
+
+.. _developers-api-selectbasefields:
+
+selectBaseFields
+~~~~~~~~~~~~~~~~
+
+This method makes sure that the query will include a
+number of base fields necessary for the overlay
+process. This means the uid and pid fields.
+
+This method takes the following parameters:
+
+$table (string)
+  Table from which to select.
+
+$selectFields (string)
+  List of fields to select from the table.
+
+
+.. _developers-api-selectoverlaysfields:
+
+selectOverlaysFields
+~~~~~~~~~~~~~~~~~~~~
+
+This method makes sure that the query will include all
+necessary fields for the **language** overlay process.
+It returns the original list of selected fields plus
+any other necessary fields that were missing.
+
+This method takes the following parameters:
+
+$table (string)
+  Table from which to select.
+
+$selectFields (string)
+  List of fields to select from the table.
+
+
+.. _developers-api-selectoverlaysfieldsarray:
+
+selectOverlayFieldsArray
+~~~~~~~~~~~~~~~~~~~~~~~~
+
+This method returns an array containing the list of all
+fields that should be added to the current list of
+selected fields, in order to have all the necessary
+information for the **language** overlay process.
+
+This method takes the following parameters:
+
+$table (string)
+  Table from which to select.
+
+$selectFields (string)
+  List of fields to select from the table.
+
+
+.. _developers-api-selectversioningfields:
+
+selectVersioningFields
+~~~~~~~~~~~~~~~~~~~~~~
+
+This method makes sure that the query will include all
+necessary fields for the **version** overlay process.
+It returns the original list of selected fields plus
+any other necessary fields that were missing.
+
+This method takes the following parameters:
+
+$table (string)
+  Table from which to select.
+
+$selectFields (string)
+  List of fields to select from the table.
+
+
+.. _developers-api-selectversioningfieldsarray:
+
+selectVersioningFieldsArray
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+This method returns an array containing the list of al
+fields that should be added to the current list of
+selected fields, in order to have all the necessary
+information for the **version** overlay process.
+
+This method takes the following parameters:
+
+$table (string)
+  Table from which to select.
+
+$selectFields (string)
+  List of fields to select from the table.
+
+
+.. _developers-api-overlayrecordset:
+
+overlayRecordSet
+~~~~~~~~~~~~~~~~
+
+This method performs both the translation and
+versioning overlays on the given recordset, according
+to the relevant TCA settings.
+
+.. note::
+   If overlay mode is "hideNonTranslated", the
+   overlaid recordset may contain less records than the
+   original one, if some records were missing a
+   translation.
+
+This method takes the following parameters:
+
+$table (string)
+  Table name
+
+$recordset (array)
+  Full recordset to overlay. Must contain uid, pid and
+  $TCA[$table]['ctrl']['languageField'].
+
+$currentLanguage (integer)
+  Uid of the currently selected language in the FE.
+
+$overlayMode (string)
+  Overlay mode. If "hideNonTranslated" then records without translation
+  will not be returned un-translated but removed instead.
+
+$doVersioning (boolean)
+  Set to TRUE if version overlays must be performed.
+
+
+.. _developers-api-getoverlayrecords:
+
+getOverlayRecords
+~~~~~~~~~~~~~~~~~
+
+This method is a wrapper around
+:code:`\Cobweb\Overlays\OverlayEngine::getLocalOverlayRecords()` and
+:code:`\Cobweb\Overlays\OverlayEngine::getForeignOverlayRecords()`.
+It will call the appropriate method depending on the translation
+structure (i.e. translations in same table or in
+foreign table). It returns the same result as these two
+methods.
+
+This method takes the following parameters:
+
+$table (string)
+  Name of the table for which to fetch the records.
+
+$uids (array)
+  Array of all uid's of the original records for which to fetch the translation.
+
+$currentLanguage (integer)
+  Uid of the system language to translate to.
+
+$doVersioning (boolean)
+  Set to TRUE if version overlays must be performed.
+
+
+.. _developers-api-getlocaloverlayrecords:
+
+getLocalOverlayRecords
+~~~~~~~~~~~~~~~~~~~~~~
+
+This method gets all translation overlay records for
+the chosen language and for all records indicated by
+the list of uid's. It will work for tables that contain
+their own translations.
+
+If workspace preview is active, the translation
+overlays will have been properly version-overlaid.
+
+It returns all overlay records organized by uid and pid
+so that the overlay process can take place properly
+afterwards.
+
+This method takes the following parameters:
+
+$table (string)
+  Name of the table for which to fetch the records.
+
+$uids (array)
+  Array of all uid's of the original records for which to fetch the translation.
+
+$currentLanguage (integer)
+  Uid of the system language to translate to.
+
+$doVersioning (boolean)
+  Set to TRUE if version overlays must be performed.
+
+
+.. _developers-api-getforeignoverlayrecords:
+
+getForeignOverlayRecords
+~~~~~~~~~~~~~~~~~~~~~~~~
+
+This method gets all translation overlay records for
+the chosen language and for all records indicated by
+the list of uid's. It will work for tables that use a
+foreign table to store their translations.
+
+If workspace preview is active, the translation
+overlays will have been properly version-overlaid.
+
+It returns all overlay records organized by uid and pid
+so that the overlay process can take place properly
+afterward.
+
+This method takes the following parameters:
+
+$table (string)
+  Name of the table for which to fetch the records.
+
+$uids (array)
+  Array of all uid's of the original records for which to fetch the translation.
+
+$currentLanguage (integer)
+  Uid of the system language to translate to.
+
+$doVersioning (boolean)
+  Set to TRUE if version overlays must be performed.
+
+
+.. _developers-api-overlaysinglerecord:
+
+overlaySingleRecord
+~~~~~~~~~~~~~~~~~~~
+
+This method actually performs the translation overlay
+of a single record taking into account all fine-grained
+translation settings at field level (i.e.
+"l10n_mode"). It returns the properly overlaid
+record.
+
+This method takes the following parameters:
+
+$table (string)
+  Name of the table for which the operation is taking place.
+
+$record (array)
+  Record to overlay.
+
+$overlay (array)
+  Overlay of the record.
diff --git a/Documentation/Developer/Index.rst b/Documentation/Developer/Index.rst
new file mode 100644 (file)
index 0000000..1653330
--- /dev/null
@@ -0,0 +1,20 @@
+.. ==================================================
+.. FOR YOUR INFORMATION
+.. --------------------------------------------------
+.. -*- coding: utf-8 -*- with BOM.
+
+.. include:: ../Includes.txt
+
+
+.. _developer:
+
+Developer's manual
+==================
+
+.. toctree::
+    :maxdepth: 2
+    :titlesonly:
+
+    Introduction/Index
+    OverlayRecords/Index
+    Api/Index
diff --git a/Documentation/Developer/Introduction/Index.rst b/Documentation/Developer/Introduction/Index.rst
new file mode 100644 (file)
index 0000000..d2e3780
--- /dev/null
@@ -0,0 +1,42 @@
+.. ==================================================
+.. FOR YOUR INFORMATION
+.. --------------------------------------------------
+.. -*- coding: utf-8 -*- with BOM.
+
+.. include:: ../../Includes.txt
+
+
+.. _developer-introduction:
+
+Introduction
+------------
+
+Traditionally getting a set of records from the database in a TYPO3 application (typically a FE
+plugin) is done by calling a method like :code:`\TYPO3\CMS\Core\Database\DatabaseConnection::exec_SELECTquery()`.
+Then – if your site uses multiple languages and your records are localized using standard TYPO3 mechanisms – you have to
+overlay each record with its translation by calling t3lib_page::getRecordOverlay(). It is also up to
+you to check whether the translation succeeded or not. Here is how you code may look like, taking
+"tt_news" as an example and doing a simple rendering with a bullet list:
+
+.. code-block:: php
+
+    // Restrict records to default language
+    $languageCondition = $GLOBALS['TCA']['tt_news']['ctrl']['languageField'] . ' IN (0, -1)';
+    // Also take records that exist only in chosen language
+    if ($GLOBALS['TSFE']->sys_language_content > 0) {
+        $languageCondition .= ' OR (tt_news.' . $GLOBALS['TCA']['tt_news']['ctrl']['languageField'] . " = '" . $GLOBALS['TSFE']->sys_language_content . "' AND tt_news." . $GLOBALS['TCA']['tt_news']['ctrl']['transOrigPointerField'] . " = '0')";
+    }
+    // Add enable fields check
+    $where = '(' . $languageCondition . ') ' . $GLOBALS['TSFE']->sys_page->enableFields('tt_news');
+    $news = $GLOBALS['TYPO3_DB']->exec_SELECTgetRows('uid, pid, title', 'tt_news', $where);
+
+    $content = '<ul>';
+    foreach ($news as $item) {
+        // Perform overlay on each record
+        $overlay = $GLOBALS['TSFE']->sys_page->getRecordOverlay('tt_news', $item, $GLOBALS['TSFE']->sys_language_content, $GLOBALS['TSFE']->sys_language_contentOL);
+        // Check if record was not unset (in translation strict mode)
+        if (isset($overlay)) {
+            $content .= '<li>' . $overlay['title'] . '</li>';
+        }
+    }
+    $content .= '</ul>';
diff --git a/Documentation/Developer/OverlayRecords/Index.rst b/Documentation/Developer/OverlayRecords/Index.rst
new file mode 100644 (file)
index 0000000..72e2e5c
--- /dev/null
@@ -0,0 +1,35 @@
+.. ==================================================
+.. FOR YOUR INFORMATION
+.. --------------------------------------------------
+.. -*- coding: utf-8 -*- with BOM.
+
+.. include:: ../../Includes.txt
+
+
+.. _developer-overlay-records:
+
+Getting overlaid records in a single call
+-----------------------------------------
+
+Using the "overlays" library the code in the previous chapter is reduced to the following:
+
+.. code-block:: php
+
+    $news = \Cobweb\Overlays\OverlayEngine::getAllRecordsForTable('title', 'tt_news');
+    $content .= '<ul>';
+    foreach ($news as $item) {
+        $content .= '<li>' . $item['title'] . '</li>';
+    }
+    $content .= '</ul>';
+
+
+The :code:`\Cobweb\Overlays\OverlayEngine::getAllRecordsForTable()`
+method takes the same arguments as
+:code:`\TYPO3\CMS\Core\Database\DatabaseConnection::exec_SELECTquery()`,
+but takes care of all the enable fields and all the translation
+process.
+
+On top of this the "overlays" library is so structured that all translation overlays are gotten
+in a single database request. The normal TYPO3 CMS process generates one query per record to overlay.
+Thus "overlays" plays much nicer to your database. This comes at the price of some additional
+PHP processing.
diff --git a/Documentation/Includes.txt b/Documentation/Includes.txt
new file mode 100644 (file)
index 0000000..8ef89a7
--- /dev/null
@@ -0,0 +1,21 @@
+.. ==================================================
+.. FOR YOUR INFORMATION
+.. --------------------------------------------------
+.. -*- coding: utf-8 -*- with BOM.
+
+.. This is 'Includes.txt'. It is included at the very top of each and
+   every ReST source file in this documentation project (= manual).
+
+
+.. ==================================================
+.. DEFINE SOME TEXT ROLES
+.. --------------------------------------------------
+
+.. role::   typoscript(code)
+
+.. role::   ts(typoscript)
+   :class:  typoscript
+
+.. role::   php(code)
+
+.. highlight:: php
diff --git a/Documentation/Index.rst b/Documentation/Index.rst
new file mode 100644 (file)
index 0000000..c3bf7e6
--- /dev/null
@@ -0,0 +1,60 @@
+.. ==================================================
+.. FOR YOUR INFORMATION
+.. --------------------------------------------------
+.. -*- coding: utf-8 -*- with BOM.
+
+.. include:: Includes.txt
+
+
+.. _start:
+
+=================
+Improved overlays
+=================
+
+.. only:: html
+
+    :Language:
+        en
+
+    :Version:
+        |release|
+
+    :Description:
+        This extension provides an easy to use API for retrieving properly localized records. It
+        also takes care of keeping the DB calls to a minimum.
+
+    :Keywords:
+        overlays, language, versioning, api
+
+    :Copyright:
+        2008-2014
+
+    :Author:
+        François Suter
+
+    :Email:
+        typo3@cobweb.ch
+
+    :License:
+        This document is published under the Open Publication License
+        available from http://www.opencontent.org/openpub/
+
+    :Rendered:
+        |today|
+
+    The content of this document is related to TYPO3,
+    a GNU/GPL CMS/Framework available from `www.typo3.org <https://typo3.org/>`__.
+
+
+    **Table of Contents**
+
+.. toctree::
+    :maxdepth: 3
+    :titlesonly:
+
+    Introduction/Index
+    Installation/Index
+    Limitations/Index
+    Developer/Index
+    KnownProblems/Index
diff --git a/Documentation/Installation/Index.rst b/Documentation/Installation/Index.rst
new file mode 100644 (file)
index 0000000..17335a9
--- /dev/null
@@ -0,0 +1,32 @@
+.. ==================================================
+.. FOR YOUR INFORMATION
+.. --------------------------------------------------
+.. -*- coding: utf-8 -*- with BOM.
+
+.. include:: ../Includes.txt
+
+
+.. _installation:
+
+Installation
+============
+
+All you need is to install the extension and you can start using it in your own developments right
+away.
+
+
+.. _installation-compatibility:
+
+Compatibility
+-------------
+
+As of version 3.0.0, TYPO3 CMS 6.2 or more is required.
+
+
+.. _installation-upgrading-to-version-300:
+
+Upgrading to version 3.0.0
+--------------------------
+
+Method :code:`getWorkspaceCondition()` was deprecated in version 2.0.0 and removed
+in version 3.0.0. Use :code:`getVersioningCondition()` instead.
diff --git a/Documentation/Introduction/Index.rst b/Documentation/Introduction/Index.rst
new file mode 100644 (file)
index 0000000..6b7fe47
--- /dev/null
@@ -0,0 +1,58 @@
+.. ==================================================
+.. FOR YOUR INFORMATION
+.. --------------------------------------------------
+.. -*- coding: utf-8 -*- with BOM.
+
+.. include:: ../Includes.txt
+
+
+.. _introduction:
+
+Introduction
+============
+
+
+This extension makes it easier to get a set of records from the TYPO3 database, properly overlaid
+for sites with multiple languages. Furthermore it provides in a central place a set of tools related
+to database calls that are sometimes spread over several classes in the TYPO3 architecture. Versions
+and workspaces are also supported, as well as language overlays in foreign tables.
+
+It also aims to reduce the number of database calls, at least for language overlays. In a scenario
+where many records are fetched and overlaid the number of requests to the database will be much
+smaller, albeit at the cost of increased PHP processing (there's no free lunch). For version
+overlays, extension "overlays" still relies on the TYPO3 Core method
+:code:`\TYPO3\CMS\Frontend\Page\PageRepository::versionOL()`.
+
+There are limitations to what can be achieved with a simple library. Please read the
+:ref:`Limitations <limitations>` chapter carefully.
+
+
+.. _introduction-questions:
+
+Questions and support
+---------------------
+
+If you have any questions about this extension, please ask them in the TYPO3 English mailing list,
+so that others can benefit from the answers. Please use the bug tracker on forge.typo3.org to report
+problem or suggest features (http://forge.typo3.org/projects/extension-overlays/issues).
+
+
+.. _introduction-credits:
+
+Credits
+-------
+
+Most of the overlay code itself comes from the TYPO3 CMS core and was not developed by myself. It is
+encapsulated in various methods for easier use.
+
+
+.. _introduction-happy-developer:
+
+Keeping the developer happy
+---------------------------
+
+Every encouragement keeps the developer ticking, so don't hesitate to send thanks or share your
+enthusiasm about the extension.
+
+If you appreciate this work and want to show some support, please check
+http://www.monpetitcoin.com/en/francois/support-me/.
diff --git a/Documentation/KnownProblems/Index.rst b/Documentation/KnownProblems/Index.rst
new file mode 100644 (file)
index 0000000..7d3fd32
--- /dev/null
@@ -0,0 +1,15 @@
+.. ==================================================
+.. FOR YOUR INFORMATION
+.. --------------------------------------------------
+.. -*- coding: utf-8 -*- with BOM.
+
+.. include:: ../Includes.txt
+
+
+.. _known-problems:
+
+Known problems
+==============
+
+None to date. Please report any bugs to
+https://forge.typo3.org/projects/extension-overlays/issues.
diff --git a/Documentation/Limitations/Index.rst b/Documentation/Limitations/Index.rst
new file mode 100644 (file)
index 0000000..944bfc7
--- /dev/null
@@ -0,0 +1,86 @@
+.. ==================================================
+.. FOR YOUR INFORMATION
+.. --------------------------------------------------
+.. -*- coding: utf-8 -*- with BOM.
+
+.. include:: ../Includes.txt
+
+
+.. _limitations:
+
+Limitations
+===========
+
+TYPO3's overlay architecture makes it very difficult to provide a full-fledged API for some
+operations without building a complete SQL parser on top (which is essentially what the "dataquery"
+extension of the Tesseract project does).
+
+
+.. _limitations-table-joins:
+
+Table joins
+-----------
+
+In :code:`\TYPO3\CMS\Core\Database\DatabaseConnection::exec_SELECTquery()`
+it is perfectly okay to make joins by setting several table names in
+the :code:`$from_table` parameter. Example:
+
+.. code-block:: sql
+
+    $result = \TYPO3\CMS\Core\Database\DatabaseConnection::exec_SELECTquery('*', 'pages, tt_content', 'tt_content.pid = pages.uid');
+
+
+This will not work correctly for overlays. Indeed tables must be overlaid individually. So in order
+to have joined tables overlaid, it would be necessary to separate the result of the query into two
+tables again, overlay each part and join them again.
+
+The suggestion that can be made here is to select records from both tables separately using
+tx_overlays::getAllRecordsForTable() and perform the join in your PHP code.
+
+
+.. _limitations-text-search:
+
+Text search
+-----------
+
+Imagine trying to select records based on a LIKE condition place on a text field. Imagine the
+following records:
+
+=====  ===========  ================  ===========================  =====  =====
+uid    l18n_parent  sys_language_uid  title                        ...
+-----  -----------  ----------------  ---------------------------  -----  -----
+1      0            0                 Weather forecast for Geneva  ...
+-----  -----------  ----------------  ---------------------------  -----  -----
+2      1            3                 Wetterbericht für Genf       ...
+=====  ===========  ================  ===========================  =====  =====
+
+Now let's say we want to make a text-based search on the title. We might write something like:
+
+.. code-block:: php
+
+    $records = \Cobweb\Overlays\OverlayEngine::getAllRecordsForTable('uid, title', 'tt_news', "title LIKE '%" . $searchWord . "%'");
+
+
+($searchWords would have been properly escaped first, of course). Since extension "overlays" aims to
+follow the TYPO3-way of doing overlays it will automatically select only records in the default
+language and overlay them afterwards. This means that the above query will work fine if you search
+for "geneva", but will not work if you search for "genf", because that word does not appear in the
+default language. The result of the query is thus wrong: there is a record that would match the
+condition, but it won't be found because it's not in the default language.
+
+On the other hand if you tried to select directly in the right language (using
+:code:`\TYPO3\CMS\Core\Database\DatabaseConnection::exec_SELECTquery()`), you will miss some information because
+some fields in "tt_news" are not editable in the translations.
+
+There's no simple solution to this conundrum. One might be to select records in the requested
+language first, use these records' "parent_id" information to get the records in the default
+language, and then overlay the latter with the former. This is obviously a lot of overhead. Not to
+mention what a nightmare it becomes if you add the dimension of version overlays.
+
+A better solution is probably to avoid such text-based searches at all and use search engines in
+that case (Apache Solr, Google, etc.), although that will probably not work for workspace preview,
+except if you can manage to index workspace versions. Then again it's probably unnecessary to be
+able to correctly search in workspaces in most cases.
+
+All that is described above is not an issue if you test numeric fields, such as simple flags, dates,
+etc.
diff --git a/Documentation/Settings.yml b/Documentation/Settings.yml
new file mode 100644 (file)
index 0000000..a99f978
--- /dev/null
@@ -0,0 +1,11 @@
+# This is the project specific Settings.yml file.
+# Place Sphinx specific build information here.
+# Settings given here will replace the settings of 'conf.py'.
+
+---
+conf.py:
+  copyright: 2008-2015
+  project: Improved overlays
+  version: 3.0
+  release: 3.0.0-dev
+...
\ No newline at end of file
diff --git a/doc/manual.pdf b/doc/manual.pdf
deleted file mode 100644 (file)
index 6e2faba..0000000
Binary files a/doc/manual.pdf and /dev/null differ
diff --git a/doc/manual.sxw b/doc/manual.sxw
deleted file mode 100755 (executable)
index 3859d9c..0000000
Binary files a/doc/manual.sxw and /dev/null differ