.. ================================================== .. FOR YOUR INFORMATION .. -------------------------------------------------- .. -*- coding: utf-8 -*- with BOM. .. include:: ../../Includes.txt data ^^^^ Here you need to specify how to show all the data. This is kind of the heart of everything and it is capable of a lot of different things, combinable in a lot of different ways. So lets get started with a few basic things before we get into the heart of everything, the column configuration (aField). eDisplay -------- Specify the main handler for displaying the data. Technically speaking, these are classes located in the extension's directory under Classes/Data/. All of them share a few settings (described here) and all of them have their own settings as well (described a little further down the page, indicated by headlines starting with *data:*). You may configure all the settings all the handlers need and just select the one primarily needed here (could be useful if you want to configure a multiple-SQL-Frontend-application in one general place using TS and just configure the most necessary things in the single SQL Frontend flexforms). You may also just configure the main and necessary things for one display handler. Enough of the talking, what handlers are there (currently): - **Table** is the most original one as it displays a table full of data allowing in-line editing - **Detail** shows one single entry in detail view - **Csv** is mostly just useful for downloading data in comma-separated form - **Form** shows one single entry directly in a form for editing or allows direct creation - **Manual** is capable of displaying multiple entries but in an unorthodox styling (You define it!) - **Xlsx** is just like the Csv handler a download-handler for Microsoft-ready Xlsx (Excel) files A few more questions about the handlers: *Is any one better than another?* No. Well, that depends on the definition of the word *better*. They all have their specific purposes and for that case they are better than the others. But besides that, some of them e.g. don't allow editing (CSV for instance) and could thus be called *worse* than others. *I don't know what to do, which one should I choose?* Table. *Will there be more in future?* Most likely. Ideas are flying around (grids, RSS, etc.). If you want to develop one or already have developed one, please let me know. aOverruleOtherDisplayIf ----------------------- Okay, this is a bit more advanced, so you might skip this for the moment. *Otherwise*: You may allow the SQL Frontend with this array-config setting to decide automatically which display handler to choose. Why would that make sense? Well, imagine a table view with the possibility to reach a detail view. The latter is just a link to the exact same page including a GET parameter indicating the parameter to the entry shown in detail view. In order not to configure the plugin twice you could set the default eDisplay handler to *Table* and tell SQL Frontend to use *Detail* instead if the GET parameter is there. This is how it works: :: 'aOverruleOtherDisplayIf' => array( 'sDisplayOverruler' => 'Detail', 'sIfSource' => 'GP', 'sIfConnect' => 'AND', 'aIf' => array( 'uid', 'username!=', 'pid==15', 'startdate<12350000' ) ) - **sDisplayOverruler** sets the eDisplay handler to use in case the requirements are fulfilled. - **sIfSource** specifies the source where to look for the requirements. This could be one of the already known aDefault (ref) sources - GP - fe_user - environment - page - tt_content - date - tstamp - ... - **aIf** is another array that holds the requirements (could be multiple ones) in one of the following formats - variable name only (example: *uid*) ckecks if this variable is set within sIfSource - variable==value (example: *username==mario*) checks if variable equals the value - variable!=value (example: *username!=mario*, also *username!=*) checks if variable does not equal value (you may also use empty as value) - variablevalue - variable<=value - variable>=value - **sIfConnect** is either *AND* or *OR* indicating if all (AND) or just one (OR) of the requirements has to be met to use the sDisplayOverruler instead of eDisplay sTemplateDir ------------ String/Directory name. When looking for files, this is the place to look for. You might use the marker ###EXT:bla### here that replaces EXT:bla with the path to the extension with the name bla (for the SQL Frontend's main directory, enter *###EXT:mh_omsqlio###*, default is set to the sub-directory Resources/Template/). bAdd ---- Boolean. If set, creation of new entries is allowed. bDuplicate ---------- Boolean. If set, duplication is "allowed" meaning that it is possible to initiate it. Creation again is only allowed depending on bAdd. bEdit ----- Boolean. If set, editing entries is allowed. bDelete ------- Boolean. If set, deletion of entries is allowed. This means that, depending on dbal/bOnlyEntriesBasedOnCurrentUser, an entry is either removed completely or the deleted-flag ist set. sOrder ------ String. For all list-based handler specify the column/field to order the entries by. Example: :: name bDescending ----------- Boolean. If set to true, default order (sOrder) is descending (from z to a). bOrderOnlyInJs -------------- Boolean. If set to true the sorting won't be applied to the database query (kind-of advanced setting). This means that you are able to sort by the final result if there is - for instance - a callback in between and you want the sorting to be based on that. aField ------ This is heart of everything, the holy grail so to speak. In this associative (= key-based) multi-dimensional configuration array you specify *what* is shown *how*. Therefore you need to configure fields/columns to display and tell the SQL Frontend on what real field/column (of the dbal layer) they build upon. Furthermore you may specify a few general settings and you have to define a field/column handler that is capable of preparing the values. Each handler then has own settings that are explained on subpages of this documentation. **Note:** Fields and Columns are basically the same. Since the SQL Frontend was formerly used for database tables only, *columns* is the old name for what's now called *fields*. Anyhow, both of them describe one single kind of information. Think of it as one single column in the output' table. So, lets first talk about the general things to define for each field/column. Specify one entry per field/column you want to display and give it an array key as well as a configuration sub-array. Example: :: 'aField' => array( 10 => array( 'sColumn' => 'username', 'eClass' => 'TextShort', 'sHeadline' => 'User' ), 20 => array( 'sColumn' => 'email', 'eClass' => 'Link', 'sLink' => 'mailto:###', 'sShow' => '###' ), 25 => array( 'sColumn' => 'telephone', 'eClass' => 'TextShort', 'sWrap' => '+43 |' ) ) **Note:** The keys don't have to follow this pattern (you could also number them 1, 2, 3) but it makes later insertion of new fields/columns easer as you don't have to re-number the other entries. **Caution:** aField is inherited in the configuration levelling system in a special way. First of all, you might configure all fields/columns from a table within, say, TypoScript. If you then, later, in a SQL Frontend plugin, only select the fields/columns in the flexform, all the configuration for those chosen fields/columns i taken from TypoScript (normal configuration behavior would be to overwrite it completely meaning that all per-field/column-settings like headlines and bAutofilter would be gone). The second special thing is, that the first special thing (the kind-of weird overwriting system) only applies if the two configurations are configured with the same table. **Last but not least**, some aField handler may include WHERE parts as array (e.g., all foreign handler) that look like :: array( 'deleted:0', 'hidden!1' ) This syntax allows multiple comparers: - : equals - ! not equals - > larger than - >= larger or equal than - < smaller than - <= smaller or equal than - ~ like (for case-insensitive or wildcard comparisons using %) Sorting """"""" This is done by the main key (in the example above: 10, 20, 25). In order to re-sort them, re-number (or use any alpha-numeric sorting system). sColumn """"""" String. The column/field to configure. Obligatory. **Note:** You may use the same column/field many times. This might be useful for advanced read-only SQL Frontends. Just, so you know ... sHeadline """"""""" String. This is shown next to the form input or in the table header row. bHidden """"""" Boolean. If set to true, this column is not shown. Why to configure it then in the first place? Well, you might need that column for other columns or interceptions as they rely on the currently selected data. Default is, of course, false. bSort """"" Boolean, default is true. If set to false, this column is not sortable by the user. sSort """"" String. One of numeric, text, text(), date, html-*something* or empty. Defines how to apply frontend sorting to this column if necessary (e.g. if in Table mode). If you don't know, why this is necessary, imagine the three rows with the values **8**, **3000** and **102**. The latter (102) is clearly larger a number than the first one (8) but if you sort this column in text mode, a 1 (as in the beginning of 102) comes -- alphabetically thinking -- before 3 (as in 3000) and before before 8 (as in 8). Thus, the resulting *text* order would be 102, 3000, 8. In numeric mode, the whole text is seen as a number and the corresponding order is hence 8, 102, 3000. The difference between text and text() is that text takes the complete content from the cells in order to sort whereas text() applies jQuery's .text() function resulting in stripping off HTML surroundings (e.g., tags). So in case you have a wrapper set that creates a link, use text(). html-something means that any HTML attribute might be taken. This could come in handy if you want to sort a column full of images by their title attribute. In this case you would enter *html-title* (within that, text is applied again). Keep in mind that this is way slower than text, numeric or, even, date. bAdd """" Boolean. You may prohibit a single field to be shown as form element in adding mode. bDuplicate """""""""" Boolean. Just like bAdd but for duplicating. bEdit """"" Boolean. You could set this to false and thus prohibit the user to edit this single field/column. If you generally allow editing, this could make sense. If you generally prohibit editing, this doesn't change anything. bClickableForEditing """""""""""""""""""" Boolean. This does not say anything about permission of editing but only about the fact that the value shown (in general mode, not as a form) is clickable and thus initiates the edit form to load or not. Why? And when to use? Well, this comes in handy in case your output of a field is a link and you want a click on that link to follow it actually rather than display the form. On the other hand, if the form is loaded in any other way, you want it to be editable. In that case, set this to true. sDefault """""""" String. If set, this value is used for creation forms. It is not written to the database if this form element is not shown (e.g. due to bEdit). Thus, it is *not* the same as dbal/aDefault. May take default value markers as known already from dbal/aDefault but in ### marker form (see dbal/sWhereGet for examples). bAutofilter """"""""""" Boolean, only applies to table view. If set, a dropdown will be shown under the headline allowing the user to temporarily select which entries to show. sHelptext """"""""" String. If set, in full-size form mode, a help text (indicated by a little exclamation mark) will be displayed next to that form field. bHidableByUser """""""""""""" Boolean. *Not yet fully implemented.* Later, this should give the logged-in user the opportunity to hide this column/field for his/her personal view. sCssClass """"""""" Supported by some column/field handler. Include manual css classes that are applied to the form elements. Wrapping """""""" Two options (both strings), *sWrap* and *sWrapRaw*. Generally this is a possibility to surround the finally output' value with something else. For instance, to put a Euro sign (€) after a price. The most simple configuration therefore is the following: :: 'sWrap' => '| €' As CSV data views are slightly different, they use the raw output (in future, maybe also other data handler might use that raw output). Anyhow, you might therefore want to differ the wrapper. Thus, for this example, imagine you want to output not just a Euro sign but also a little money icon in front of the output: :: 'sWrap' => 'costs | €', 'sWrapRaw' => '| €' And finally, you might want to use another column to display behind or after the value. This might come in handy in case there is another column where it is saved what currency to use. Put here the internally used name of the column to show (that is either the original column name, or, if used multiple, the column name with a number after it) in marker-surrounding hash symbols. That being said, you also understand that the other column has to be configured in order to select the data from the database: :: 'sWrap' => 'costs | ###currency###', 'sWrapRaw' => '| ###currency###' aValidation """"""""""" Just like aField, this is a multi-dimensional associative array that may be sorted by its array keys. Include specific validation handler for validating form input before saving it to the database. Currently available: ========== =================================================== Name Description ========== =================================================== Required Forces the user to insert a value into this field. ========== =================================================== Example: :: 'aField' => array( 10 => array( 'sColumn' => 'username', 'eClass' => 'TextShort', 'sHeadline' => 'User', 'aValidation' => array( 10 => array( 'eClass' => 'Required' ) ) ) ) aIncludeJs ---------- Very advanced array setting. If you want to re-work any javascript file used in the SQL Frontend, specify a path here that is checked for the files to be included before checking the SQL Frontend default paths (if nothing is found, default fiels are taken). Use multiple paths to check multiple locations in the given (key-dependent) order. Example: :: 'aIncludeJs' => array( 10 => 'fileadmin/tx_mhomsqlio/js/', 20 => 'uploads/tx_mhomsqlio/js/' ) aJsConfig --------- These settings are passed to the client because they are needed by the javascript frontends (that's also why their naming pattern is different from the rest of the configuration). Common settings here are: ========================== =============== ======= ======== Name Used by ... Type Default ========================== =============== ======= ======== enableColumnReorder Table/SlickGrid boolean false autoHeight Table/SlickGrid boolean true forceFitColumns Table/SlickGrid boolean true multiColumnSort Table/SlickGrid boolean true height Table mixed 300 width Table mixed - enableTextSelectionOnCells Table/SlickGrid boolean false rowHeight Table/SlickGrid number 29 ========================== =============== ======= ======== Want to use **real-width column width's**? Set aJsConfig/forceFitColumns to false. Want to resize the whole SQL Frontend in order to have **more flexibility in column width handling**? Set aJsConfig/width to either a number (= pixel value) or a string with unit size (e.g. *100%*). Want to use **in-table scrolling fixing the headlines**? Set aJsConfig/autoHeight to false and maybe adopt height to either another number (representing pixels) or a string with unit size in the end (e.g. *12em* or *50%*). bDontIncludeExtensionCss ------------------------ Boolean. If set, no extension CSS is included. Field/Column handler (eClass) """"""""""""""""""""""""""""" These are the handler you were reading about the whole time. Enter one per field/column that is responsible for its - output (in a table, for instance) - raw output (meaning no-HTML output; e.g. for CSV) - input (into the database table or wherever the data goes depending on dbal settings) They are completely different and thus you should think a bit about which to take. Here are the most common cases. +-----------------------+-----------------------------------+-------------------+-----------------------+ | eClass | Description | Examples | Remarks | +=======================+===================================+===================+=======================+ | Number | numeric values only | uid, price | specify if possible | +-----------------------+-----------------------------------+-------------------+-----------------------+ | TextShort | texts that fit into one line | username, subject | specify if possible | | | (form presented as input field | | | +-----------------------+-----------------------------------+-------------------+-----------------------+ | Link | display text/number as link | detail link, URL | | +-----------------------+-----------------------------------+-------------------+-----------------------+ | TextLong | text that doesn't fit one line | message, | | | | (form presented as textarea) | description | | +-----------------------+-----------------------------------+-------------------+-----------------------+ | Rte | rich text editor (tinymce) | message, | | | | (based on TextLong) | description | | +-----------------------+-----------------------------------+-------------------+-----------------------+ | Timestamp | Unix timestamp, converted to date | crdate, tstamp | only if > 1970-01-01 | +-----------------------+-----------------------------------+-------------------+-----------------------+ | DateTime | DateTime objects or date strings | birthday | | +-----------------------+-----------------------------------+-------------------+-----------------------+ | Bool | numeric but shown as checkbox | archived, done | | +-----------------------+-----------------------------------+-------------------+-----------------------+ | Dropdown | manually pre-defined values | status | better rely on Enum | +-----------------------+-----------------------------------+-------------------+-----------------------+ | Enum | like dropdown, | status | depends on database | | | but with database-defined values | | design | +-----------------------+-----------------------------------+-------------------+-----------------------+ | ForeignSingle | represents 1 entry in other table | user | shows dropdown | +-----------------------+-----------------------------------+-------------------+-----------------------+ | ForeignSingleTree | represents 1 entry in other table | content element | shows grouped dropdown| | | but displayed as children from | grouped by page | | | | another (parent) table | | | +-----------------------+-----------------------------------+-------------------+-----------------------+ | ForeignSingleTextShort| represents 1 entry in other table | company, page | shows free text input | | | but as free text input | title | | +-----------------------+-----------------------------------+-------------------+-----------------------+ | ForeignMultiple1n | represents multiple entries in | related links, | shows input field and | | | other table, but lets the user | pets of people, | multiple selection | | | type them manually | albums of artists | | +-----------------------+-----------------------------------+-------------------+-----------------------+ | ForeignMultipleComma | represents multiple entries as | usergroups, | shows dropdown and | | | comma-separated list in the same | categories | multiple selection; | | | table (old TYPO3 installations) | | don't if not necess. | +-----------------------+-----------------------------------+-------------------+-----------------------+ | ForeignMultipleMm | represents multiple entries in | usergroups, | shows dropdown and | | | other table connected via _mm | categories | multiple selection | | | table (new TYPO3 installations) | | | +-----------------------+-----------------------------------+-------------------+-----------------------+ | FileMultiple | allows upload of files and saves | media, images | use for single files | | | them either as comma-list or in | | also (limit to 1) | | | foreign table | | | +-----------------------+-----------------------------------+-------------------+-----------------------+ | Sort | buttons to order list elements | sorting | no input, buttons | +-----------------------+-----------------------------------+-------------------+-----------------------+ And here you find the handler-specific configuration: .. toctree:: :maxdepth: 1 :titlesonly: :glob: Bool/Index DateTime/Index Dropdown/Index Enum/Index FileMultiple/Index ForeignMultiple1n/Index ForeignMultipleComma/Index ForeignMultipleMm/Index ForeignSingle/Index ForeignSingleTree/Index Link/Index Number/Index Rte/Index Sort/Index TextLong/Index TextShort/Index Timestamp/Index data: Table ^^^^^^^^^^^ bSearch ------- Boolean, default is true. If set to false, no search box is shown (by default, it is located in the top left corner of the table). Anyhow, you might want to specify the styling/location of the box -- in this case have a look into the Resources/Template/ directory at all the Table_*.html files and the setting sTemplateDir. bMultiple --------- Boolean. If set, the multiple dropdown at the bottom of the table is shown. If false, well, not. nEntriesPerPage --------------- Number. There is a dropdown at the bottom of the table (edit it within the TableFoot template) that allows the user to manually select how many entries shall be shown per page. Anyhow, you may specify the default here. **Usability hint:** Choose a value that fits onto the screen without much scrolling. bSum ---- Boolean. If set to true, a row is added at the bottom of the table that tries to calculate the currently selected (not filtered) sum of this column. May only make sense for number columns, although number extraction (using JavaScript's floatval) might also work on textual columns. bManualColumnSelect ------------------- Boolean (default is false). If set to true and the user is a valid logged in frontend user, it is possible for them to manually hide/show columns. Of course, only the set columns are allowed to be hidden/shown. Default is to show all of them. If you want to disable manual hiding for specific columns, have a look at the bHidableByUser setting. bManualFilterSave ----------------- Boolean (default is false). If set to true the user is allowed to save a set filter. If the user is a valid logged in frontend user this filter is then saved in the database; if he/she is not logged in, a cookie is used instead. Saved filters may include autofilter settings, search queries, manual order and the amount of entries shown per page. nEditColumnWidth ---------------- Number. Pixel amount that specifies how big in horizontal measurements the column should be that contains the delete/duplicate links. bColumnSizesInPercentages ------------------------- Boolean. If set, **nWidth** options per column (numerically set in data/aField/*xy*/nWidth) are taken as percentage numbers in order to calculate column widths. If set, also data/aJsConfig/forceFitColumns is automatically set to false. Example: :: data { bColumnSizesInPercentages = 1 aField { 10 { sColumn = uid eClass = Number sHeadline = ID nWidth = 10 } 20 { sColumn = title eClass = TextShort sHeadline = Title nWidth = 60 } 30 { sColumn = crdate eClass = Timestamp sHeadline = Creation sFormat = Y-m-d H:i nWidth = 20 } 40 { sColumn = hidden eClass = Bool sHeadline = Hidden nWidth = 10 } } } The example will resize the title column to 60 % of the table width, whereas both hidden and uid will receive 10 % of the space. The creation date will end up occupying 20 % of the table width. bReloadTableOnSave ------------------ Boolean. If set to true, edited entries are not just re-entered into the table but the whole table is reloaded. This might be necessary if you want to apply sorting after each change or if you need to take changes into account that are not specified in the SQL Frontend (e.g. database operations). bReloadTableOnAdd ----------------- Boolean. If set to true, newly created or duplicated entries are not just entered into the table but the whole table is reloaded. This might be necessary if you want to apply sorting after each change or if you need to take changes into account that are not specified in the SQL Frontend (e.g. database operations). aMultiple --------- Array to expand the multiple dropdown in the bottom. Per entry, specify a controller (like in the flexform settings), a data action (like in the flexform settings), a function to call and define how the client should handle that. Sounds complicated? It is indeed, but it allows nice things. Like CSV download -- but don't worry, that's configured by default. Anyhow, here is how it works: Again, aMultiple is a multi-dimensional associative array, meaning that you define array keys that specify the sorting. Per entry multiple options may be set: - **eController** defines where to call a function; if empty, the function is assumed to be a javascript function, otherwise specify one of the PHP controllers (list, form, or detail) - **eAction** is just needed for the PHP controllers and is one of csv or show - **sFunction** defines what to call; if you want to fetch rows, *getRows* is what you want; otherwise check the data handler to be called for all public methods as they are possible to be called; if in JS mode (controller and/or action not defined), three possible options are available (in this order): if *sFunction* represens a Table.js-context function, this one is called (context: Table.js). If *sFunction* contains a dot and in total represents a JS function within the window context (e.g. location.reload), this one is called. If none of the two options apply, *sFunction* it is just used as the return value (so you could actually define this to be a URL and just use the eHandler redirect in order to redirect to a link, if you need that -- altough this is, of course, not a real multiple action) - **bSubmitSelectedRows** specifies (boolean) if an array of all rows that the user manually selected should be submitted to sFunction - **sLabel** is easy; that's the text that's shown - **bConfirmBeforeAction** would if set (boolean) ask the user if he/she is sure he/she wants to do the intended action - **eHandler** finally specifies what to do with the retrieved result(s); could be one of - *redirect* to the resulting URL (only works if the function returns an URL of course) - *open* opens the resulting URL (see above) in a new window - *refresh* updates the view/grid without reloading the data - *reload* instead completely reloads the data (not the page) - *any js function* to be called - *none* is fine as well - **aFurtherParam** allows you to specify other paramters to submit to sFunction (after the array of selected rows (if specified)), configure as an array in the correct order The following example allows multiple deletion and would ask if the user is sure to delete all selected rows: :: 'aMultiple' => array( 10 => array( 'eController' => 'list', 'eAction' => 'data', 'sFunction' => 'deleteMultiple', 'bSubmitSelectedRows' => true, 'sLabel' => 'Delete', 'bConfirmBeforeAction' => true, 'eHandler' => 'reload' ) ) Another example that would update all entries to be hidden: :: 'aMultiple' => array( 10 => array( 'eController' => 'list', 'eAction' => 'data', 'sFunction' => 'updateMultiple', 'bSubmitSelectedRows' => true, 'sLabel' => 'Hide entries', 'bConfirmBeforeAction' => true, 'eHandler' => 'reload', 'aFurtherParam' => array( array( 'hidden' => 1 ) ) ) ) Ultimately, the following example would enable an Xlsx download for all rows at once: :: 'aMultiple' => array( 10 => array( 'eController' => 'list', 'eAction' => 'xlsx', 'sFunction' => 'getRows', 'bSubmitSelectedRows' => false, 'sLabel' => 'Download all entries as Excel file', 'bConfirmBeforeAction' => false, 'eHandler' => 'redirect' ) ) aConditional ------------ Normally, the table is striped in order to improve usability. Anyhow, it sometimes is necessary to color certain rows under certain conditions. This is how you do that. As the *a* in the beginning of *aConditional* suggests, we are again talking about an associative multi-dimensional configuration array. The sorting (based on the array keys, you already know that) is important here as the first condition to match the current/checked row defines the color. Or, to be more specific, the CSS class to be used. Per condition you may set the field/column which is checked, an operator that specifies how it is checked, and finally a value against which is checked. And of course, you specify the CSS class in case of success. And, as nearly everywhere, you are able to use markers here. And since you can also put markers into other markers you may, for instance, mark entries based on a certain due date (example 2). ================ ========================================== ============ Configuration Possible values Example ================ ========================================== ============ sField field/column names crdate eOperator <, >, <=, >=, ==, !=, in, not in >= mValue number, string, or comma-list (in, not in) 1234567890 sCssClass class to apply in case of success red ================ ========================================== ============ Here's a full example, that marks entries where a eStatus is set to requested yellow, and entries with eStatus set to reveived, green: :: 'aConditional' => array( 10 => array( 'sField' => 'eStatus', 'eOperator' => '==', 'mValue' => 'requested', 'sCssClass' => 'yellow' ), 20 => array( 'sField' => 'eStatus', 'eOperator' => '==', 'mValue' => 'received', 'sCssClass' => 'green' ) ) And another one with markers that marks only entries where a due date dDue (formatted as 2014-12-24) is overrun (in the past) red and those where the due date is pretty close (within one week) yellow: :: 'aConditional' => array( 10 => array( 'sField' => 'dDue', 'eOperator' => '<=, 'mValue' => '###date:Y-m-d###', 'sCssClass' => 'red' ), 20 => array( 'sField' => 'dDue', 'eOperator' => '<=', 'mValue' => '###tstamp2date:###strtotime:+1week###:Y-m-d###', 'sCssClass' => 'yellow' ) ) **Note 1:** In the default stylesheet, classes green, red and yellow are already defined. **Note 2:** You may combine the classes with .odd and .even classes for even more usability. **Note 3:** eOperator can also be **else** (mValue then does not have to be specified) and hold the CSS class to apply in case, no other condition matched. Remember to put this condition in the end of the list. sEditColumnDelete ----------------- Template to use for the deletion link. Default: :: sEditColumnDuplicate -------------------- Template to use for the duplication link. Default: :: sEditColumnSave --------------- Template to use for the saving link (in creation/edit mode). Default: :: sEditColumnAbort ---------------- Template to use for the abort link (in creation/edit mode). Default: :: sSumFooterDescription --------------------- Template to use for the footer sum column (see Number column). Default: :: nSumFooterDescriptionColumn --------------------------- Default: **0** This is the column index (start with 0) under which the sum field is placed (What's sum? See Number column.). bOnEditLinkToPage ----------------- Boolean. If set, clicks intended to edit a row do not open the form but the link specified in sEditLink. sEditLink --------- See bOnEditLinkToPage. You may use any displayed (!) column of the current entry as marker here (surround with ###). In case you want to use a parameter that is already in use as another GET/POST parameter, you may also prefix it with a "col-" indicator. That means, that if you want to use the column "id" but your normal TYPO3 links look like "index.php?id=123", then "id" in your sEditLink gets translated to 123 (since the system automatically replaced GET/POST parameter names. In this case, use ###col-id### in your sEditLink instead. Example: :: ?id=123&uid=###uid### bOnAddLinkToPage ---------------- Boolean. Like bOnEditLinkToPage but for the "add new entry to this list" button. No markers available here. Example: :: ?id=123 sDuplicateLink -------------- If bOnAddLinkToPage and bDuplicate are set, you need this setting as well. You may -- as in sEditLink -- use markers here. bOpenAddFormInPopup ------------------- Boolean. If true, add form is shown in javascript popup (modal window). If set to true, bReloadTableOnAdd is set to true automatically. Depending on bOnAddLinkToPage either the form or sAddLink is loaded. bOpenDuplicateFormInPopup ------------------------- See bOpenAddFormInPopup. bOpenEditFormInPopup -------------------- See bOpenAddFormInPopup. sOpenFormInPopupPartly ---------------------- String, CSS selector in order to only show a part of the loaded page. Used together with popup form and opened page on add/duplicate/add (this is, for instance, bOpenAddFormInPopup together with bOnAddLinkToPage and sAddLink set). Only the HTML elements from the opened page that match the current setting are shown within the popup. data: CSV ^^^^^^^^^ sDelimiter ---------- String. Delimits every value, default is **,**. sQuote ------ String. Surroundsd every value, default is **"**. sLinebreak ---------- String. Specifies how a line should end. Default is CRLF which is windows linebreak. bPrepareForMsExcel ------------------ Boolean. This is a bit of a weird name for the fact that, if set to true, a UTF-8 BOM will be put in the beginning allowing Microsoft Excel to also (as other application do by default) recognize how the data is encoded. sTempSubDirectory ----------------- String, default is **mh_omsqlio**. This is the sub directory in TYPO3's temp directory typo3temp/ where the CSV files are saved. data: Xlsx ^^^^^^^^^^ Allows download directly for Microsoft Excel (using PHPExcel library) with various settings already set (autofilter, fixed top row, multi-line, etc.). sTempSubDirectory ----------------- String, default is **mh_omsqlio**. This is the sub directory in TYPO3's temp directory typo3temp/ where the Excel files are saved. data: Detail ^^^^^^^^^^^^ One general thing to know about detail view is that you can either force it to always show a certain entry or depend the entry to be shown on certain aspects (like GET/POST variables, currently logged in user, etc.). And another general thing to know about detail view is that you can combine those two settings by generally showing the entry dependent on certain aspects and at the same time use the force (harhar, use the force ...) to set a certain entry as default entry if no aspects are specified. bShowFixedEntry --------------- Boolean. This is the first of the first general things. If set to true, a fixed entry has to be specified (using aFixedId). If set to false, aspects have to be specified (aParamId) that tell the SQL Frontend how to find the correct entry. If you want to combine the two settings as explained in the other general thing to know about detail view, set this setting to false. bUseFixedIdAsDefaultForParamId ------------------------------ Boolean. This is the switch you need to set to true if you want to combine a default entry with a dynamically retrieved one. aFixedId -------- Specify one or many restrictions here that sum up to identify one fixed entry to be shown. Multi-dimensional array with field/column as key defining for which field/column the restriction should be checked. The value to each key may either be a manually entered value or a configuration array where you could, like in dbal/aDefault (ref) set a source, a field and a wrapper (e.g. to specify the currently logged-in user's ID). Example: :: 'aFixedId' => array( 'pid' => 14, 'user_id' => array( 'sSource' => 'fe_user', 'sField' => 'uid', 'sWrap' => '|' ) ) In the example the first entry to be found is taken that matches with pid = 14 and user_id equals the uid of the currently logged-in user. aParamId -------- If you allow the detail view to choose the entry to be shown based on certain conditions (bShowFixedEntry is false), you need to define where to find these conditions and to which field/column they should be applied. Therefore, again, specify an associative (key-based sorted) configuration array that holds on each key another array with two options defined: :: 'aParamId' => array( 10 => array( 'sParam' => 'id', 'sColumn' => 'pid' ), 20 => array( 'sParam' => 'tx_mhomsqlio_pi1[uid]', 'sColumn' => 'uid' ) ) The SQL Frontend now checks for the first entry that matches *both* requirements. The first (key 10) tells the extension to take the GET/POST parameter with the name *id* (which is, in TYPO3 terms, the current page ID) and to apply it to the field/column with the name *pid*. The second one (key 20) takes the GET/POST parameter *tx_mhomsqlio_pi1[uid]* (a TYPO3-common array structure in GET/POST values) and applies it to the column/field *uid*. data: Form ^^^^^^^^^^ This handler directly shows a form. This could either be a form for new entries, thus it is just an empty (pre-filled with default values) form that allows the user to create data entries. Or it could also be an edit form. And for the latter, again, as for the detail view, you may either specify one single entry to be edited or a few rules to find the entry to be edited dynamically. bIsEditForm ----------- Boolean. If set to false, this is a creation form. If true, it's an edit form and aFixedId is required. bIsEditFormIfIdIsset -------------------- Boolean. Allows to dynamically determine whether the form should be an edit or a creation form. If set to true and bIsEditForm set to false aFixedId/aParamId/bUseFixedIdAsDefaultForParamId-settings are used to determine an ID to be edited. If nothing is found, form is shown to be a creation form. You don't get it? Let's say, you want a list (table) displayed and on add/edit show the full-page form (on the same page, using the same plugin). Here is your necessary code (besides the usual bAdd, bEdit and other settings): :: data { aOverruleOtherDisplayIf { sDisplayOverruler = Form sIfSource = GP sIfConnect = OR aIf { 0 = new, 1 = uid>0 } } bOnAddLinkToPage = 1 bOnEditLinkToPage = 1 sAddLink = ?id=###id###&new=1 sEditLink = ?id=###id###&uid=###uid### bOnSaveLinkToPage = 1 bOnCancelLinkToPage = 1 sSaveLink = ?id=###id### sCancelLink = ?id=###id### bIsEditFormIfIdIsset = 1 aFixedId { uid { sSource = GP sField = uid } } } aFixedId -------- Is exactly the same as for the detail view, so check there. **Hint:** Also bUseFixedIdAsDefaultForParamId and, thus, aParamId apply as for the detail view. bIsDuplicateFormFromParamId --------------------------- Boolean. If set to true and aParamId is set and -- based on aParamId -- an ID is found, this entry is used as duplication base. Does not work with bIsEditForm or bIsEditFormIfIdIsset set to true. bOnSaveLinkToPage ----------------- Boolean. If set to true, clicks on the submit button first save the entry (well, that's quite normal) but then do not reset the form but redirect to the link specified in sSaveLink instead. sSaveLink --------- See bOnSaveLinkToPage. You may use any displayed (!) column of the current entry as marker here (surround with ###). Also the marker *_sMhOmsqlioId* is allowed which is a SQL-Frontend-internal id string. Example: :: ?id=123&uid=###uid### **Hint:** If bOnSaveLinkToPage (or bOnCancelLinkToPage, respectively) is set to true but sSaveLink is found to be empty, the SQL Frontend will (after saving, of course) redirect to the last page in the browser's history (more technically speaking, a *history.go(-1)* is performed). bOnCancelLinkToPage ------------------- Boolean. If set to true, a click on the cancel button redirects to the page specifed in sCancelLink. sCancelLink ----------- See bOnCancelLinkToPage. If in edit mode (bIsEditForm) you may use any displayed (!) column of the current entry or *_sMhOmsqlioId* as marker here (surround with ###). bEnablePreview -------------- Boolean. If set to true, a preview button is initiated. This preview button is capable of ... #. change certain settings in the form (e.g. enable a hidden flag) #. save/submit the form #. redirect or open a new page If set, it needs the following settings starting with *Preview* to be specified as well. bSetValueBeforeSaving --------------------- Boolean. If set to true, values set in aPreviewValue are set before submitting the form. If false, aPreviewValue is ignored. aPreviewValue ------------- Array with columns/fields as keys and values to be set as, well, values. Keep in mind that these values will be set using JavaScript and are, thus, processed throught normal field/column handler. Example: :: 'aPreviewValue' => array( 'hidden' => 1, 'subheader' => 'not yet published' ) sPreviewLink ------------ String. The link to open after the form was successfully submitted and the entry successfully saved/created. sPreviewWindow -------------- String. Defines where to open the link. Default is *_blank* which opens a new window. If you want it to be opened in the current window, use *_self*. sTemplateHead ------------- String/Filename. If specified the handler searches for a file with that name in sTemplateDir and uses it as the safe-cancel-form head before outputting the form itself. Thus, it has to contain the buttons. Suggestion is, that you either stick to one of the included examples (see below) or take a look at them in order to create your own. What is possible here? Well, the name you enter here, will get a ".html" appended and, if bEnablePreview is not set or set to false, also a "\_NoPreview" will be appended here. So *FormHead* (the default here) will transform either into *FormHead\_NoPreview.html* or into *FormHead.html*. Thus, you could enter *FormHead* here even though that's unnecessary as it represents the default value. Anyhow, you could also enter *FormHead\_Send* here which would show send and abort buttons instead of the save/cancel combination. Again, this would (in case of ...) transform to *FormHead\_Send\_NoPreview.html* or *FormHead\_Send.html*. sTemplateFoot ------------- See sTemplateHead. The same applies here, but please replace *Head* with *Foot*. bHideTemplateHead ----------------- Boolean. If set to true, no heading template (this is the top bar with buttons) is shown. bHideTemplateFoot ----------------- Boolean. Same here, but please think before setting both bHideTemplate... settings to false - as this means that no save button is available to the user. bValidateAllValues ------------------ Boolean. Normally, if the user changes a single field value, this value gets validated right on time. Before submitting, the whole form gets validated. Anyhow, under some circumstances, you might want to validate the whole form every time a single value gets changed (this might be the case if you need all form values in an interceptor while the user is still editing the form). If so, set this to true. data: Manual ^^^^^^^^^^^^ Okay, imagine a list of entries (just like in the Table handler) but that except shown in a table the styling of the single entries is whatever you like it to be. Thus you could align images with title (each representing one entry) next to each other. Or kind-of-a grid system. Or an Unordered List (UL) or Ordered List (OL) respectively. As you can see, options are infinite. nEntriesPerPage --------------- Numeric. This is special this time as only one page is shown. Thus this is like a limit factor. Set to -1 if you want to load all entries. sTemplateHead ------------- String/Filename. If specified the handler searches for a file with that name in sTemplateDir and outputs it before outputting all the entries. sTemplateFoot ------------- See sTemplateHead and think of a human body (head vs. foot ... you know, what I mean). Styling ------- This is pretty easy as it is exactly the same as in Detail view (so see that description for more details). The only thing you should know is where to edit all the styles. Create (or use) a file called *Manual.html* in sTemplateDir.