EXT: Admin Interface¶

What does it do?.¶

This extension attempts to be a universal front end plugin by creating search/list/view/edit user interfaces for any table that has associated TCA meta data. Typically this extension is used in conjunction with the database kickstarter which is used to build the data model for an application. It is very useful for providing front end submission and administration of records for extensions that only provide front end rendering functionality. With flexible searchBoxFields TS configuration, it is very useful for search/list view also.

This extension is designed to be used by typo3 site developers with some knowledge of typoscript but not necessarily any knowledge of php. Being able to use the kickstarter is required if you want to make your own database tables.

It is also designed with hooks at many levels (method/wrap/field/sql/action) by an advanced user to simplify small customisations to the raw data model derived user interface..

The admin interface is placed in a page as a plugin and a template record is configured to define what table and fields are presented and what functionality is presented (search?/delete?/edit?). The extension is intended to be easy to use so the minimum required configuration is the name of the table that is to be presented. eg plugin.tx_admininterface_pi1.table=fe_users will produce a search/list/view user interface.

The extension was started by extracting form field rendering code from the fe_adminLib.inc class provided with the core typo3 code. It differs from the fe_adminLib (and derived fe administration solutions) by generating user interfaces without necessarily requiring HTML templates to make the rendering work and has many improvements in field type support including date, rich text, file upload and database relationship (including select/radio and popup window) types.

All output is templatable for maximum flexibility. A template file and subpart can be specified for the list/view/form/searchform views. Template files can be active in converting the provided data into a view format by embedding php in the template files.

This templating approach has been depreciated in favor of using TS content objects which provides even more flexibility.

There are many typoscript configuration options that include php functions to customise the functionality. These include method overrides, per field defaults and overrides. It is possible to create fake fields that appear in your output but are derived entirely from php.

Email notifications at various stages is the plugin process are configurable from typoscript. Links can be configured in emails to allow one click editing of records from an email client. This replicates the 'setfixed' behaviour of the fe_adminLib. Additionally it is possible to embed a login form into a HTML email.

Breaking news. The admin interface now has a wiki page for frequently asked questions. http://wiki.typo3.org/Admin_interface .

Screenshots¶

Configuration involves inserting the admin_interface plugin in a page and creating a TS template record on that page.

Results in front end list and search form

With buttons linking to editing forms

FAQ¶

FAQ¶

Configuring available fields¶

Using typoscript it is possible to control which fields are displayed in the lst, view, edit and search forms.

• Only these fields are provided as markers and saved to database
• the HTML template can skip further fields

plugin.tx_admininterface_pi1 {
  record {
    listFields=name,email
    viewFields=name,email,phone,fax,address
    editFields=username,name,email.phone,fax,address
    # these fields are non editable in the edit form
    editViewFields=username
  }
}

Configuring behaviors¶

• uiconfig
• uiconfig.allowdelete
• uiconfig.allowedit
• uiconfig.allownew
• uiconfig.allowprint
• uiconfig.disableview
• uiconfig.viewbeforeedit
• uiconfig.autosearch

Search Configuration¶

• record.searchBoxFields.key { type=text |daterange|picklist|picklist_custom fields=name,address }
• record.sortFields
• record.groupByFields
• uiconfig.maxListRows
• joins

Output Configuration/TS Content Object Templating¶

The section rendering resources defines a rendering configuration section for each major user interface component – view, form, list, searchform. Each section provides a renderObj which is a TEMPLATE cObj by default. The rendering methods provide a HTML default template including all relevant markers and wraps which is passed with a marker array to the cObj->getSingle method. Each section may also provide an imageRenderObj section to define how images are rendered for this view and a marks section to add additional markers or customise existing ones.

Use plugin.tx_admininterface_pi1.renderingresources.view.dumpDefault Template=1 to see the default template, a list of markers and the cObj configuration used for rendering the view. Similarly for form,list,searchform.

To override the template for the form, use renderingresources.form.renderObj.template.file=mynewtem.html

The default list configuration provides a series of nested subparts LIST_CATEGORIES_AND_ITEMS,LIST_CATEGORY,LIST_ITEMS,LIST_ITEM for which the rendering properties including stdWrap and wrap and marks and subparts and ... can be set. By overriding LIST_ITEM.marks it is possible to create button images using the GIFBUILDER content object.

The option renderingresources.list.categoriseBy=fieldname triggers categorisation during list rendering. The category field can be a relationship to another table. Where the relationship allows multiple select, the first selected item is used. The label field of the related table is provided when rendering the LIST_CATEGORY subpart as the CATEGORY_LABEL marker. Categories are sorted by the title of their label field.

Configuring field customisations¶

override and fakefields

Configuring validation¶

The validation routines use the TCA to determine if the incoming data is in a valid format. Additionally there are global options to simplify configuration of validation rules.

• record.uniqueFields
• record.requiredFields

Configuring Email notifications¶

• emailOn
• infoMail
• setfixed

Configuring Database Relationships¶

Multiple varieties of field types for database relationships are supported

one to many (foreign key in child pointing to parent)

• selector boxes and checkboxes
• search with popup. Implemented using the record.fakefields typoscript configuration

many to one (foreign key in parent pointing at child)

- radiobuttons

- popup window allowing management of related child with foreign key in parent. Allow search and select, new record creation and removal of association to child records. Implemented using the record.inputrender typoscript configuration

inputrender {
    client_id {
        type=popupsearch
        # limit on search results that appear in popup box
        extrawhere=
        # page id configured for editing of child records
        editpid=36
        # fields that shown in popup box list
        popupListFields=name,street,suburb
        # formatting for display of related child inline to parent form
        format {
            # wrapped around whole input field – include markers for addlink, deletelink
            wrap=<table border='1' width='100%'><tr ><th>Name</th><th align='right'>###addlink###</th></tr>|</table>
            edit=<tr><td>###name###</td><td>  ###editlink### </td></tr
        }
    }

Joins¶

It is possible to configure a join that will allow lists and views and search queries to access fields in join tables directly.

table=fe_users
alias=u
join.0 {

table=fe_groups
alias=g
condition=and find_in_set(g.uid,u.usergroup)
fields=title,description

}

If a join is configured then field names must be prefaced by the table alias in listFields etc. For example listFields=uname,gtitle,gdescription.

When referencing joined fields in searchBoxFields, the fields are prefaced by the table alias and a dot ready to be used directly in a sql query.

Where fields are configured as excludeFields in the TCA, the TCA meta data is not normally available for listFields etc unless there is a backend user logged in. By using the configuration option plugin.tx_admininterface_pi1.loadTCA=<comma seperated table names>. This is done by default for the current table but any join tables must be listed explicity to allow correct form/output generation. This needs to be fixed.

Access Control¶

Access control is based on front end users and groups. The plugin limits access in one of two ways. By using the inbuilt group based page/content access restrictions it is possible to limit access per group.

The configuration option plugin.tx_admininterface_pi1.lockToFEUser=1 limits editing of records to session users with a uid matching the cruser_id of the record.

Creating Dependant Fields and Dependant Search Fields¶

• type field and fakefields

Other Cusomisations¶

XCLASSES, method override, php templates

Behavior Customisation using TS tests¶

By using TS tests in the constants section of your template, it is possible to set configuration values per FE user group or based on other criteria that select how the extension behaves.

eg

CONSTANTS

AI.allowDelete=0

AI.editFields=name,date

# adminGroup

[userGroup=3]

AI.allowDelete=1

AI.editFields=name,date,restrictedfield

SETUP

plugin.tx_admininterface_pi1.record.editFields={$AI.editFields}

Another approach with similar results is to configure multiple pages with varying configurations that are access restricted to particular FE groups.

FAQ¶

• not an array error –> where invalid table name is specifiedma
• no show field input –> invalid input type – not supported type or missing TCA for field
• ### markers in output –> incorrect marker in template
• the default configuration options are all messed up -> remember that typoscript cascades. If you create a child editing page underneath a parent editing page in the page tree, the parent configuration will act as a default.

TS Configuration Options¶

Global configuration options affecting a range of behaviours.

Section join¶

It is possible to include fields from related database tables in list/view results and query criteria by configuring a sql join.

Multiple layers of joins can be created using join.0, join.1,.... resulting in queries like

select * from (bdg left join res on bdg.bid = res.bid) left join dom on res.rid = dom.rid;

When using the fields that result from a join query there are two conventions. listFields and viewFields prepend the alias of the additional table to the additional table field names. searchBoxFields.$fieldName.fields appends the alias and a dot to the field name so that the configuration can be used directly in the sql query string.

Section record¶

Specify lists of fields that are used in various situations. The init method of the controller class provides default values for these configuration options using the TCA to find sensible defaults.

inputrender.client_id {
    type=popupsearch
    extrawhere=and find_in_set(usergroup,1)
    editpid=36
    popupListFields=name,street,suburb
    format {
        wrap=<table border='1' width='100%'><tr ><th>Name</th><th align='right'>###addlink###</th></tr>|</table>
        edit=<tr><td>###name###</td><td>  ###editlink### </td></tr>
    }
}

Section uiconfig¶

Enable/disable functionality using the allowField. Various constants controlling behavior and to some extent rendering.

Section renderingresources¶

Section infomail¶

Note that default infomail configuration exists for insert,update,delete,view,setfixed_approve

eg

insert {
    template.text=<html>###SYS_SETFIXED_EDIT###<br/>###SYS_SETFIXED_APPROVE### ###SYS_SETFIXED_DELETE###<br/>A new record has been created <br>###QUICKVIEW###<br>  </html>
    to.email={$admin_email}
    subject=Record Created
    from.email={$from_email}
}

Section emailOn¶

This section is used in conjunction with the infomail section to define when notification emails should be sent.

Section setfixed¶

Configuration of actions that can be executed by clicking on links (most likely embedded in emails). An MD5 hash of the field values of the record at the time of rendering is used to authenticate access. This means that access is only available until the record changes.

Section upload¶

Section rte¶

RTE configuration here is very limited. It is best to use page TS config to set

RTE.default.FE {

showButtons=

toolbarOrder=

}

Remember to enable any plugins in the extension configuration

Section functionOverride¶

Three mechanisms for hooking in custom PHP are available.

- Fakefields/overrides/defaults all allow calling a function to act as the value for a field.

- By specifying a PHP file as a templates.searchForm|view|form|list.file, PHP becomes available at the component rendering level after the template markers have been prepared by the generic code.

- The functionOverride set of configuration allows redefining any of the methods that have these hooks for total control.

Examine the source for the details of parameter passing to hook functions.

Field Selections¶

The default behavior of the admin interface is to automatically select fields that are shown in the form, view, list, .... It is also possible to override the fields available for a given purpose with TS configuration eg plugin.tx_admininterface_pi1.record.listFields=name,address.

Selection of default values is based on a number of sources.

• columns available in the TCA for this table are used to set defaults for user interface fields
• fields defined in the database table definitions (queried in init) are used to filter generation of database queries. dbFields,selectFields,insertFields,updateFields are set by default to all the available database columns.

the field configured as a label in the TCA for this table (config.label) is used to select a single default listField.

The result of selecting default values is stored in the conf variable as a comma seperated list under the keys plugin.tx_admininterface_pi1.record.???Fields. Where there is existing configuration coming from a TS template record, that is used in preference. HINT: To debug an some example configuration containing a complete list of the available fields, set plugin.tx_admininterface_pi1.debug.fields=1.

The resulting field lists include

VIEW

listFields,editFields,editViewFields,viewFields,emailQuickViewFields

DB

insertFields,updateFields,dbFields,sortFields,groupByFields,selectFiel ds

Other field lists that are not set automatically

fakefields,overrides,defaults

FakeFields provides a way to tie in constant value or function derived values as user interface fields. Fakefields can be used in the UI field lists above ie listFields=fake_combinedfirstlastname,address,phone

Overrides provides a way to set a constant value or function derived value into a field when the form is rendered and when loaded from or saved to the database. If overrides.$fieldName.createOnly=1, the overrides is only performed when creating a new record.

Defaults provides a way to set a constant value or function derived value into a field when a form is rendered for creating a new record.

Global and Class Variables¶

- better as functions??

conf

piVars

[DATA]

[search]

controller variables

Access Controls¶

NOTE: The following description is what will be. At time of writing only lockToFEUser and ***Fields are supported.

As this is a front end plugin, access controls are based strictly on fe users and fe groups.

By using this extension, you are opening access to potentially change and delete records from a database table. Whilst reasonable defaults are provided, it is possible to create situations when any web site visitor can manipulate database records. Use with care!!

Relevant configuration options include

TODO allowedTables comma seperated list comma seperated list of tables that are available for editing by this extension

lockToFEUser boolean(1/0) only allow access to records where the cruser_id field matches the uid of the current logged in user.

TODO lockToFEGroups comma seperated list group ids that are allowed to use this plugin.

***Fields comma seperated list list of database fields that are allowed for particular functions eg list,view,...

allow*** boolean(1/0) user interface features to enable

* By using typoscript conditions based on group membership it is possible to customise the available field lists for different user groups.

Where lockToFEUser and lockToFEGroups is disabled, if allowEdit or allowDelete are enabled a warning message is displayed about insecure configuration unless uiconfig.forcePublicEditing is enabled.

Alternatively different user interfaces can be presented to different user groups by creating multiple custom configured pages with group level access control enabled.

setFixed authentication