====== The Registry (WbAdaptor) ======
Programming without **global** constants and variables.

In the medium term it is planned to build up a 'Registry' in WebsiteBaker. Until this is ready, the class '**WbAdaptor**' will take over this task. First of all, the class provides properties that are more or less identical with the previous constants. At the same time, also the old constants are -still- available unchanged for old code, however they may **no longer** be used for new or revised Code!
===== Overview =====
Global constants show a fundamental characteristic which very much supports 'lazy' programming: Once declared, they are directly available at absolutely any location of the source code requiring no additional expense. Visibility and scope don't play any role for them. Absolutely 'lazy' programmers abuse constants as variables that, eventually set in sequence, and then are available at no extra transfer in the following functions. The apparent advantages, however, also face significant disadvantages. Security-critical data are **never** stored in constants. The best negative example in previous WB versions are the credentials for access to the database, which were available in each droplet, each piece of dynamic code of a template etc., absolutely freely accessible for everyone.

Global constants (as well as global variables), used within classes, break up their clear encapsulation and can prevent the reusability of the code. See 'Basics of object-oriented programming'.

Global constants are, as has long been stated, from this version on deprecated, that is undesirable. See: [[dev:284:deprecated|Deprecated-List Entry 10 from 12.2013]].

Of course, discarding all previous constants without any replacement is clearly not a feasible approach. That's simply impossible. At least in the first step, the class '**WbAdaptor**' makes properties available that are similar to the previous constants.

A significant change has arisen about the spelling of the identifier:\\
The identifiers have been written entirely in capital letters and separated several individual words with an underscore **_**, the new identifiers however still consist of the same sub strings, but now they are  written in '**//StudlyCaps//**' notation without delimiters between words.

__Example:__ **DEFAULT_TEMPLATE** becomes **DefaultTemplate** now

The transformation of the identifier is performed automatically when reading in the class WbAdaptor.

So far so good. To make it not too simple, for about a dozen former constants the identifier (key) and also partially the content has completely changed!!

===== Changed identifiers =====

List of new identifiers and examples of the current contents.\\
FIXME (note: this list is not complete!)

^old constant   ^new key    ^content (example)  ^
|NEW               |getDatabase()   |the current object for accessing the database  |
|NEW               |getTranslate()  |the current translation object                 |
|NEW               |getApplication() |the current application/core object ($wb or $admin) | 
|NEW               |getRequester()  |the current requester Objekt                  |
|NEW               |PageId          |the ID of the current page                     |
|NEW               |BlockId         |the ID of the current block                    |
|NEW               |SectionId       |the ID of the current section                  |
|WB_URL            |AppUrl          |http: ⁄⁄ example.com/wb/                                                     |
|WB_REL            |AppRel          |/wb/  (absolute path from DOCUMENT_ROOT, for use as a relative URL)                                                                      |
|WB_PATH           |AppPath         |/var/www/httpdocs/wb/ \\ alternatively, in Windows  ('c:/var/www/httpdocs/wb/')  |
|ADMIN_URL         |AcpUrl          |http: ⁄⁄ example.com/wb/admin/                                               |
|ADMIN_REL         |AcpRel          |/wb/admin/                                                                   |
|ADMIN_PATH        |AcpPath         |/var/www/httpdocs/wb/admin/                                                  |
|TMP_PATH          |TempPath        |/var/www/httpdocs/wb/temp/                                                   |
|TEMPLATE          |Template        |MyTemplate             |
|TEMPLATE_DIR      |TemplateDir     |templates/MyTemplate/  |
|NEW               |TemplateUrl     |http: ⁄⁄ example.com/wb/templates/MyTemplate/  |
|NEW               |TemplateRel     |/wb/templates/MyTemplate/  |
|NEW               |TemplatePath    |/var/www/httpdocs/wb/templates/MyTemplate/  |
|ADMIN_DIRECTORY   |AcpDir          |admin/                                                                       |
|PAGES_DIRECTORY   |PagesDir        |pages/                                                                       |
|MEDIA_DIRECTORY   |MediaDir        |media/                                                                       |
|WB_VERSION        |AppVersion      |2.8.4                                                                        |
|WB_REVISION       |AppRevision     |2060                                                                         |
|WB_SP             |AppServicePack  |SP1                                                                          |
|NEW               |AppName         |WebsiteBaker                                                                 |
|STRING_DIR_MODE   |DirModeString   | %%rwxrwxr-x%%   (textual representation, corresponds to 0775 octal)                                                           |
|OCTAL_DIR_MODE    |DirModeOctal    | %%509%% (stored integer, corresponds to 0775 written in octal)  |
|STRING_FILE_MODE  |FileModeString  | %%rw-rw-r--%%   (textual representation, corresponds to 0664 octal)                                                           |
|OCTAL_FILE_MODE   |FileModeOctal   | %%436%% (stored integer, corresponds to 0664 written in octal)  |

Who looks attentively at the list, will recognize a few new laws:

The string **WB**_ became **App** (has nothing to do with any of these App Stores !!), it's just the original abbreviation for application =>  program.\\
The string **ADMIN_** became **Acp** which is the abbreviation for **A**dmin **C**ontrol **P**anel, because the functions and names 'backend' and 'admin tools' will be abolished or replaced in one of the subsequent versions.\\

Regardless of the changed prefixes, the following rules apply for extensions:
   * xxx**Url** basically includes a full URL with protocol specification
   * xxx**Path** includes a full path starting from the root directory of the physical file system and **always** begins with a slash ** / ** and **c:/** for Windows.
   * xxx**Rel** includes an absolute path, starting from DOCUMENT_ROOT and **always** begins with a slash ** / **
   * xxx**Dir** contains one or more successive directory names, and **must not** start with a slash ** / **.

__for all statements in common the following rules apply:__
  * As PATH_SEPERATOR only the slash** / ** is allowed. Adjustments can be made easily with\\ <code> $sPath = str_replace('\\', '/', $sPath); </code>
  * If the last element of a URL, Rel, Path-, or Dir-specified directory, the indication must terminate on a slash** / **.\\
  * To ensure that a directory path is terminated with a single slash** / **the short sequence is sufficient\\ <code> $sPath = rtrim($sPath, '/').'/'; </code>
  *  Leading slashes** / **are removed by\\ <code>  $sPath = ltrim($sPath, '/');  </code>

OLD => NEW example:
|     ^ key        ^ value                     ^
^old  | WB_URL           | http: ⁄⁄ example.com/wb  |
^new  | AppUrl           | http: ⁄⁄ example.com/wb/ |
^old  | ADMIN_REL        | /wb/admin                |
^new  | AcpRel           | /wb/admin/               | 
^old  | PAGES_DIRECTORY  | /pages                   |
^new  | PagesDir         | pages/                   |
^old  | TEMPLATE_DIR     | http: ⁄⁄ example.com/wb/templates/MyTemplate  |
^new  | TemplateDir      | templates/MyTemplate/    |

===== Application of WbAdaptor =====
This class can be reached from anywhere. It is sufficient to import that only existing active instance of the class with\\ <code> $oReg = \bin\WbAdaptor::getInstance(); </code> to import into the current scope. 
But even better is the use of dependency injection, i.e. the transfer of the instance from outside to the function or class.

:!: It is strongly recommended that the identifier //**$oReg**// is used for the instance of the WbAdaptor object in order to achieve a better and consistent readability of all program components.

Also the request of the individual values quite straightforward:\\
<code> echo $oReg->TemplateDir.'images/logo.png'; </code> \\
Output:  ''templates/myTemplate/images/logo.png''

What is not visible from the outside, the fact is that all retrievable values are stored in two basic groups:
  * //System// -> these are all values that are **always** the same at constant, for basic settings constant for each script call.
  * //Request// -> all other values, which can, depending on the page, users who request mode or other criteria have different values.
The system values are protected and can **not** be overridden by //Request// values or anything else.