The main Application object that handles requests and response. More...

Public Member Functions
Request Context
Methods and Structures for getting information about the current request context.
&	getQuery ()
	Returns a reference to the current query object. This is very similar to the $_GET and $_REQUEST globals except this array has been filled in with missing values.
&	getQueryParam ($key)
	Returns a query parameter.
&	getResultSet ()
	Loads the current result set.
&	getRecord ()
	Gets the current record based on the current query.
	getRecordContext ($id=null)
	Returns the related record that forms a context for the specified record id. A context is provided so that we can tell if a record is being viewed through the lense of a related record. This can affect things like the permissions, bread-crumbs, and other navigation items. It allows us to tell where we are and where we came from.
	addRecordContext (Dataface_RelatedRecord $rec)
	Adds a related record to the current context. This provides a lense through which to view the destination records of this related record so that their permissions are evaluated as if they are part of the relationship.
	clearRecordContext ()
	Clears the current record context. The record context is a set of related records that are meant to be used as a lense through which to view any destination records of any related record in the set.
	recordLoaded ()
	Checks is the current record has been loaded yet.
&	getAction ()
	Gets the settings array for the current action as specified by the -action parameter of the current query.
	getSearchTarget (array $action=null)
	Gets the name of the action that should be used as a search target from the given action context. If $action is omitted, then the current action (specified by the -action query parameter) will be used as the current context.
Event Handling
Methods for dealing with the dispatch of events.
	fireEvent ($name, $params=null)
	Fires an event to all event listeners.
	registerEventListener ($name, $callback)
	Registers an event listener to respond to events of a certain type.
	unregisterEventListener ($name, $callback)
	Unregisters an event listener.
	getEventListeners ($name=null)
	Gets a list of the callbacks that are registered for a given event.
Delegate Class
Methods for obtaining and working with the delegate class.
&	getDelegate ()
	Returns a reference to the delegate object for this application. The delegate object can be used to define custom functionality for the application.
Permissions
Method wrappers for working with permissions.
	getPermissions ($params=array())
	Returns the permissions that are currently available to the user in the current context. If we are in browse mode then permissions are checked against the current record. Otherwise, permissions are checked against the table.
	checkPermission ($perm)
	Checks if a permission is granted in the current context.
Custom Pages
Methods for working with custom pages. These are seldom used and are not the recommended way to make actions in Xataface.
&	getCustomPages ()
	PHP files located in the 'pages' directory of the site are considered to be custom pages. Passing the GET parameter -action=custom_<pagename> will cause the Application controller to display the page <pagename>.php from the pages directory. This method just returns an array of full paths to the custom pages that are available in the 'pages' directory.
	getCustomPagePath ($name)
	Obtains the full path (read for inclusion) of the custom page with name $name.
	getCustomPageLabel ($name)
	Obtains the label for a custom page. The label is the same as the name except with capitalization of words and replacement of underscores with spaces.

Data Fields
const	EX_FAILED_TO_CREATE_SESSION_DIR = 5500
	$redirectHandler = null
	An object that implements a method named 'redirect' that is supposed to handle requests to redirect to a new page. This gives an opportunity to suppress redirects or handle them differently inline. This is helpful if you're loading Xataface from a cron script or another application and need to prevent redirects.
	$rawQuery
	$prefs
	User preferences matrix.

Languages
Methods for dealing with multiple languages.
	getLanguage ($langCode)
	Returns the language associated with a given language code.
	getLanguageCode ($locale)
	Returns the Xataface language code for a particular locale. E.g. zh_CN would return zh, while zh_TW would return zt.
	getAvailableLanguages ()
	Returns an array of all available languages in the application. This is derived from all languages listed in the [languages] section of the conf.ini file.

Configuration & Initialization
Methods and Data Structures for Storing and Accessing Configuration.
	$_conf
	A configuration array to store configuration information.
	db ()
	Returns MySQL connection resource.
	Dataface_Application ($conf=null)
	Constructor. Do not use this. getInstance() instead.
&	conf ()
	Returns the config array as loaded from the conf.ini file, except that it opens up the opportunity for the delegate class to load values into the config using its own conf() method.
	getMySQLMajorVersion ()
	Get the mysql major version number of MySQL. returns int.
	getPageTitle ()
	setPageTitle ($title)
	getSiteTitle ()
	Gets the site title.
static &	getInstance ($conf=null)
	Returns reference to the singleton instance of this class.

Session Handling
Methods and data structures for dealing with Session Handling and authentication.
	saveMessage ($str)
	Sets a message to be displayed as an info/alert the next time a page is rendered. This is handy if your action is performing some funcitons and then redirecting to a new page on complete - and you want the message to be displayed on the other page.
	enableSessions ()
	Sets the cookie that causes sessions to be enabled by default. In order to maximize performance Xataface will try not to start a session until it absolutely has to . This allows public sites to not rack up huge amounts of Session files unnecessarily.
	disableSessions ()
	Unsets the cookie that causes sessions to be enabled by default. Despite the name, this doesn't actually disable sessions. Sessions will still be enabled when they are needed, eg for login. This will just enable them always by default.
	sessionEnabled ()
	Checks if sessions are enabled by default.
	startSession ($conf=null)
	Starts a session if one does not already exist. If you are writing code that needs to use session data it is a good idea to explicitly call this before doing anything with the $_SESSION array. It is safe to call this multiple times.
&	getAuthenticationTool ()
	Obtains reference to the authentication tool.

Template & UI Interaction
Methods for customizing the output. This includes error messages, and inclusion of content in the head of the document.
	addHeadContent ($content)
	Adds some content meant to be inserted in the head of the application.
	getNavItem ($key, $label=null)
	Returns the nav item info for a key. This is a wrapper around the nav items defined in the [_tables] section of the conf.ini file.
	isNavItemSelected ($key)
	Checks whether the specified nav item is currently selected. This is used by the default implementation of getNavItem() and it an be used also in custom implementations. It can also be overridden by the application delegate class method of the same name.
	addError ($err)
	Adds an error to be displayed in the UI in the messages block.
	numErrors ()
	Returns the number of errors that are to be displayed to the user in the messages block.
	getErrors ()
	Returns an array of the errors that are set to be displayed to the user in the messages block.
	addMessage ($msg)
	Adds a message to be displayed in the messages block.
	getMessages ()
	Gets the messages that are to be displayed in the messages block. This will look in multiple sources for possible messages to display. It will include the following: $_SESSION['msg'] $app->messages $app->response['–msg'].
	clearMessages ()
	Clears all of the message to be displayed.
	numMessages ()
	Returns the number of messages to be displayed to the user.
static &	getResponse ()
	Returns the response array used for compiling response. The response may include messages that need to be displayed to the screen as an alert. Currently the response array only includes a single key: –msg.

Request Handling
Methods for handling the main requests. These methods are responsible for doing the heaving lifting of displaying a page.
	handleRequest ($disableCache=false)
	Handle a request. This method is the starting point for all Dataface application requests. It will delegate the request to the appropriate handler. The order of delegation is as follows: Uses the ActionTool to check permissions for the action. If permissions are not granted, dispatch the error handler. If permissions are granted then we continue down the delegation chain. If the current table's delegate class defines a handleRequest() method, then call that. If the current table's delegate class does not have a handleRequest() method or that method returns a PEAR_Error object with code E_DATAFACE_REQUEST_NOT_HANDLED, then check for a handler bearing the name of the action in one of the actions directories. Check the directories in the following order: a. <site url>="">/tables/.
	display ($main_content_only=false, $disableCache=false)
	Displays the Dataface application.

Utility Functions
Useful functions that are informed by the current context to provide useful functionality to the application as a whole.
	$_parseStringContext = array()
	parseString ($expression, $context=null)
	Evaluates a string expression replacing PHP variables with appropriate values in the current record.
	testCondition ($condition, $context=null)
	Tests an expression for a boolean result. This is primarly used by the condition directive of actions to be able to evaluate boolean expressions to determine if an action should be visible or not.
	url ($query, $useContext=true, $forceContext=false)
	Builds a link to somewhere in the application. This will maintain the existing query information.
	registerUrlFilter ($filter)
	Registers a filter that acts on URLs that are build with link builder. This allows modules to affect URLs as they are built to add, remove, or change parameters.
	filterUrl ($url)
	Filters a URL to add the current table and apply any filters that have been registered using registerUrlFilter()
	redirect ($url)
	Redirects the browser to a particular URL. Using this method rather than using a Location HTTP header directly is preferred as it allows modules to hook in to provide their own redirect handler to override the redirect.

Detailed Description

The main Application object that handles requests and response.

This is the one object that is presumed to always exist in a Dataface request.

Example 1

Usage in the index.php file or entry point of an application. In this context, the application is merely loaded and called upon to display the application.

<?php
require_once 'xataface/public-api.php';
df_init(__FILE__, '/dataface')->display();

In the above example we're exploiting the fact that df_init() returns the application object so we can call Dataface_Application::display() using method chaining.

Obtaining the Dataface_Application Object

Always use the Dataface_Application::getInstance() to obtain a reference to the Dataface_Application object. Never use the constructor directly.

@app = Dataface_Application::getInstance();

Getting the Current Query

The most common use of the application object is to get a reference to the current request parameters. Use Dataface_Application::getQuery() to get this as an associative array.

$app = Dataface_Application::getInstance();
$query =& $app->getQuery();
if ( $query['-action'] == 'foo' ){
    // Do some foo stuff
}

Getting the Current Record

Each HTTP request should resolve to context which includes a current record. The current record is decided by Xataface URL Conventions. It will either be decided by the -recordid parameter, or the current filter combined with the -cursor parameter (although there are some other possiblities.

$app = Dataface_Application::getInstance();
$record = $app->getRecord();
echo "The current record is ".$record->getTitle();

See Also: Dataface_Record

Author: Steve Hannah (shann.nosp@m.ah@s.nosp@m.fu.ca)

Since: 0.6

Definition at line 135 of file Application.php.

Member Function Documentation

addError ( $err )

Adds an error to be displayed in the UI in the messages block.

Parameters

PEAR_Error $err The error that is being added.

Returns: void

See Also: numErrors(); getErrors(); addMessage() To add string messages instead of Error objects.

Definition at line 1834 of file Application.php.

addHeadContent ( $content )

Adds some content meant to be inserted in the head of the application.

Parameters

string $content

Returns: void

Example: Adding A CSS stylesheet in the <head> of the page
$app->addHeadContent('<link rel="stylesheet" type="text/css" href="styles.css"/>');

Attention: If possible, you should try to use the Dataface_JavascriptTool class for adding javascripts and CSS stylesheets to your application's output.

Since: 1.0

See Also: Dataface_JavascriptTool; Dataface_CSSTool

Definition at line 1752 of file Application.php.

addMessage ( $msg )

Adds a message to be displayed in the messages block.

Parameters

string $msg The messag to be displayed.

Returns: void

See Also: addError()

Definition at line 1867 of file Application.php.

addRecordContext ( Dataface_RelatedRecord $rec )

Adds a related record to the current context. This provides a lense through which to view the destination records of this related record so that their permissions are evaluated as if they are part of the relationship.

Parameters

Dataface_RelatedRecord $rec The related record to add for context.

Returns: void

Since: 2.0

See Also: getRecordContext(); clearRecordContext()

Definition at line 1339 of file Application.php.

checkPermission ( $perm )

Checks if a permission is granted in the current context.

This is essentially a wrapper around the getPermissions() method that goes on to check for the existence of a permission.

Parameters

string $perm The name of a permission to check.

Returns: boolean True if the permission is granted.

See Also: getPermissions()

Definition at line 2983 of file Application.php.

clearMessages ( )

Clears all of the message to be displayed.

Returns: void

Definition at line 1900 of file Application.php.

clearRecordContext ( )

Clears the current record context. The record context is a set of related records that are meant to be used as a lense through which to view any destination records of any related record in the set.

Since: 2.0

Returns: void

See Also: getRecordContext(); addRecordContext()

Definition at line 1359 of file Application.php.

& conf ( )

Returns the config array as loaded from the conf.ini file, except that it opens up the opportunity for the delegate class to load values into the config using its own conf() method.

This is useful if an application wants to store config information in the database and still make it available to the application.

Returns: array

Definition at line 1055 of file Application.php.

Dataface_Application ( $conf = null )

Constructor. Do not use this. getInstance() instead.

The garbage collector threshold is the number of seconds that "garbage" can exist for before it is deleted. Examples of "garbage" include import tables (ie: temporary tables created as an intermediate point to importing data).

Definition at line 526 of file Application.php.

db ( )

Returns MySQL connection resource.

Definition at line 516 of file Application.php.

disableSessions ( )

Unsets the cookie that causes sessions to be enabled by default. Despite the name, this doesn't actually disable sessions. Sessions will still be enabled when they are needed, eg for login. This will just enable them always by default.

See Also: enableSessions(); sessionEnabled(); startSession()

Definition at line 1517 of file Application.php.

display	(	$main_content_only = `false`,
		$disableCache = `false`
	)

Displays the Dataface application.

Parameters

boolean	$main_content_only	Whether to only show the main content or to show the full page with header and footer. This parameter is not respected by many of the current templates and may be removed in later releases.
boolean	$disableCache	Whether to disable the output cache. It is enabled by default.

Flow Chart

Enlarge.

Definition at line 2362 of file Application.php.

enableSessions ( )

Sets the cookie that causes sessions to be enabled by default. In order to maximize performance Xataface will try not to start a session until it absolutely has to . This allows public sites to not rack up huge amounts of Session files unnecessarily.

See Also: disableSessions(); sessionsEnabled()

Definition at line 1504 of file Application.php.

filterUrl ( $url )

Filters a URL to add the current table and apply any filters that have been registered using registerUrlFilter()

Parameters

string $url The URL to be filtered.

Returns: string The filtered URL.

See Also: registerUrlFilter()

Definition at line 2834 of file Application.php.

fireEvent	(	$name,
		$params = `null`
	)

Fires an event to all event listeners.

Parameters

string	$name	The name of the event. e.g. afterInsert
array	$params	Array of parameters to pass to the event listener.

Returns: mixed Result of event. May be PEAR_Error if the event throws an error.

See Also: registerEventListener()

Definition at line 1957 of file Application.php.

& getAction ( )

Gets the settings array for the current action as specified by the -action parameter of the current query.

Returns: array Action parameters (or null if action doesn't exist).

Definition at line 1385 of file Application.php.

& getAuthenticationTool ( )

Obtains reference to the authentication tool.

Returns: Dataface_AuthenticationTool

Definition at line 1699 of file Application.php.

getAvailableLanguages ( )

Returns an array of all available languages in the application. This is derived from all languages listed in the [languages] section of the conf.ini file.

Returns: array Array of 2-digit xataface language codes.

Since: 1.0

Example conf.ini:: [languages]

en=English

fr=French

Example Inputs:: $app->getAvailableLanguages();

Example Outputs:: array(

en => English

fr => French

)

Definition at line 486 of file Application.php.

getCustomPageLabel ( $name )

Obtains the label for a custom page. The label is the same as the name except with capitalization of words and replacement of underscores with spaces.

Parameters

string $name The custom page name.

Returns: string The label for the custom page.

Definition at line 3104 of file Application.php.

getCustomPagePath ( $name )

Obtains the full path (read for inclusion) of the custom page with name $name.

Parameters

string $name The name of a custom page.

Returns: string The path to the custom page.

Definition at line 3091 of file Application.php.

& getCustomPages ( )

PHP files located in the 'pages' directory of the site are considered to be custom pages. Passing the GET parameter -action=custom_<pagename> will cause the Application controller to display the page <pagename>.php from the pages directory. This method just returns an array of full paths to the custom pages that are available in the 'pages' directory.

Returns: array Array of all of the pages in the pages directory that can be used as custom pages.

Definition at line 3064 of file Application.php.

& getDelegate ( )

Returns a reference to the delegate object for this application. The delegate object can be used to define custom functionality for the application.

Returns: ApplicationDelegateClass The application delegate class instance. Or null if none defined.

See Also: ApplicationDelegateClass

Definition at line 2905 of file Application.php.

getErrors ( )

Returns an array of the errors that are set to be displayed to the user in the messages block.

Returns: PEAR_Error[]

See Also: addError(); numErrors()

Definition at line 1855 of file Application.php.

getEventListeners ( $name = null )

Gets a list of the callbacks that are registered for a given event.

Parameters

$name The name of the event for which the callbacks are registered.

Returns: array Either an array of callbacks for the event. Or associative array of array of callbacks for all events with the key on the event name.

Definition at line 2002 of file Application.php.

static& getInstance ( $conf = null )

static

Returns reference to the singleton instance of this class.

Parameters

array $conf Optional configuration associative array that matches the stucture of the conf.ini file. This parameter will only be considered the first time this method is called in the request.

Returns: Dataface_Application

Since: 0.6

Example: $app = Dataface_Application::getInstance();

$app->display();

Definition at line 1029 of file Application.php.

getLanguage ( $langCode )

Returns the language associated with a given language code.

Parameters

string $langCode The 2-digit xataface language code. May be non-standard.

Returns: string The 2-digit ISO-639 language code corresponding to the Xataface language code.

Since: 1.0

Example

Given a languages section in your conf.ini file that resembles:

Inputs:: echo $app->getLanguage('zt');

echo "\n". $app->getLanguage('zh');

Outputs: zh

zh

Since: 1.2

Definition at line 423 of file Application.php.

getLanguageCode ( $locale )

Returns the Xataface language code for a particular locale. E.g. zh_CN would return zh, while zh_TW would return zt.

Parameters

string $locale A local in the form <lang>_<COUNTRY>. E.g. en_US or zh_CN

Returns: string The 2-digit xataface language code that handles the locale.

Inputs:: echo $app->getLanguageCode('zh_TW');

Outputs:: zh

Since: 1.2

Definition at line 449 of file Application.php.

getMessages ( )

Gets the messages that are to be displayed in the messages block. This will look in multiple sources for possible messages to display. It will include the following:

$_SESSION['msg']
$app->messages
$app->response['–msg'].

Returns: string[]

Definition at line 1882 of file Application.php.

getMySQLMajorVersion ( )

Get the mysql major version number of MySQL. returns int.

Definition at line 1087 of file Application.php.

getNavItem	(	$key,
		$label = `null`
	)

Returns the nav item info for a key. This is a wrapper around the nav items defined in the [_tables] section of the conf.ini file.

This can be overridden using the Application Delegate class method of the same name.

Parameters

string	$key	The key of the nav item. This would be the table name if using the traditional simple table nav items.
string	$label	The label for the nav item. This would be the table label if using the traditional simple table nav items.

Returns: array
href => The URL where the nav item is to link

label => The label for the nav item.

selected => boolean value indicating whether the item is currently selected.

See Also: isNavItemSelected()

Definition at line 1777 of file Application.php.

getPageTitle ( )

Definition at line 1095 of file Application.php.

getPermissions ( $params = array() )

Returns the permissions that are currently available to the user in the current context. If we are in browse mode then permissions are checked against the current record. Otherwise, permissions are checked against the table.

This will first try to get the permissions on the current record (as retrieved via getRecord()), and if no record is currently selected, it will get the permissions on the current table.

Parameters

array $params Parameters that can be passed to getPermissions to specify a particular field or relationship.

Returns: array Array of permissions / permissions matrix.

See Also: Dataface_Record::getPermissions(); Dataface_Table::getPermissions(); checkPermission()

Definition at line 2953 of file Application.php.

& getQuery ( )

Returns a reference to the current query object. This is very similar to the $_GET and $_REQUEST globals except this array has been filled in with missing values.

Returns: array Reference to current query object.

Example: $query =& $app->getQuery();

if ( $query['-table'] == 'dashboard' ){

// Always set the action for the dashboard to 'dashboard_action'

$query['-action'] = 'dashboard_action';

}

Definition at line 1166 of file Application.php.

& getQueryParam ( $key )

Returns a query parameter.

Parameters

string $key The query parameter to obtain. This should omit the leading '-' in the parameter name. E.g. Instead of '-action' this will be 'action'.

Returns: mixed The query parameter or null if not present.

Example: Input:
echo $app->getQueryParam('table');

$query = $app->getQuery();

echo $app['-table'];

Output:

my_table

Definition at line 1193 of file Application.php.

& getRecord ( )

Gets the current record based on the current query.

Returns: Dataface_Record

How Is the Record Selected?

It checks for the keys parameter and uses these keys as a filter.
It then checks for the -__keys__ parameter and uses these keys as a filter.
It then checks for the –__keys__ parameter and uses these keys as a filter.
It then checks for the –recordid parameter and returns the specified record.
It then checks for the -recordid parameter and returns the specified record.
It then loads the current result set and returns the record specified by the -cursor parameter (which is default 0).

The –no-query Parameter

Attention: This method may be affected by the –no-query parameter which tells Xataface that no query should be performed automatically during this request. This parameter is meant for performance reasons so save load on the database at the developer's request. If –no-query is specified, then this method will simply return null.

Example: Given the following query:
array(

user_id => 10

)

@code

We have @code

$rec = $app->getRecord(); // Record with user_id 10.

Given the query:

array(
    user_id => 10,
    -recordid => 'users?user_id=11'
)

We have

$rec = $app->getRecord() // Record with user_id 11

Definition at line 1259 of file Application.php.

getRecordContext ( $id = null )

Returns the related record that forms a context for the specified record id. A context is provided so that we can tell if a record is being viewed through the lense of a related record. This can affect things like the permissions, bread-crumbs, and other navigation items. It allows us to tell where we are and where we came from.

Parameters

string $id The record ID to check for context.

Returns: Dataface_RelatedRecord A related record that wraps the record in question.

Since: 2.0

Definition at line 1302 of file Application.php.

static& getResponse ( )

static

Returns the response array used for compiling response. The response may include messages that need to be displayed to the screen as an alert. Currently the response array only includes a single key: –msg.

Returns: array A response array with the following keys:
--msg => <string>

Definition at line 1926 of file Application.php.

& getResultSet ( )

Loads the current result set.

Returns: Dataface_QueryTool

Definition at line 1206 of file Application.php.

getSearchTarget ( array $action = null )

Gets the name of the action that should be used as a search target from the given action context. If $action is omitted, then the current action (specified by the -action query parameter) will be used as the current context.

This method is used by the find form and the search form to figure out which action should be used to show the search results when performing a find. Before this method, searches would always go to the list view, but as the list of modules grow, there are many other actions that might be appropriate for showing search results. Most notably, if you are viewing an action that "lists" a found set and you perform a search, you would expect to remain in the action/view from which you initiated the search. Previously they would have been kicked back to list view, which may not be desirable.

How Search Target Is Determined

If the DelegateClass::getSearchTarget() method is implemented, its result will be used.
If the ApplicationDelegateClass::getSearchTarget() method is implemented, its result will be used.
If the current action's search_target directive is set, then that value will be used.
If the default_search_target directive of the conf.ini file is set, then its value will be used.
list will be used if nothing else was specified.

Parameters

array $action The action definition associative array, or null. If null is provided, then the current action (as specified by $query['-action'] will be used).

Returns: string The name of an action to send for search results.

Since: 2.0

Definition at line 1429 of file Application.php.

getSiteTitle ( )

Gets the site title.

Returns: string The site title.

If $app->_conf['title'] is set then this will just return that. If not it will determine an appropriate title based on the current record and the current table.

Definition at line 1117 of file Application.php.

handleRequest ( $disableCache = false )

Handle a request. This method is the starting point for all Dataface application requests. It will delegate the request to the appropriate handler. The order of delegation is as follows:

Uses the ActionTool to check permissions for the action. If permissions are not granted, dispatch the error handler. If permissions are granted then we continue down the delegation chain.
If the current table's delegate class defines a handleRequest() method, then call that.
1. If the current table's delegate class does not have a handleRequest() method or that method returns a PEAR_Error object with code E_DATAFACE_REQUEST_NOT_HANDLED, then check for a handler bearing the name of the action in one of the actions directories. Check the directories in the following order: a. <site url>="">/tables/.

b. <site url>="">/actions b. <dataface url>="">/actions

If no handler can be found then use the default handler. The default handler can be quite powerful as it accepts the '-template' query parameter to use a specific template for display.

Parameters

boolean $disableCache Whether to disable the cache or not for this request.

See Also: ApplicationDelegateClass::beforeHandleRequest()

Definition at line 2052 of file Application.php.

isNavItemSelected ( $key )

Checks whether the specified nav item is currently selected. This is used by the default implementation of getNavItem() and it an be used also in custom implementations. It can also be overridden by the application delegate class method of the same name.

Parameters

string $key The nav item key. Traditionally the table name if using simple table navigation items.

Returns: boolean True if the item is meant to be selected.

See Also: getNavItem(); ApplicationDelegateClass::isNavItemSelected()

Definition at line 1811 of file Application.php.

numErrors ( )

Returns the number of errors that are to be displayed to the user in the messages block.

Returns: int

See Also: addError(); getErrors()

Definition at line 1846 of file Application.php.

numMessages ( )

Returns the number of messages to be displayed to the user.

Returns: int

Definition at line 1908 of file Application.php.

parseString	(	$expression,
		$context = `null`
	)

Evaluates a string expression replacing PHP variables with appropriate values in the current record.

Parameters

string	$expression	A string containing PHP variables that need to be evaluated.
Dataface_Record	$context	A Dataface_Record, Dataface_RelatedRecord object, or array whose values are treated as local variables when evaluating the expression.

Example expressions:: '${site_href}?-table=Profiles&ProfileID==${ProfileID}' – in the above example, ${site_href} would be replaced with the url (including script name) of the site, and ${ProfileID} would be replaced with the value of the ProfileID field in the current record.

Expression Context

The following variables are set up in the context and can be used in the expression:

Variable	Type	Description
$site_url	String	The Site URL (i.e. DATAFACE_SITE_URL). This includes the URL to the folder containing the application. It doesn't include the index.php file.
$site_href	String	The Site HREF (i.e. DATAFACE_SITE_HREF). This is the URL to the index.php file.
$dataface_url	String	The URL to the Xataface directory.
$table	String	The name of the current table.
$tableObj	Dataface_Table	Reference to the Dataface_Table object encapsulating the current table.
$query	array	The current query array. See getQuery()
$resultSet	Dataface_QueryTool	The current query result set. See getResultSet()
$record	Dataface_Record	The current record. This may be obtained from the 'record' key of the $context parameter. If omitted, then this will be the result of getRecord()
$relationship	Dataface_Relationship	The current relationship. This may be passed as the 'relationship' key of the $context parameter. If omitted then it is loaded from the current table and the $query['-relationship'] parameter.

Definition at line 2578 of file Application.php.

recordLoaded ( )

Checks is the current record has been loaded yet.

Returns: boolean

See Also: getRecord()

Definition at line 1374 of file Application.php.

redirect ( $url )

Redirects the browser to a particular URL. Using this method rather than using a Location HTTP header directly is preferred as it allows modules to hook in to provide their own redirect handler to override the redirect.

Parameters

string $url The URL to redirect to.

Returns: void

Redirect Handlers: You can assign your own redirect behavior by setting the redirect handler fo the application.

Definition at line 2872 of file Application.php.

registerEventListener	(	$name,
		$callback
	)

Registers an event listener to respond to events of a certain type.

Parameters

string	$name	The name of the event to register for. e.g. afterInsert
mixed	$callback	A standard PHP callback. Either a function name or an array of the form array(&$object,'method-name').

Returns: void.

See Also: fireEvent(); unregisterEventListener()

Definition at line 1976 of file Application.php.

registerUrlFilter ( $filter )

Registers a filter that acts on URLs that are build with link builder. This allows modules to affect URLs as they are built to add, remove, or change parameters.

Parameters

callback $filter A callback function that follow the PHP callback conventions and call be called with call_user_func. This should accept a string as a input and provide the modified string as output.

Returns: void

Example

A filter to add -foo=1 to the end of all URLs:

function addFoo($string){
    return $string.'&-foo=1';
}
$app = Dataface_Application::getInstance();
$app->registerUrlFilter('addFoo');
// Now any URL produced will include &-foo=1 at the end of it
$url = $app->url('');
    // Outputs index.php?-table=test&-action=list&-foo=1

See Also: filterUrl()

Definition at line 2820 of file Application.php.

saveMessage ( $str )

Sets a message to be displayed as an info/alert the next time a page is rendered. This is handy if your action is performing some funcitons and then redirecting to a new page on complete - and you want the message to be displayed on the other page.

Parameters

string $str The message that should be displayed.

Returns: void

Example: $app->saveMessage("The record was saved successfully.");

Definition at line 1491 of file Application.php.

sessionEnabled ( )

Checks if sessions are enabled by default.

Returns: boolean

See Also: enableSessions(); disableSessions(); startSession()

Definition at line 1529 of file Application.php.

setPageTitle ( $title )

Definition at line 1103 of file Application.php.

startSession ( $conf = null )

Starts a session if one does not already exist. If you are writing code that needs to use session data it is a good idea to explicitly call this before doing anything with the $_SESSION array. It is safe to call this multiple times.

Parameters

array $conf Optional configuration data that should follow the format of $app->_conf['_auth']

See Also: enableSessions(); disableSessions()

Definition at line 1544 of file Application.php.

testCondition	(	$condition,
		$context = `null`
	)

Tests an expression for a boolean result. This is primarly used by the condition directive of actions to be able to evaluate boolean expressions to determine if an action should be visible or not.

Parameters

string	$condition	A string that is executed in the sandbox context.
array	$context	Extra context information to include. This does not allow arbitrary variables to be added to the context, only specific ones.

Returns: boolean

Expression Context

The following variables are set up in the context and can be used in the expression:

Variable	Type	Description
$site_url	String	The Site URL (i.e. DATAFACE_SITE_URL). This includes the URL to the folder containing the application. It doesn't include the index.php file.
$site_href	String	The Site HREF (i.e. DATAFACE_SITE_HREF). This is the URL to the index.php file.
$dataface_url	String	The URL to the Xataface directory.
$table	String	The name of the current table.
$tableObj	Dataface_Table	Reference to the Dataface_Table object encapsulating the current table.
$query	array	The current query array. See getQuery()
$resultSet	Dataface_QueryTool	The current query result set. See getResultSet()
$record	Dataface_Record	The current record. This may be obtained from the 'record' key of the $context parameter. If omitted, then this will be the result of getRecord()
$relationship	Dataface_Relationship	The current relationship. This may be passed as the 'relationship' key of the $context parameter. If omitted then it is loaded from the current table and the $query['-relationship'] parameter.

See Also: Dataface_ActionTool; parseString()

Definition at line 2714 of file Application.php.

unregisterEventListener	(	$name,
		$callback
	)

Unregisters an event listener.

See Also: registerEventListener(); fireEvent()

Definition at line 1988 of file Application.php.

url	(	$query,
		$useContext = `true`,
		$forceContext = `false`
	)

Builds a link to somewhere in the application. This will maintain the existing query information.

Parameters

mixed	$query	Either a query string or a query array.
boolean	$useContext	Whether to use the existing context variables or not.
boolean	$forceContext	Whether to force context.

See Also: Dataface_LinkTool::buildLink()

Example Using Query Array: Given that the current page is located at http://example.com/path/to/app/index.php?-table=foo&-action=bar&username=ted
echo $app->url(array('-action'=>'browse'));

Output is:
/path/to/app/index.php?-table=foo&action=browse&username=ted

(Actually this isn't entirely correct... the entire context will also be included and Xataface calculates some default context parameters at the beginning of every request so the actually result will include parameters like -skip, -limit, -cursor, etc.. as well).

Definition at line 2776 of file Application.php.

Field Documentation

$_conf

A configuration array to store configuration information.

Definition at line 521 of file Application.php.

$_parseStringContext = array()

Definition at line 2510 of file Application.php.

$prefs

Initial value:

 array(
                'show_result_stats'=>1, 
                'show_jump_menu'=>1,    
                'show_result_controller'=>1,    
                'show_table_tabs'=>1,                   
                'show_actions_menu'=>1,                 
                'show_logo'=>1,                                 
                'show_tables_menu'=>1,                  
                'show_search'=>1,                               
                'show_record_actions'=>1,               
                'show_recent_records_menu'=>1,  
                'show_bread_crumbs' => 1,               
                'show_record_tabs' => 1,                
                'show_record_tree' => 1,                
                'list_view_scroll_horizontal'=>1, 
                'list_view_scroll_vertical'=>1  
        
        )

User preferences matrix.

Definition at line 274 of file Application.php.

$rawQuery

Definition at line 232 of file Application.php.

$redirectHandler = null

An object that implements a method named 'redirect' that is supposed to handle requests to redirect to a new page. This gives an opportunity to suppress redirects or handle them differently inline. This is helpful if you're loading Xataface from a cron script or another application and need to prevent redirects.

Example

$app = Dataface_Application::getInstance();
class MyHandler {
    function redirect($url){
        echo "A request to redirect to $url.";
    }
}
$app->redirectHandler = new MyHandler();
$app->display();

Note that if your handler does not either throw an exception or exit execution, then Xataface will throw a Dataface_Application_RedirectException which can be caught higher up the call stack.

Definition at line 165 of file Application.php.

const EX_FAILED_TO_CREATE_SESSION_DIR = 5500

Definition at line 137 of file Application.php.

The documentation for this class was generated from the following file:

Dataface/Application.php

Public Member Functions

Data Fields

Languages

Configuration & Initialization

Session Handling

Template & UI Interaction

Request Handling

Utility Functions

Detailed Description

Member Function Documentation

How Search Target Is Determined

Field Documentation

Example