Developer API¶

About¶

The goal of this class is to simplify the use of flexform fields. It will allows you to easily access to every field contained in a flexform, without having to use the xml2array method from the t3lib_div class, which produces an huge multidimensionnal array which is hard to work with.

Usage¶

The only thing you have to do is the creates a new instance of the class, and pass the XML data of the flexform to the constructor.

Here's an example:

// Gets the flexform helper with some flexform data from a database record
$flexHelper = tx_apimacmade::getPhp5Class( 'flexform', array( $row[ 'flexform_field' ] ) );

$myFieldValue = $flexHelper->myFieldName;

foreach( $flexHelper as $fieldName => $fieldValue ) {

    // ... do something ...

}

$flexHelper->setDefaultSheet( 'sDEF' );
$flexHelper->setDefaultLang( 'lDEF' );
$flexHelper->setDefaultValue( 'vDEF' );

$myFieldValue = $flexHelper->getFieldValue( 'myFieldName', 'sDEF', 'lDEF', 'vDEF' );

// Process each base field of the flexform
foreach( $flexHelper as $fieldName => $fieldValue ) {

    // Checks if we have a section field
    if( is_array( $fieldValue ) ) {

        // Process each section item
        foreach( $fieldValue as $sectionItem ) {

            // Gets the item type
            $itemType = ( string )$sectionItem;

            // Gets each sub-field of the current item
            foreach( $sectionItem as $sectionItemFieldName => $sectionItemFieldValue ) {

                // ... do something ...
            }
        }

    } else {

        // ... processing for normal fields ...
    }
}

Functions for the initialization of the class.¶

Those functions are the core of this API. Except the class constructor, they are all reserved for internal use.

Class constructor.¶

This function can't be called by t3lib_div::makeInstance, since it needs the parent object to be passed as an argument. Sorry about that.

When you call the constructor, do not forget to set the $apimacmade_version class variable, as it will be used for version checking. Read the example below to find out more.

&$pObj

1:
2:
3:
4:
5:
6:
7:

// Typo3 FE plugin class
require_once(PATH_tslib.'class.tslib_pibase.php');

// API class
require_once(t3lib_extMgm::extPath('api_macmade').'class.tx_apimacmade.php');

class tx_myextension_pi1 extends tslib_pibase {

1:
2:
3:
4:
5:
6:
7:
8:
9:
10:
11:
12:
13:

class tx_myextension_pi1 extends tslib_pibase {

  // Same as class name
  var $prefixId = 'tx_myextension_pi1';

  // Path to this script relative to the extension dir
  var $scriptRelPath = 'pi1/class.tx_myextension_pi1.php';

  // The extension key
  var $extKey = 'myextension';

  // API version
  var $apimacmade_version = 1.0;

1:
2:
3:
4:

function main($content,$conf) {

  // New instance of the API
  $this->api = new tx_apimacmade($this);

1:

$this->api->debug('Hello World!');

Produce a version error message.¶

This function produce the error message if the version of the API is too old.

$version

false

Produce an error message.¶

This function is used to produce an error message, if another function report a problem, often caused by bad argument types.

$method

$message

$line

Gets a PHP 5 class.¶

This function is used to load an PHP5 class contained in this API.

$name

$args

array()

Returns a new instance of a class.¶

This method does basically the same stuff as the makeInstance method from t3lib_div, except the fact that this one can take arguments that will be passed to the class constructor.

$className

$args

array()

Functions for frontend development.¶

All of those functions are only available in a frontend context. They also all need the API class to be instantiated, as they will use the internal variable $pObj.

Do not try to use them out of a frontend context, and without the API class instantiated.

Merge plugin TS configuration with flexform configuration.¶

This function merge the plugin TS configuration array with the flexform configuration (priority is given to flexform). Everything is done automatically with a mapping array containing the path of the TS elements to replace, and the path of the flexform fields in the XML.

$mapArray

$tsArray

$flexRes

1:
2:
3:
4:
5:
6:
7:
8:
9:
10:
11:
12:
13:
14:
15:
16:
17:
18:
19:
20:

// Mapping array for PI flexform
$flex2conf = array(
  'pidList' => 'sDEF:pages',
  'recursive' => 'sDEF:recursive',
  'allowHTML' => 'sDEF:allow_html',
  'templateFile' => 'sTEMPLATE:template_file',
  'dateFormat' => 'sDEF:date_format',
  'list.' => array(
          'defaultMode' => 'sLIST:default_mode',
          'maxRecords' => 'sLIST:max_records',
          'maxPages' => 'sLIST:max_pages',
          'displayFields' => 'sLIST:display_fields',
          'pictures.' => array(
                  'file.' => array(
                          'maxW' => 'sLIST:image_maxw',
                          'maxH' => 'sLIST:image_maxh',
                  ),
          'params' => 'sLIST:image_params',
  ),
);

sDEF:pages

1:
2:
3:
4:
5:
6:
7:
8:

// Init flexform configuration of the plugin
$this->pi_initPIflexForm();

// Get flexform informations
$piFlexForm = $this->cObj->data['pi_flexform'];

// Ovverride TS setup with flexform
$conf = $this->api->fe_mergeTSconfFlex($flex2conf,$conf,$piFlexForm);

Loads a template file.¶

This function reads a template file and store it as a C-Object in the API class.

$templateFile

1:
2:

// Store template file in the API class for further processing
$this->api->fe_initTemplate('EXT:myextension/pi1/template.html');

Template rendering.¶

This function analyzes the template C-Object, previously set by $this->fe_initTemplate and substitute the specified section with the specified subsections.

$templateMarkers

$templateSection

1:
2:
3:
4:
5:
6:
7:
8:
9:
10:
11:
12:
13:
14:
15:
16:
17:

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN">

<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en">

        <head>
                <meta http-equiv="content-type" content="text/html; charset=iso-8859-1" />
                <title>Template File</title>
        </head>

        <body>
                <!-- ###HELLO### -->
                <p>###WORLD###</p>
                <p>###UNIVERSE###</p>
                <!-- ###HELLO### -->
        </body>

</html>

1:
2:
3:
4:
5:
6:
7:
8:

// Template markers
$templateMarkers = array(
  '###WORLD###' => 'Hello World!',
  '###UNIVERSE###' => 'Hello Universe!',
);

// Render template
$content = $this->api->fe_renderTemplate($templateMarkers,'###HELLO###');

Returns the content with CSS.¶

This function is used to output the requested content wrapped in an HTML element, containing a CSS class.

$element

$className

$content

false

$piClass

1

$htmlSpecialChars

false

$startTagOnly

false

$params

array()

Sets internals variables.¶

This function is used to set the internal variables array ($this->pObj->internal) needed to execute a MySQL query.

$results_at_a_time

false

$maxPages

false

$searchFieldList

false

$orderByList

false

Adds swapClasses JavaScript Code.¶

This function adds the javascript code used to switch between CSS classes.

$class1

$class2

Returns a swapClasses link.¶

This function is used to output the requested content wrapped in an HTML link element calling the swapClasses JS function.

$elementId

$content

false

$htmlSpecialChars

false

$startTagOnly

false

$params

array()

Create IMAGE cObjects.¶

This function creates an IMAGE cObject for each given filename.

This function is particularly useful with image references stored in a database field.

$imgRefs

$conf

$imgPath

false

Link a string to some page.¶

This function links a string to a page (the active one by default).

It's the same function as tslib_pibase::pi_linkTP(), except that a configuration array for the typolink can be passed directly as argument, and that it will always returns a correct cHash.

$str

$urlParameters

array()

$cache

0

$altPageId

0

$conf

array()

Link a string to some page.¶

This method is the same as method fe_linkTP_keepPIvars of tslib_piBase, except the fact that it will always return a correct cHash.

$str

$overrulePIvars

array()

$cache

0

$clearAnyway

0

$altPageId

0

Returns an URL to some page.¶

This method is the same as method pi_fe_linkTP_keepPIvars_url of tslib_piBase, except the fact that it will always return a correct cHash.

$overrulePIvars

array()

$cache

0

$clearAnyway

0

$altPageId

0

Link a string to some page.¶

This function links a string to a page (the active one by default), while keeping current piVars.

Additionnal piVars can be added or overlaid in the overrulePIvars array. All piVars found in the unsetPIvars array won't be preserved.

$str

$overrulePIvars

array()

$unsetPIvars

array()

$cache

0

$clearAnyway

0

$altPageId

0

Returns an URL to some page.¶

This function returns the URL to a page (the active one by default), while keeping current piVars.

Additionnal piVars can be added or overlaid in the overrulePIvars array. All piVars found in the unsetPIvars array won't be preserved.

Same as fe_linkTP_unsetPIvars, but it returns only the URL.

$overrulePIvars

array()

$unsetPIvars

array()

$cache

0

$clearAnyway

0

$altPageId

0

Builds parameters for a typoLink.¶

This method is used to build the 'additionalParams' TypoScript option. Each parameter of the array will be formed as a piVar (prefixed with pObj->prefixId).

$params

array()

$keepPiVars

true

Init the FE-Admin script for frontend input.¶

This function adds all the configuration necessary to use fe_adminLib to the plugin configuration array.

$conf

$table

$pid

$feAdminConf

$create

1

$edit

0

$delete

0

$infomail

0

$fe_userOwnSelf

0

$fe_userEditSelf

0

$debug

0

$defaultCmd

'create'

$confKey

'fe_adminLib'

Creates an input.¶

This function creates an HTML input tag, ready for a usage with fe_adminLib.

$type

$name

$feAdminConf

$feAdminSection

$number

1

$params

array()

$defaultValue

0

$defaultChecked

0

$keepSentValues

1

$langPrefix

'pi_feadmin_'

$headerSeparation

'<br />'

Creates a text area.¶

This function creates an HTML <textarea> tag for use with the fe_adminLib script.

$name

$feAdminConf

$feAdminSection

$params

array()

$defaultValue

0

$keepSentValues

1

$langPrefix

'pi_feadmin_'

$headerSeparation

'<br />'

Creates a select.¶

This function creates an HTML select tag for use with the fe_adminLib script.

The $option parameter can be an array or a number. If it's an array, the options will get the keys as values, and the values as label. If it's a number, it will create x options (x representing that number). The values will be incremented from zero, and the labels taken from the locallang file, according to the standard Typo3 syntax (eg.: lang_prefix_fieldname.I.value).

$name

$feAdminConf

$feAdminSection

$options

$htmlspecialchars

1

$params

array()

$keepSentValues

1

$langPrefix

'pi_feadmin_'

$headerSeparation

'<br />'

Creates a select from a table.¶

This function creates an HTML select tag for use with the fe_adminLib script. Values and labels are taken from an external table.

$name

$feAdminConf

$feAdminSection

$table

$pidList

$labelField

$valueField

'uid'

$htmlspecialchars

1

$addWhere

''

$groupBy

''

$orderBy

''

$limit

''

$params

array()

$keepSentValues

1

$langPrefix

'pi_feadmin'

$headerSeparation

'<br />'

Returns a form element header.¶

This function creates the header of a form element for use with the fe_adminLib script. It also checks if the field is required in the plugin configuration array, and adds warning markers.

$name

$langPrefix

$headerSeparation

$requiredFieldList

false

$evalValues

array()

Build a login box.¶

This function constructs a standard Typo3 login box. All the setup is done by the function. You only have to specify the PID of the sysfolder where you store your website users records, and it will handle everything. If the user is already logged, it display a logout form.

$pid

$inputSize

30

$method

'POST'

$target

'_self'

$wrap

false

$layout

false

$langPrefix

'pi_loginbox_'

$permaLogin

false

$asTsArray

false

Build a search box.¶

This function constructs a standard Typo3 search box for use in plugins. The result is basically the same as tslib_piBase::pi_list_searchBox, but the output is valid XHTML, without tables.

$method

post

$nocache

true

$sword

'sword'

$pointer

'pointer'

Build a browse box.¶

This function constructs a standard Typo3 browse box for use in plugins. The result is basically the same as tslib_piBase::pi_list_browseresults, but the output is valid XHTML, without tables.

$pointer

post

$count

true

$maxResults

'sword'

$maxPages

'pointer'

Includes the Prototype framework.¶

This function includes the Prototype JavaScript framework by adding a script tag to the TYPO3 page headers. This method can only be used in a frontend context.

Includes the Mootools framework.¶

This function includes the Mootools JavaScript framework by adding a script tag to the TYPO3 page headers. This method can only be used in a frontend context.

Includes the Prototype framework.¶

This function includes the Scriptaculous JavaScript framework by adding a script tag to the TYPO3 page headers. This method can only be used in a frontend context.

Includes the lightbox script.¶

This function includes the lightbox JavaScript by adding a script tag to the TYPO3 page headers. This method can only be used in a frontend context.

$includeCss

true

Includes the UFO script.¶

This function includes the UFO JavaScript script by adding a script tag to the TYPO3 page headers. This method can only be used in a frontend context.

Includes the SWFObject script.¶

This function includes the SWFObject JavaScript script by adding a script tag to the TYPO3 page headers. This method can only be used in a frontend context.

Includes a script from WebToolKit.¶

This function includes a JavaScript script from WebToolKit by adding a script tag to the TYPO3 page headers. This method can only be used in a frontend context. Available scripts are base64, crc32, md5, sha1, sha256, url and utf8.

$file

Functions for backend development.¶

All of those functions are only available in a backend context. They also all need the API class to be instantiated, as they will use the internal variable $pObj.

Do not try to use them out of a backend context, and without the API class instantiated.

Build action icons.¶

This function creates the icon(s) associated with an action to do on a record. Compatible with Typo3 skinning functions.

$actions

$table

$uid

Build a select menu representing the page tree.¶

This function creates a select menu containing the page tree from a specified page ID.

$name

$treeStartingPoint

0

$size

'1'

$multiple

false

$pageIcons

1

Build CSS styles for select menu items.¶

This function creates the CSS styles to correctly display a record icon inside an option tag of a select menu.

$table

$rec

$backPath

Init CSM.¶

This function initialize the Contenxt Sensitive Menu (CSM), in order to use it in a backend module.

Get CSM menu for a record.¶

This function creates an icon of the requested record with aContext Sensitive Menu (CSM).

$table

$rec

$backPath

$align

top

Includes the Prototype framework.¶

This function includes the Prototype JavaScript framework by adding a script tag to the TYPO3 page headers. This method can only be used in a backend context.

Includes the Mootools framework.¶

This function includes the Mootools JavaScript framework by adding a script tag to the TYPO3 page headers. This method can only be used in a backend context.

Includes the Prototype framework.¶

This function includes the Scriptaculous JavaScript framework by adding a script tag to the TYPO3 page headers. This method can only be used in a backend context.

Includes the lightbox script.¶

This function includes the lightbox JavaScript by adding a script tag to the TYPO3 page headers. This method can only be used in a backend context.

$includeCss

true

Includes the UFO script.¶

This function includes the UFO JavaScript script by adding a script tag to the TYPO3 page headers. This method can only be used in a backend context.

Includes the SWFObject script.¶

This function includes the SWFObject JavaScript script by adding a script tag to the TYPO3 page headers. This method can only be used in a backend context.

Includes a script from WebToolKit.¶

This function includes a JavaScript script from WebToolKit by adding a script tag to the TYPO3 page headers. This method can only be used in a backend context. Available scripts are base64, crc32, md5, sha1, sha256, url and utf8.

$file

Functions related to databases queries.¶

Those functions are available in any context, but they will need the AI class to be instantiated most of the time.

Export a database table to text format.¶

This function returns a database table contents as a formatted text variable. By default, it generates a tabulated text file.

SPECIAL NOTE: This function can be called without the API class instantiated.

$table

$fieldList

'*'

$whereClause

''

$groupBy

''

$orderBy

''

$limit

''

$sepField

9

$sepRow

10

$directOut

0

$directOutCharset

'iso-8859-1'

Export a database table to XML format.¶

This function returns a database table contents as an XML object.

SPECIAL NOTE: This function can be called without the API class instantiated.

$table

$fieldList

'*'

$whereClause

''

$groupBy

''

$orderBy

''

$limit

''

$uppercase

0

$xmlDeclaration

1

$xmlVersion

'1.0'

$xmlEncoding

'iso-8859-1'

$directOut

1

$ns

false

$nsPrefix

'ns'

1:
2:
3:
4:
5:
6:
7:
8:
9:
10:
11:
12:
13:
14:
15:
16:
17:
18:
19:
20:

<?xml version="1.0" encoding="iso-8859-1"?>
<!--
- Typo3 XML Export
-
- Generation Time: Thu, 25 Nov 2004 23:00:00 +0100
-
- Host: localhost
- Database: typo3_db
- Table: fe_users
-->
<typo3_db>
        <fe_users>
                <uid>1</uid>
                <username>admin</username>
        </fe_users>
        <fe_users>
                <uid>2</uid>
                <username>macmade</username>
        </fe_users>
<typo3_db>

1:
2:

// Export fe_users
$this->api->table2xml('fe_users','uid,username');

General purposes functions for miscellaneous development.¶

Those functions are available in any context. You also don't need the instantiate the API class to use them, as they don't need a parent object.

String format conversion.¶

This function converts a string with ISO-8859-1 characters encoded with UTF-8 to single-byte ISO-8859-1.

SPECIAL NOTE: This function can be called without the API class instantiated.

$content

Returns an age.¶

This function returns an age, calculated from a timestamp. By default, the function takes the current time as reference, but another timestamp can be specified. The function also returns by default the age in days, but it can also returns it in seconds, minutes or hours.

SPECIAL NOTE: This function can be called without the API class instantiated.

$tstamp

$currentTime

false

$ageType

false

Write tag parameters.¶

This function write, from an array, every given key, with it's value, as an HTML tag parameter.

SPECIAL NOTE: This function can be called without the API class instantiated.

$params

Check for valid variables.¶

This function checks for the type of multiples variables, passed in an array. It's used to check with one function call multiple variable which should be of the same type.

SPECIAL NOTE: This function can be called without the API class instantiated.

$vars

$type

'array'

Clean an array¶

This function process an array and removes all the keys given as second parameter. It can also keep only the given keys if the $inverse parameter is set.

SPECIAL NOTE: This function can be called without the API class instantiated.

$input

$keys

$inverse

0

Returns a base URL.¶

This function is used to get only the host part of an URL.

SPECIAL NOTE: This function can be called without the API class instantiated.

$url

$http

1

$trailingSlash

1

Create a vCard.¶

This function produces a vCard (.vcf format) from an array.

Here's an example input array:

array(
    'firstname' => string      // First name
    'name' => string                   // Last name
    'username'  => string      // Nick name
    'company'  => string       // Company
    'department'  => string    // Department
    'title' => string                  // Job title
    'www' => string                    // Home page
    'note' => string                   // Notes
    'birthday' => tstamp       // Birtday
    'email' => array(
            array(
                    'mail' => string   // Email address
                    'type' => string   // Type (WORK - HOME – Other)
            )
    )
    'phone' => array(
            array(
                    'number' => string // Number
                    'type' => string   // Type (WORK - HOME - CELL - MAIN - HOMEFAX - WORKFAX – Other)
            )
    )
    'messenger' => array(
            array(
                    'name' => string   // Account name
                    'service' => string        // Service (AIM - JABBER - MSN - YAHOO – ICQ)
                    'type' => string   // Type (WORK - HOME – Other)
            )
    )
    'address' => array(
            array(
                    'street' => string // Street
                    'city' => string   // City
                    'state' => string  // State
                    'zip' => string    // ZIP code
                    'country' => string        // Country
                    'type' => string   // Type (WORK - HOME – Other)
            )
    )
    'image' => string                  // Picture reference
    'iscompany' => boolean     // Define as company
)

$user

$version

'3.0'

$charset

false

Parse avCard (or a pack of vCards).¶

This function produis used to parse a vCard, or a pack of vCard, and to produce a multi-dimensionnal array with all the vCard informations. The array produced is exactly the same kind of array that must be passed to the div_vCardCreate function of this API. So the two functions are compatible.

If a vCard has an embed base65 encoded image, it's decoded, and a temporary image file is created in typo3temp/. The file reference is then included in the output array.

SPECIAL NOTE: This function can be called without the API class instantiated.

$file

Create an HTML list from a string.¶

This function produces an HTML list element (UL or OL) from a string, using a separator to get each list item.

SPECIAL NOTE: This function can be called without the API class instantiated.

$string

$sep

','

$htmlspecialchars

1

$listType

'ul'

$listParams

array()

$itemsParams

array()

Create an HTML list from an array.¶

This function produces an HTML list element (UL or OL) from an array.

SPECIAL NOTE: This function can be called without the API class instantiated.

$inputArray

$htmlspecialchars

1

$listType

'ul'

$listParams

array()

$itemsParams

array()

Output some content.¶

This function is used to output content with a specified type, as attachment for example. You can get a list of all the available type at the following address:

http://www.openmobilealliance.org/tech/omna/omna-wsp-content-type.htm

SPECIAL NOTE: This function can be called without the API class instantiated.

$out

$cType

$fName

$cDisp

'attachment'

$charset

'utf-8'

Convert XML data to an array.¶

This function is used to convert an XML data to a multi-dimensionnal array, representing the structure of the data.

This function is based on the Typo3 array2xml function, in t3lib_div. It basically does the same, but has a few more options, like the inclusion of the xml tags arguments in the output array. This function also has support for same multiple tag names inside the same XML element, which is not the case with the core Typo3 function. In that specific case, the array keys are suffixed with '-N', where N is a numeric value.

SPECIAL NOTE: This function can be called without the API class instantiated.

$data

$keepAttribs

1

$caseFolding

0

$skipWhite

0

$prefix

false

$numeric

'n'

$index

'index'

$type

'type'

$base64

'base64'

$php5defCharset

'iso-8859-1'

Convert an array to XML.¶

This function is used to convert a multi-dimensionnal array to XML code.

This is the reverse function of div_xml2array().

SPECIAL NOTE: This function can be called without the API class instantiated.

$input

$xmlRoot

'phpArray'

$prefix

''

$numeric

'item'

$numericAsAttribute

index

$addArrayAttribute

type

$xmlDeclaration

1

$encoding

'iso-8859-1'

$version

'1.0'

$standalone

'yes'

$doctype

false

$newLine

10

$indent

9

$level

0

Crops a string.¶

This function is used to crop a string to a specified number of characters. By default, it crops the string after an entire word, and not in the middle of a word. It also strips by default all HTML tags before cropping, to avoid display problems.

SPECIAL NOTE: This function can be called without the API class instantiated.

$str

$chars

$endString

'...'

$crop2space

1

$stripTags

1

Returns a timestamp.¶

This function returns a timestamp for a given year (XXXX), week number, and day number (0 is sunday, 6 is saturday).

Thanx to Nicolas Miroz (nmiroz@free.fr) for the informations about date computing.

SPECIAL NOTE: This function can be called without the API class instantiated.

$day

$week

$year

Ensure a number is in a specified range.¶

This function forces the specified number into the boundaries of a minimum and maximum number.

SPECIAL NOTE: This function can be called without the API class instantiated.

$number

$min

$max

$int