--- manual-doc_core_api-29-09-2005_15-27-41.txt 2006-07-26 17:23:30.000000000 +0200 +++ manual-doc_core_api_4-0-0.txt 2006-07-26 18:30:25.000000000 +0200 @@ -7,7 +7,7 @@ TYPO3 Core APIs Extension Key: doc_core_api -Copyright 2000-2005, Kasper Skårhøj, +Copyright 2000-2006, Kasper Skårhøj, This document is published under the Open Content License available from http://www.opencontent.org/opl.shtml @@ -16,7 +16,7 @@ - a GNU/GPL CMS/Framework available from www.typo3.com -Revised for TYPO3 3.9 +Revised for TYPO3 4.0 Table of Contents Table of Contents @@ -254,9 +258,7 @@ This is a per-server way to install an extension; they are global for the TYPO3 source code on the web server. These extensions will be available for any TYPO3 installation sharing the source code. Notice on distribution: -TYPO3 is distributed with a fixed set of global extensions which are distributed for reasons like popularity and sometimes history. You might want to just leave the global extensions as-is in the distribution of TYPO3 and never change them. -Another option (when you upgrade TYPO3 source) is to copy the typo3/ext/ directory from the former source to the new source, overriding the default directory, after which you can always enter TYPO3 and upgrade the versions if needed. Unfortunately you can experience that global extensions in the TYPO3 distributions are newer than those online in TER - they were simply not updated in TER prior to the packaging of the source. -The general recommendation is to leave the global extensions as a part of the core of TYPO3 and use local extensions only for custom environments. +As of version 4.0, TYPO3 is no longer distributed with a fixed set of global extensions. In previous versions these were distributed for reasons like popularity and sometimes history. System typo3/sysext/ This is system default extensions which cannot and should not be updated by the EM. They are distributed with TYPO3 core source code and generally understood to be a part of the core system. @@ -1455,6 +1457,141 @@ For usage in "ext_locallang.php" files t3lib_extMgm::addPItoST43($_EXTKEY); +Programming with workspaces in mind +The concept of workspaces needs attension from extension programmers. The implementation of workspaces is however made so that no critical problems can appear with old extensions; +First of all the Live workspace is no different from how TYPO3 has been working for years so that will be supported out of the box (except placeholder records must be filtered out in the frontend with t3ver_state!= , see below). +Secondly, all permission related issues are implemented in TCEmain so the worst your users can experience is an error message. +However, you probably want to update your extension so that in the backend the current workspace is reflected in the records shown and the preview of content in the frontend works as well. Therefore this chapter has been written with instructions and insight into the issues you are facing. +Frontend challenges in general +For the frontend the challenges are mostly related to creating correct previews of content in workspaces. For most extensions this will work transparently as long as they use the API functions in TYPO3 to request records from the system. +The most basic form of a preview is when a live record is selected and you lookup a future version of that record belonging to the current workspace of the logged in backend user. This is very easy as long as a record is selected based on its uid or pid fields which are not subject to versioning; You simply call sys_page->versionOL() after record selection. +However, when other fields are involved in the where clause it gets dirty. This happens all the time! For instance, all records displayed in the frontend must be selected with respect to enableFields configuration! What if the future version is hidden and the live version is not? Since the live version is selected first (not hidden) and then overlaid with the content of the future version (hidden) the effect of the hidden field we wanted to preview is lost unless we also check the overlaid record for its hidden field (->versionOL() actually does this). But what about the opposite; if the live record was hidden and the future version not? Since the live version is never selected the future version will never have a chance to display itself! So we must first select the live records with no regard to the hidden state, then overlay the future version and eventually check if it is hidden and if so exclude it. The same problem applies to all other enableFields, future versions with delete flags and current versions which are invisible placeholders for future records. Anyway, all that is handled by TYPO3s t3lib_page class which includes functions for enableFields and deleted so it will work out of the box for you. But as soon as you do selection based on other fields like email, username, alias etc. it will fail. +Summary: +Challenge: How to preview elements which are disabled by enableFields in the live version but not necessarily in the offline version. Also, how to filter out new live records with t3ver_state set to 1 (placeholder for new elements) but only when not previewed. +Solution: Disable check for enableFields/where_del_hidden on live records and check for them in versionOL on input record. +Frontend implementation guidelines +Any place where enableFields() are not used for selecting in the frontend you must at least check that t3ver_state!=1 so placeholders for new records are not displayed. +Make sure never to select any record with pid = -1! (related to versioning). +If you need to detect preview mode for versioning and workspaces you can read these variables: +$GLOBALS[?TSFE?]->sys_page->versioningPreview: If true, you are allowed to display previews of other record versions. +$GLOBALS[?TSFE?]->sys_page->versioningWorkspaceId: Will tell you the id of the workspace of the current backend user. Used for preview of workspaces. +Use these API functions for support of version previews in the backend: + +Function +Description +$GLOBALS[?TSFE?]->sys_page->versionOL($table,&$row) +Versioning Preview Overlay. +Generally ALWAYS used when records are selected based on uid or pid. If records are selected on other fields than uid or pid (eg. "email = ....") then usage might produce undesired results and that should be evaluated on individual basis. + +Principle; Record online! => Find offline? + +Example: +This is how simple it is to use this record in your frontend plugins when you do queries directly (not using API functions already using them): + +$res = $GLOBALS[?TYPO3_DB?]->exec_SELECTquery(...); +while ($row = $GLOBALS[?TYPO3_DB?]->sql_fetch_assoc($res)) { +$GLOBALS[?TSFE?]->sys_page->versionOL($table,$row); + +if (is_array($row)) { +... + +When the live record is selected, call ->versionOL() and make sure to check if the input row (passed by reference) is still an array. +$GLOBALS[?TSFE?]->sys_page->fixVersioningPid() +Finding online PID for offline version record. +Will look if the "pid" value of the input record is -1 (it is an offline version) and if the table supports versioning; if so, it will translate the -1 PID into the PID of the original record +Used whenever you are tracking something back, like making the root line. In fact, it is currently only used by the root line function and chances are that you will not need this function often. + +Principle; Record offline! => Find online? + +Frontend scenarios impossible to preview +These issues are not planned to be supported for preview: +Lookups and searching for records based on other fields than uid,pid,enableFields will never reflect workspace content since overlays happen to online records after they are selected. +This problem can largely be avoided for versions of new records because versions of a "New"-placeholder can mirrow certain fields down onto the placeholder record. For the "tt_content" table this is configured as ?shadowColumnsForNewPlaceholders? => ?sys_language_uid,l18n_parent,colPos,header?, so that these fields used for column position, language and header title are also updated in the placeholder thus creating a correct preview in the frontend. +For versions of existing records the problem is in reality reduced a lot because normally you don?t change the column or language fields after the record is first created anyways! But in theory the preview can fail. +When changing the type of a page (eg. from "Standard" to "External URL") the preview might fail in cases where a look up is done on the "doktype" field of the live record. +Page shortcuts might not work properly in preview. +Mount Points might not work propertly in preview. +It is impossible to preview the value of count(*) selections since we would have to traverse all records and pass them through ->versionOL() before we would have a reliable result! +In tslib_fe::getPageShortcut() sys_page->getMenu() is called with an additional WHERE clause which will not respect if those fields are changed for a future version. This could be the case other places where getmenu() is used (but a search shows it is not a big problem). In this case we will for now accept that a wrong shortcut destination can be experienced during previews. + + +Backend challenges +The main challenge in the backend is to reflect how the system will look when the workspace gets published. To create a transparent experience for backend users we have to overlay almost every selected record with any possible new version it might have. Also when we are tracking records back to the page tree root point we will have to correct pid-values. All issues related to selecting on fields other than pid and uid also relates to the backend as they did for the frontend. +Workspace related API functions for backend modules + +Function +Description +t3lib_BEfunc::workspaceOL() +Overlaying record with workspace version if any. Works like ->sys_page->versionOL() does, but for the backend. Input record must have fields only from the table (no pseudo fields) and the record is passed by reference. + +Example: +$result = $GLOBALS[?TYPO3_DB?]->exec_SELECTquery(?*?, ?pages?, ?uid=?.intval($id).$delClause); +$row = $GLOBALS[?TYPO3_DB?]->sql_fetch_assoc($result); +t3lib_BEfunc::workspaceOL(?pages?, $row); +t3lib_BEfunc::getRecordWSOL() +Gets record from table and overlays the record with workspace version if any. + +Example: +$row = t3lib_BEfunc::getRecordWSOL($table,$uid); + + +// This is the same as: +$row = t3lib_BEfunc::getRecord($table,$uid); +t3lib_BEfunc::workspaceOL($table,$row); +t3lib_BEfunc::fixVersioningPid() +Translating versioning PID -1 to the pid of the live record. Same as sys_page->fixVersioningPid() but for the backend. +t3lib_BEfunc::isPidInVersionizedBranch() +Will fetch the rootline for the pid, then check if anywhere in the rootline there is a branch point. Returns either "branchpoint" (if branch) or "first" (if page) or false if nothing. Alternatively, it returns the value of "t3ver_stage" for the branchpoint (if any) +t3lib_BEfunc::getWorkspaceVersionOfRecord() +Returns offline workspace version of a record, if found. +t3lib_BEfunc::getLiveVersionOfRecord() +Returns live version of workspace version. +t3lib_BEfunc::versioningPlaceholderClause() +Returns a WHERE-clause which will deselect placeholder records from other workspaces. This should be implemented almost everywhere records are selected based on other fields than uid and where t3lib_BEfunc::deleteClause() is used. + +Example: + +$res = $GLOBALS[?TYPO3_DB?]->exec_SELECTquery( +?count(*)?, +$this->table, +$this->parentField.?=?.$GLOBALS[?TYPO3_DB?]->fullQuoteStr($uid, $this->table). +t3lib_BEfunc::deleteClause($this->table). +t3lib_BEfunc::versioningPlaceholderClause($this->table). +$this->clause +); +$BE_USER->workspaceCannotEditRecord() +Checking if editing of an existing record is allowed in current workspace if that is offline. +$BE_USER->workspaceCannotEditOfflineVersion() +Like $BE_USER->workspaceCannotEditRecord() but also requires version to be offline (draft) +$BE_USER->workspaceCreateNewRecord() +Checks if new records can be created in a certain page (according to workspace restrictions). +$BE_USER->workspacePublishAccess($wsid) +Returns true if user has access to publish in workspace. +$BE_USER->workspaceSwapAccess() +Returns true if user has access to swap versions. +$BE_USER->checkWorkspace() +Checks how the users access is for a specific workspace. +$BE_USER->checkWorkspaceCurrent() +Like ->checkWorkspace() but returns status for the current workspace. +$BE_USER->setWorkspace() +Setting another workspace for backend user. +$BE_USER->setWorkspacePreview() +Setting frontend preview state. + +Backend module access +You can restrict access to backend modules by using $MCONF[?workspaces?] in the conf.php files. The variable is a list of keywords defining where the module is available: +$MCONF[?workspaces?] = online,offline,custom + +You can also restrict function menu items to certain workspaces if you like. This is done by an argument sent to the function t3lib_extMgm::insertModuleFunction(). See that file for more details. +Detecting current workspace +You can always check what the current workspace of the backend user is by reading $GLOBALS[?BE_USER?]->workspace. If the workspace is a custom workspace you will find its record loaded in $GLOBALS[?BE_USER?]->workspaceRec. +The values for workspaces are as following: +workspace 0 = online (live) +workspace -1 = offline (draft) +workspace > 0 = custom (projects) +workspace -99 = none selected at all (ERROR!) +Using TCEmain with workspaces +Since admin-users are also restricted by the workspace it is not possible to save any live records when in a workspace. However for very special occasions you might need to bypass this and to do so, you can set the instance variable t3lib_tcemain::bypassWorkspaceRestrictions to TRUE. An example of this is when users are updating their user profile using the User > Setup module; that actually allows them to save to a live record (their user record) while in a draft workspace. TYPO3 Core Engine (TCE)Introduction Database The TYPO3 Core Engine is the class that handles all data writing to database tables configured in $TCA. In addition the class handles commands such as copy, move, delete. It will handle undo/history and versioning of records as well and everything will be logged to the sys_log. And it will make sure that write permissions are evaluated correctly for the user trying to write to the database. Generally, any processing specific option in the $TCA array is handled by TCE. @@ -1510,6 +1647,10 @@ "1" Value should always be "1" This action will delete the record (or mark the record "deleted" if configured in $TCA) +undelete +1 +Value should always be "1". +This action will set the deleted-flag back to 0. localize integer Pointer to a sys_language uid to localize the record into. Basically a localization of a record is making a copy of the record (possibly excluding certain fields defined with l10n_mode) but changing relevant fields to point to the right sys language / original language record. @@ -1528,12 +1669,15 @@ Keys: [action] : Keyword determining the versioning action. Options are: new : Indicates that a new version of the record should be created.Additional keys, specific for new action: -[treeLevels] : (Only pages) Integer, -1 to 4, indicating the number of levels of the page tree to versionize together with a page. -1 means only the page record gets versionized 0 means the page + content tables (defined by ctrl-flag versioning_followPages)>0 means the the whole branch is versionized (full copy of all tables), down to the level indicated by the value (1= 1 level down, 2= 2 levels down, etc.)The treeLevel is recorded in the field t3ver_swapmode and will be observed when the record is swapped during publishing. +[treeLevels] : (Only pages) Integer, -1 to 4, indicating the number of levels of the page tree to version together with a page. This is also referred to as the versioning type:-1 (element) means only the page record gets versioned (default) 0 (page) means the page + content tables (defined by ctrl-flag versioning_followPages)>0 (branch) means the the whole branch is versioned (full copy of all tables), down to the level indicated by the value (1= 1 level down, 2= 2 levels down, etc.)The treeLevel is recorded in the field t3ver_swapmode and will be observed when the record is swapped during publishing. [label] : Indicates the version label to apply. If not given, a standard label including version number and date is added. swap : Indicates that the current online version should be swapped with another.Additional keys, specific for swap action: [swapWith] : Indicates the uid of the record to swap current version with! [swapIntoWS]: Boolean, indicates that when a version is published it should be swapped into the workspace of the offline record. clearWSID : Indicates that the workspace of the record should be set to zero (0). This removes versions out of workspaces without publishing them. +setStage : Sets the stage of an element. Special feature: The id-key in the array can be a comma list of ids in order to perform the stageChange over a number of records. Also, the internal variable ->generalComment (also available through tce_db.php as "&generalComment") can be used to set a default comment for all stage changes of an instance of tcemain. Additional keys for this action is: +[stageId] : Values are: -1 (rejected), 0 (editing, default), 1 (review), 10 (publish) +[comment] : Comment string that goes into the log. Examples of Commands: $cmd[?tt_content?][54][?delete?] = 1;    // Deletes tt_content record with uid=54 @@ -1731,7 +1875,7 @@ Accepts options to be set in TCE object. Currently it supports "reverseOrder" (boolean). mirror array -- +Example: [mirror][table][11] = ?22,33? will look for content in [data][table][11] and copy it to [data][table][22] and [data][table][33] prErr boolean If set, errors will be printed on screen instead of redirection. Should always be used, otherwise you will see no errors if they happen. @@ -2309,7 +2453,108 @@ Get User Configuration value The internal ->uc array contains options which are managed by the User>Setup module (extensions "setup"). These values are accessible in the $BE_USER->uc array. This will return the current state of "Condensed mode" for the user: $BE_USER->uc[?condensedMode?] -PHP Class ExtensionIntroduction +Using system logThe log table (sys_log) +Writing to the system log is done using the backend user object: +$this->BE_USER->writelog($type,$action,$error,$details_nr,$details,$data,$table,$recuid,$recpid,$event_pid,$NEWid); +Here are description of the arguments to this function call: +Field +Type +Var +Description +type +tinyint +$type +Value telling which module in TYPO3 set the log entry. The type values are paired with an action-integer which is telling in more detail what the event was. Here type and action values are arranged hierarchically (type on first level, action on second level): + +1 : t3lib_TCEmain (TYPO3 Core Engine where database records are manipulated) +Action values are for new, updated, copy, move, delete etc. +2 : tce_file (File handling in fileadmin/ and absolute filemounts) +Action values are for various file handling types like upload, rename, edit etc. +3 : System (eg. sys_history save) +4 : Modules: This is the mode you may use for extensions having backend module functionality. Probably you would like to use BE_USER->simplelog() for your extensions. +254 : Personal settings changed +255 : Login or Logout action +1=login +2=logout +3=failed login (+ errorcode 3) +4=failure_warning_email sent +action +tinyint +$action +See type above + +When not available, use value 0 +error +tinyint +$error +Error level: +0 = message, a notice of an action that happened. +1 = error, typically a permission problem for the user +2 = System Error, something which should not happen for technical reasons. +3 = Security notice, like login failures +details_nr +tinyint +$details_nr +Number of detail message. This number should be unique for the combination of type/action + +-1 is a temporary detail number you can use while developing and error messages are not fixed yet. +0 is a value that means the message is not supposed to be translated +>=1 means the message is fixed and ready for translation. +details +tinytext +$details +The log message text (in english). By identification through type/action/details_nr this can be translated through the localization system. +If you insert %s markers in the details message and set $data to an array the first 5 entries (keys 0-4) from $data will substitute the markers sequentially (using sprintf) +log_data +tinyblob +$data +Data that follows the log entry. Can be an array. See details for more info. +tablename +varchar(40) +$table +Table name. Special field used by tce_main.php. +recuid +int +$recuid +Record UID. Special field used by tce_main.php. +recpid +int +$recpid +Record PID. Special field used by tce_main.php. [OBSOLETE; not used anymore.] +event_pid +int +$event_pid +The page ID (pid) where the event occurred. Used to select log-content for specific pages. +NEWid +varchar(20) +$NEWid +Special field used by tce_main.php. NEWid string of newly created records. +tstamp +int +- +EXEC_TIME of event, UNIX time in seconds. +uid +int +- +Unique ID for log entry, automatically inserted +userid +int +- +User ID of backend user, automatically set for you +IP +varchar(39) +- +REMOTE_ADDR of client +workspace +int +- +Workspace ID + +Making logging simple +While it is nice to have log message categorized and numbered during development and sometimes beyond that point a simpler logging API is necessary. Therefore you can also call this function: + +BE_USER->simplelog($message, $extKey=??, $error=0) +All you need is to set $message to store a log message. If you call it from an extension it is good practice to also supply the extension key. Finally you can add the error number (according to the table above) if you need to signal an error.PHP Class ExtensionIntroduction Practically all important scripts have their main code encapsulated in a class (typically named SC_[scriptname] and instantiated as the global object $SOBE) and almost all library classes used in TYPO3 - both frontend and backend - can be extended by user defined classes. Extension of TYPO3 PHP classes may also be referred to as an "XCLASS extension". Extending TYPO3s PHP classes is recommended mostly for special needs in individual projects. This is due to the limitation that a class can only be extended once. Thus, if many extensions try to extend the same class, only one of them will succeed and in turn the others will not function correctly. So, extending classes is a great option for individual projects where special "hacks" are needed. But generally it is a poor way of programming TYPO3 extensions in which case you should look for a system hook or request a system hook to be made for your purpose if generally meaningful. @@ -3304,25 +3549,20 @@ Display mainpalette -integer -(pointing to palette key) -Points to the palette-number that should always be shown in the bottom of the TCEform. +comma seperated list of integers (pointing to multiple palette keys) +Points to the palette-number(s) that should always be shown in the bottom of the TCEform. Example: For many records you can find the last section of the form looking something like this: This box displays the fields from the "main palette". In the case above (table: "tt_content") the main palette is "1" configured like this in $TCA for "tt_content": -?palettes? => Array ( -    ?1? => Array(?showitem? => ?hidden,starttime,endtime,fe_group?), +?palettes? => Array ( +?1? => Array(?showitem? => ?hidden,starttime,endtime,fe_group?), And in the "ctrl" section it looks like this: - script_ended = 0;? - function jumpToUrl(URL) {? - document.location = URL;? - }? -         ?mainpalette? => ?1?, +?mainpalette? => ?1?, Display canNotCollapse @@ -3479,6 +3719,16 @@         ?useColumnsForDefaultValues? => ?path,base?, Proc. +shadowColumnsForNewPlaceholders +string +(list of fieldnames) +When a new element is created in a draft workspace a placeholder element is created in the Live workspace. Certain values of the draft element can be necessary to transfer to the live element, such as sys_language_uid typically. This list of fields will define which values are "shadowed" to the Live record. + +Example: +$TCA[?tt_content?] = Array ( +    ?ctrl? => Array ( +        ?shadowColumnsForNewPlaceholders? => ?sys_language_uid,l18n_parent,colPos?, + is_static boolean This marks a table to be "static". @@ -3563,6 +3813,8 @@ t3ver_state - Contains special states of a version used when new and deleted content requires versioning. For an online version with this value set to 1 it means that it is a temporary placeholder for a new element. For an offline (unpublished) version with this value set to 2 it means that when swapped, the page must be deleted also. +For an offline (unpublished) version with this value set to "-1" it is just an indication that the online version has the flag set to "1" (is a placeholder for new records.). This only affects display, not processing anywhere. +t3ver_stage - For custom workspaces elements go through a cycle where 0 (zero) represents the editing cycle, 1 represents review cycle and 10 represents ready for publishing. t3ver_count - 0/offline=draft/never published, 0/online=current, 1/offline=archive, 1+=multiple online/offline occurences (incrementation happens when versions are swapped offline.) t3ver_tstamp - Timestamp of last swap/publish action. The fields pid and uid should have "signed" attributes in MySQL (so their content can be negative!) @@ -3573,16 +3825,12 @@ t3ver_wsid int(11) DEFAULT ?0? NOT NULL, t3ver_label varchar(30) DEFAULT ?? NOT NULL, t3ver_state tinyint(4) DEFAULT ?0? NOT NULL, +t3ver_stage tinyint(4) DEFAULT ?0? NOT NULL, t3ver_count int(11) DEFAULT ?0? NOT NULL, t3ver_tstamp int(11) DEFAULT ?0? NOT NULL, Special t3ver_swapmode field for pages -When pages are versionized it is an option whether content and even the branch of the page is versionized. This is determined by the parameter treeLevels set when the page is versionized. -1 means swap only record, 0 means record and content and >0 means full branch. When the version is later published the swapping will happen accordingly. - -Versioning VS. MySQL version incompatibility issue!!! -Versioning does NOT work with MySQL version 3.23.54 but does with 4.0.18. It is not known now many versions of MySQL the problem impacts. -Symptom is this: After swapping two versions the next autoindex jumps to 2.147.483.647 (one under the limit for a signed 32 bit integer field) -Reason is: When swapping versions the uid of a record is temporarily negated (13 => -13) and when the UID is set negative the autoindex is changed for the affected MySQL versions! +When pages are versioned it is an option whether content and even the branch of the page is versioned. This is determined by the parameter treeLevels set when the page is versioned. -1 means swap only record, 0 means record and content and >0 means full branch. When the version is later published the swapping will happen accordingly. Proc. versioning_followPages boolean @@ -3591,7 +3839,7 @@ If set, content from this table will get copied along when a new version of a page is created. Tracking Originals -It is highly recommended to use the origUid feature for tables whose records are copied with pages that are versionized with content or subtree since this will enable the possibility of content comparison between current and future versions. +It is highly recommended to use the origUid feature for tables whose records are copied with pages that are versioned with content or subtree since this will enable the possibility of content comparison between current and future versions. Proc. versioning [OBSOLETE] @@ -3824,6 +4072,17 @@ (Doesn?t apply to flexform fields.) Display / Proc. +l10n_display +list of keywords +Localization display. +see: l10n_mode + +This option can be used to define the language related field rendering. This has nothing to do with the processing of language overlays and data storage but the display of form fields. + +Keywords are: +hideDiff The differences to the default language field will not be displayed. +defaultAsReadonly This renders the field as read only field with the content of the default language record. The field will be rendered even if ?l10n_mode? is set to ?exclude?. While ?exclude? define the field not to be translated this option activate display of the default data. +Display l10n_cat string (keyword) @@ -3844,13 +4103,14 @@ "default" key in the array can be used to set the default value of the field. softref key in the array can be used to attach soft reference parsers. See under Additional TCA features for information about softref keys. The syntax for this value is key1,key2[parameter1;parameter2;...],.... type key is used to denote the field type from a set of keywords, eg. input, text, check, select, group, user. These are documented in individual sections below. Notice: The value of the ?form_type? key overrides this during form rendering, see below. -?form_type? key is used to set an alternative field type which is used when the field is drawn in the form but not when processed elsewhere in the system. +form_type key is used to set an alternative field type which is used when the field is drawn in the form but not when processed elsewhere in the system. +readOnly key is used to render the form in a way that the user can see the values but cannot edit them. The rendering is similar to the editable variants but not neccesarily the same and might differ in layout and size.Notice: Read only rendering might not be implemented by user defined form items! - displayCond string -Contains a condition rules for whether to display the field or not. +Contains a condition rule for whether to display the field or not. -A rules is a string divided into several parts by ":" (colons). +A rule is a string divided into several parts by ":" (colons). The first part is the rule-type and the subsequent parts will depend on the rule type. Currently these rule values can be used: FIELD : This evaluates based on another fields value in the record. @@ -3870,6 +4130,10 @@ NEW : Requires the record to be new if Part2 is "true" and reversed if Part2 is "false". HIDE_L10N_SIBLINGS : (FlexForms only) This evaluates based on whether the field is a value for the default language or an alternative language. Works only for =1, otherwise it has no effect. Part 1: Keywords: except_admin = will still show field to admin users +HIDE_FOR_NON_ADMINS: This will hide the field for all non-admin users while admins can see it. Useful for FlexForm container fields which are not supposed to be edited directly via the FlexForm but rather through TemplaVoilas Page module for instance. +VERSION: +Part 1 is the type: +IS : Part 2 is true or false: If true, the field is shown only if the record is a version (pid == -1) For FlexForm elements the fields are tags on same level. If is enabled, then the value of other fields on same level is taken from the same language. @@ -3917,7 +4181,7 @@ Display default string -Default value +The default value Display / Proc. eval list of keywords @@ -3927,7 +4191,7 @@ Keywords: required : A non-empty value is required in the field (otherwise the form cannot be saved). -trim : The value in the field will have whitespace around it trimmed away. +trim : The value in the field will have whitespaces around it trimmed away. date : The field will evaluate the input as a date, automatically converting the input to a UNIX-time in seconds. The display will be like "12-8-2003" while the database value stored will be "1060639200". datetime : The field will evaluate the input as a date with time (detailed to hours and minutes), automatically converting the input to a UNIX-time in seconds. The display will be like "16:32 12-8-2003" while the database value will be "1060698720". time : The field will evaluate the input as a timestamp in seconds for the current day (with a precision of minutes). The display will be like "23:45" while the database will be "85500". @@ -3947,6 +4211,7 @@ double2 : Converts the input to a floating point with 2 decimal positions, using the "." (period) as the decimal delimited (accepts also "," for the same). unique : Requires the field to be unique for the whole table. (Evaluated on the server only). NOTICE: When selecting on unique-fields, make sure to select using AND pid>=0 since the field CAN contain duplicate values in other versions of records (always having PID = -1). This also means that if you are using versioning on a table where the unique-feature is used you cannot set the field to be truely unique in the database either! uniqueInPid : Requires the field to be unique for the current PID (among other records on the same page). (Evaluated on the server only) +tx_* : User defined form evaluations. See below. All the above evaluations (unless noted) are done by JavaScript with the functions found in the script t3lib/jsfunc.evalfield.js "(TCE)" means the evaluation is done in the TCE on the server. The class used for this is t3lib_TCEmain. @@ -3961,6 +4226,33 @@ By this configuration the field will be stripped for any space characters, converted to lowercase, only accepted if filled in and on the server the value is required to be unique for all records from this table: ?eval? => ?nospace,lower,unique,required? +User defined form evaluations: +You can supply your own form evaluations in an extension by creating a class with two functions, one which returns the JavaScript code for client side validation called returnFieldJS() and one which does the server side validation called evaluateFieldValue(). +The function evaluateFieldValue() has 3 arguments: +$value :The field value to be evaluated. +$is_in : The is_in value of the field configuration from TCA. +&$set : Boolean defining if the value is written to the database or not. Must be passed by reference and changed if needed. + +Example: +class.tx_exampleextraevaluations_extraeval1.php: + +ext_localconf.php + +Feel free to download the example extension as a T3X file. Display / Proc. is_in string @@ -4298,7 +4590,6 @@ For more information, see how user-functions are specified in the section about ?wizards? some pages below here. Display -Now follows a code listing as example: Example: An example of radio buttons configuration from "sys_filemounts" (see above): script_ended = 0;? @@ -4323,7 +4614,6 @@ It is also possible to configure more complex types where the values from from a look up in another database table and you can even have a type where more than one value can be selected in any given order you like. - Key Datatype Description @@ -4596,6 +4886,12 @@ Keywords are: strict - If set, then permission to edit the record will be granted only if the authMode evaluates OK. The default is that a record having an authMode configured field with a non-allowed value can be edited just the value of the authMode field cannot be set to an unallowed value. Notice: This works only when maxitems <=1 (and no MM relations) since the raw value in the record is all that is evaluated! Display / Proc +exclusiveKeys +string (list of) +List of keys that exclude any other keys in a select box where multiple items could be selected. + +"Show at any login" of "fe_groups" (tables "pages" and "tt_content") is an example where such a configuration is used. + Here follow some code listings as examples: Example - A simple selector box: @@ -4806,7 +5102,7 @@ Display / Proc. allowed string -(list of...) +(list of) For the "file" internal type (Optional): A lowercase comma list of file extensions that are permitted. Eg. ?jpg,gif,txt?. Also see ?disallowed?. @@ -5313,6 +5609,8 @@ extensions for For FlexForms the DS is extended with a tag, which define all settings specific to the FlexForms usage. Also a few meta tag features are used. +Sometimes it may be necessary to reload flexform if content of the field in the flexform is changed. This is accomplished by adding reload inside . A typical example for that is a field that defines operational modes for an extension. When the mode changes, a flexform may need to show a new set of fields. By combining the tag for mode fields with tag for other fields, it is possible to create truly dynamic flexforms. +Notice that changing the mode does not delete hidden field values of the flexform. Always use the mode field to determine which parameters to use. The tables below document the extension elements: Array Elements: @@ -5952,6 +6250,14 @@ See table below for a list of the key values possible. key1=value2|key2=value2|key3=value3|... rte_transform[key1=value1|key2=value2|key3=value3] +fixed-font +Use a monospace font in textarea type fields. +[no options] + +enable-tab +Enable tabulator inside textarea type fields. +[no options] + rte_only If set, the field can only be edited with a Rich Text Editor - otherwise it will not show up. boolean (0/1) @@ -7266,7 +7572,7 @@ ts_links function t3lib_parseHTML::TS_links_rte() function t3lib_parseHTML::TS_links_db() -All -tags (TypoScript specific) are converted to proper -tags. The parameters of the -tags are separated by space. The first parameter is the link reference (see typolink function in TSref for details on the syntax), second is the target if given (if ?-? the target is not set) and the third parameter is the class. +All -tags (TypoScript specific) are converted to proper -tags. The parameters of the -tags are separated by space. The first parameter is the link reference (see typolink function in TSref for details on the syntax), second is the target if given (if ?-? the target is not set), the third parameter is the class (if ?-? the class is not set) and the fourth parameter is the title. All -tags are converted to tags, however only if they do not contain any parameters other than href, target and class. These are the only three parameters which can be represented by the TypoScript specific -tag. ts_reglinks function t3lib_parseHTML::TS_reglinks() @@ -7851,6 +8157,9 @@ For modules the key is special. It is prefixed MOD: and then the module key. For example MOD:web/website.gif or MOD:web_uphotomarathon/tab_icon.gif For examples, see code listing below. +border + +Path to an alternative HTML file instead of the default "typo3/border.html" which is displayed between the page tree and the right frame. Here is an example code listing for how most of these values can be set up in a ext_tables.php file for an extension: @@ -8343,10 +8652,11 @@ For a more practical understanding of Data Structures you should study some of the applications of Data Structures: FlexForms - using Data Structures as a DTD for rendering a hierarchical editing form which saves the content back into XML TemplaVoila - using Data Structures for mapping content to HTML template files.Introduction -This XML format is used for "locallang-XML" files, a format TYPO3 uses for storage of interface labels and translations of them. The format is parsed by t3lib_div::xml2array() which means that tag-names and "index" attribute values are inter-related in significance. The content is always in utf-8. +This XML format is used for "locallang-XML" (llXML) files, a format TYPO3 uses for storage of interface labels and translations of them. The format is parsed by t3lib_div::xml2array() which means that tag-names and "index" attribute values are inter-related in significance. The content is always in utf-8. +llXML files must be used from inside extension directories (system/global/local). See "Inside TYPO3" for more details about locallang-files and the application of this format. -"locallang-XML" files are translated by a backend tool (extension "llxmltranslate") contrary to "locallang*.php" files which are translated online on TYPO3.org. Using a backend tool makes translation faster and more "responsive" for translators who get immediate results. -A "locallang-XML" file contains a set of labels in the default language (always English) and translations of them for each system language in TYPO3 (around 40). Alternatively translations for a single language can be stored externally in an "include-file" which is a practical solution for large amounts of texts in order not to bloat the files; after all people would only need the default labels plus a single or two languages active on an installation.Elements +llXML files from installed extensions are translated by a backend tool (extension "llxmltranslate"). +A "locallang-XML" file contains a set of labels in the default language (must always English!). The translated labels are located in systematically named external files in typo3conf/l10n/[language key]/. Optionally the main files can contain the translations directly but that should only be used in special cases since it constrains the translation process too much. It is also possible with a specific file reference to use other external files than the automated ones.Elements This is the elements and their nesting in the locallang-XML format. Elements nesting other elements (Array elements): All elements defined here cannot contain any string value but must contain another set of elements. @@ -8366,9 +8676,6 @@ - - - Contains the data for translations @@ -8378,19 +8685,17 @@ Contains hash-integers for each translated label of the default label at the point of translation. This is used to determine if the default label has changed since the translation was made. -Contains the text of the default label that was the basis of the translated version! This will be stored only if is set. Otherwise the information is stored in temporary files in typo3temp/ on the local server (which means this meta-information is available but only locally.) -The original text is used to show a diff between the original base of the translation and the new default text so a translator can quickly see what has changed. +Contains the text of the default label that was the basis of the translated version! The original text is used to show a diff between the original base of the translation and the new default text so a translator can quickly see what has changed. -Array of labels for a language. -The "index" attribute contains language key +Array of labels for a language. The "index" attribute contains language key. -External includefile under "": -If the tag used in the context of the tag contains a string instead of an array of labels then it indicates that all labels for the language in question (other than "default"!) is found in another XML file pointed to by this value. The point is to save space so locallang-XML files doesn?t have to carry all translations with them (in particular interesting for CSH content where the amounts of text is enormous.) -The filenames of include files should not start with "locallang..." since they will then be detected directly by the translation tool (which you don?t want!). A common practice could be to prefix them with the language key like in this example: - -Example of including an external file for a specific language: -EXT:csh_dk/lang/dk.locallang_csh_web_info.xml +There are two cases in the context to note: +index = default: Array of default labels. +index = [language key] : +If string: Pointer to external file containing translation, eg. EXT:csh_dk/lang/dk.locallang_csh_web_info.xml +If array: Translations inline in main file (deprecated) +[If not existing, recommended]: Translations in external default file typo3conf/l10n/