index_page 1 index_page ==Documentation== [[toc]] ===Introductory=== * [[about|About Xataface]] * [http://xataface.com/documentation/tutorial/getting_started Getting Started Tutorial] * [[How to build a PHP MySQL Application with 4 lines of code]] * [[Troubleshooting]] ===Reference=== * [http://dataface.weblite.ca API Docs] * [[conf.ini file]] directives * [[fields.ini file]] directives * [[valuelists.ini file]] directives * [[relationships.ini file]] directives * [[Delegate class methods]] * [[Application Delegate Class]] * [[permissions.ini file]] directives * [[actions.ini file]] directives * [[preferences|User Preferences]] - options for customizing the application further via the getPreferences() method. * [[xataface templates|templates]] * '''[[URL Conventions]]''' - Learn how to use Xataface's URL conventions to form URLs that return exactly the result set that you want. * '''[[Roadmap]]''' - What is planned for the next releases of Xataface ===Cook Book=== * [[Customizing Theme Based on IP Address]] - An article on storing IP addresses in the database and showing users a different theme depending on which range of IP addresses they are connecting from. ===By Topic=== ====Installation==== * '''[http://xataface.com/documentation/tutorial/getting_started/installation Xataface Installation Instructions]''' - This document explains how to install Xataface on your system. It does not describe how to create an application with Xataface. * '''[http://xataface.com/documentation/tutorial/getting_started/first_application Creating your first App]''' - How to create an application using Xataface (from the Getting Started Tutorial) * '''[[about|About Xataface]]''' - Quick overview of Xataface. Includes a 6 step example of creating an application with Xataface. ====Configuration==== * '''[http://xataface.com/documentation/tutorial/getting_started/customizing Customizing field labels, descriptions, and widgets]''' - This document explains how to customize some basic aspects of your application's edit forms. (From the Getting Started tutorial). * '''[http://xataface.com/documentation/tutorial/getting_started/valuelists Using Valuelists]''' - How to use valuelists to set up options for your select lists and checkbox groups. * '''[http://xataface.com/documentation/how-to/list_tab Configuring and customizing the list tab]''' - This document explains how to customize the display of the list tab using INI files, templates, and delegate classes. ====Internationalization==== * '''[[Contribute to Xataface Translation Project]]''' - We need translators to help us keep the Xataface translations up to date. This page shows how you can help. * '''[http://xataface.com/documentation/tutorial/internationalization-with-dataface-0.6 Internationalization with Xataface]''' (tutorial) * '''[http://xataface.com/documentation/how-to/how-to-internationalize-your-application How to internationalize your application]''' (how to) - Xataface 0.6 contains a LanguageTool class that allows your applications to be presented in multiple languages * '''[http://xataface.com/documentation/how-to/use-translations How to use other translations]''' - Xataface 0.7 includes German and French translations. This document explains how to allow your application to use these and other translations, rather than the default English translation. * '''[http://xataface.com/documentation/how-to/unicode How to enable unicode support]''' - As of Xataface 0.6, unicode is fully supported so that your dataface application will work with any and multiple languages simultaneously. * '''[http://weblite.ca/svn/dataface/core/trunk/lang Download latest language files out of SVN]''' - If you want to make sure that you have the latest translations, you can download them from SVN and place them into your xataface lang directory. ====User Interface Customization==== * '''[[preferences|User Preferences]]''' - You can hide, show, enable, and disable features of the application selectively. * '''[http://xataface.com/documentation/tutorial/getting_started/changing-look-and-feel Changing the Look and Feel]''' - Change the way your application looks by adding custom headers, footers, and sections, and by overriding the default templates with your own custom templates. (From the Getting Started tutorial). * [[xataface templates|templates]] * '''[http://xataface.com/documentation/tutorial/customizing-the-dataface-look-and-feel Customizing the Xataface look and feel]''' tutorial * '''[[Customizing the look and feel of a row or a cell| Customizing the look and feel of an element in the list view]]''' - Personnalize the aspect of each part of your list according to its content. * '''[http://xataface.com/documentation/how-to/custom_javascripts How to include custom javascripts and stylesheets]''' - Use the custom_javascripts and custom_stylesheets blocks to include your own custom javascript and CSS files in your application. * '''[http://xataface.com/documentation/how-to/hide_search How to hide the search box]''' - The full-text search box that appears in the upper right can easily be removed. * '''[http://xataface.com/documentation/how-to/list_tab Configuring and customizing the list tab]''' - This document explains how to customize the display of the list tab using INI files, templates, and delegate classes. * '''[[How to Add Custom Sections to View Tab]]''' - The ''View'' tab in a Xataface application can be configured in many ways. This tutorial shows you how to add your own custom sections to the view tab. * '''[[Creating a Dashboard]]''' - Create a dashboard action for your users to so that they have a logical starting point in your application. * '''[[Grafted fields]]''' - Add a grafted field to your table for user convenience. You can use it also to be able to sort columns with relative tables content. * '''[[Clean the html for the export]]''' - Clean the HTML tags and entities for the export in CSV or XML. ====Using the API==== * '''[[Introduction to the Xataface API]]''' - A short introduction to the classes, methods, and functions available in the Xataface API. * '''[http://xataface.com/documentation/how-to/how-to-define-custom-serialization-for-fields How to define custom serialization for fields]''' ====Security==== * '''[[authentication]]''' - Overview of Xataface Authentication * '''[[registration form]]''' - Enabling User Registration in Xataface * '''[[permissions.ini file]]''' - Reference of the permissions.ini file directives. * '''[http://xataface.com/documentation/tutorial/getting_started/permissions Permissions]''' - Use sessions and delegate classes to define permissions at the record and field level. (From the Getting Started tutorial). * '''[[Cached permissions]]''' - Use cached perms for complex queries inside getPermissions() * '''[[Delegate_class_methods#toc5|Delegate class methods]]''' - Permissions-related functions * '''[[Relationship Permissions]]''' - Guide to permissions on related records. * '''[http://xataface.com/documentation/how-to/disallow_tables How to disallow access to tables]''' * '''[[site_with_backoffice]]''' - A site with a backoffice without obligation to log in * '''[http://xataface.com/documentation/how-to/security_filters Security Filters]''' - Use security filters to block users from seeing certain records. * '''[[How to granulate permissions on each field]]''' - Decide for each field who can edit, read... ** '''[[no_access_text]]''' - Replace the default NO ACCESS permission text with another text. * '''[[LDAP or Active Directory]]''' - How to authenticate users with LDAP or Active Directory... ====Performance==== * '''[http://xataface.blogspot.com/2009/06/using-query-caching-in-xataface.html Using Query Caching]''' - Query caching can drastically improve performance of busy applications with large databases. This article explains how to enable this caching in your Xataface application. * '''[[_output_cache]]''' - Xataface does quite a bit of heavy lifting on each page request. If your application is getting a lot of traffic that is slowing your server down, you may want to look at enabling the Xataface output cache. ====Modules==== * [[modules]] - Available Xataface Modules. This includes such things as CAPTCHA validation, editable javascript grids, and more. * [[Module Developers Guide]] - A guide / Tutorial on how to develop your own Xataface modules. ====Preferences==== ====Relationships==== * '''[http://xataface.com/documentation/tutorial/getting_started/relationships Relationships]''' - Xataface allows you to define relationships between tables using the relationships.ini file. (From the Getting Started Tutorial) * '''[http://xataface.com/documentation/how-to/how-to-assign-order-to-related-records How to assign order to related records]''' - Sometimes it is desirable for the records in a relationship to take on a particular default order. Dataface 0.6 makes this easy if you follow a few conventions. * '''[[Drag and Drop Reordering of Relationships]]''' - A more in-depth tutorial about adding ordering to relationships. * '''[[relationships.ini file]] reference * '''[[Relationship Permissions]] ====Forms==== * '''[http://xataface.com/documentation/how-to/DisableEnterKeyInFields How to disable the enter key in forms]''' * '''[http://xataface.com/documentation/tutorial/getting_started/customizing Customizing field labels, descriptions, and widgets]''' - This document explains how to customize some basic aspects of your application's edit forms. (From the Getting Started tutorial). * '''[http://xataface.com/documentation/tutorial/getting_started/valuelists Using Valuelists]''' - How to use valuelists to set up options for your select lists and checkbox groups. (From the Getting Started tutorial) * '''[http://xataface.com/documentation/tutorial/getting_started/validation Form Validation]''' - Xataface allows you to add validation rules to fields using the fields.ini file. (From the Getting Started tutorial). * '''[http://xataface.com/documentation/how-to/how-to-handle-file-uploads How to handle file uploads]''' - Xataface allows you to store file uploads in BLOB fields or on the file system. * '''[http://xataface.com/documentation/how-to/custom_validation How to add custom validation with delegate classes]''' - If the standard validators (e.g., required, email, regex, etc..) don't quite cut it for your validation rules, Xataface allows you to define custom validation methods in the delegate class. * '''[http://xataface.com/documentation/how-to/regex_validation Validating with regular expressions]''' - How to validate input into a field using regular expressions. * '''[[Dynamic select boxes]]''' - How to create two dynamic javascript select boxes from the valuelists. ====Importing==== * '''[http://xataface.com/documentation/how-to/import_filters Import Filters]''' - It is common to need to import records en masse into a database. This is what import filters are for. (Since 0.7). ====Actions==== * '''[http://xataface.com/documentation/tutorial/getting_started/dataface_actions Actions I: The Basics]''' - Web Lite's actions framework allows you to customize existing actions (e.g. new, edit, find) and create your own new actions. (From the Getting Started Tutorial). * '''[http://xataface.com/documentation/how-to/after_action_triggers Adding triggers to actions]''' - Xataface 0.6.1 adds some triggers to actions so that the developer can define custom functionality to be performed after an action has successfullly taken place. * '''[[Calendar Action]]''' - Using the built-in calendar action to add a full-fledged event calendar to your application. * '''[[Creating a Dashboard]]''' - Create a dashboard action for your users to so that they have a logical starting point in your application. * '''[[Selected Records Actions]]''' - Create custom actions that are performed on records that have been selected in the list tab. * '''[[Creating Printable Reports]]''' - Create a custom printable report using a custom action. * '''[[Using RecordGrid]]''' - Using Dataface_RecordGrid to print data in tabular form. ====History==== * '''[http://xataface.com/documentation/how-to/history-howto How to activate history logging]''' - Xataface 0.6.9 comes with support for managing the history of your records. This how-to shows you how to enable and use this feature. ====RSS Feeds==== * '''[[Introduction to RSS Feeds in Xataface]]''' - Xataface provides RSS feeds to any found set in your application. This tutorial shows how it works and how you can configure these feeds to get your desired results. ====Event Calendar==== * '''[[Calendar Action]]''' - Introduction to the Xataface calendar action which can be used to convert your application into a full-fledged event calendar. en 0 testpage2 2 testpage2 Another test page [[testpage]] en 0 fields.ini_file 3 fields.ini_file ==fields.ini File Reference== [[toc]] ===Overview=== The fields.ini file is a configuration file which is associated with a single table of a database application. It provides metadata about the table's fields to help Xataface dictate how they should be included in the application. This includes metadata such as * [[widget:type|Widget type]] - To specify the type of widget that should be used to edit content in the field (e.g. text, select, checkbox). * [[widget:label|Label]] - The labels that can be used in column headers and on forms. * [[widget:description|Help text]] - for forms to inform the user how data should be entered. * [[group|Field Groupings]] * [[widget:atts|widget:atts]] - To use javascripts in event handlers * and more Although a table doesn't need to have an associated fields.ini file in order for the application to work, each table can have one; and it is always located in the [[table configuration directory]]. For example, the fields.ini file for the [[people]] table would be located at [[Site Root]]/tables/people/fields.ini file. ===Syntax=== The fields.ini file uses [[standard INI syntax]] (just like the php.ini file), where each section corresponds to a column in the table. For example, consider a table "people" with columns "first_name", "last_name", and "age". The fields.ini file for the people table could then contain sections for each of its columns as follows: <code> [first_name] [last_name] [age] </code> In this example the sections are empty (i.e. they have no directives, but we could easily add some directives: <code> [first_name] widget:description="Please enter your first name" widget:label="Given Name" ...etc... </code> Here we have told Xataface that the first name field should include some help text (using the [[widget:description]] directive) on its edit form. ===Example fields.ini file=== <code> ;; Global directives applied to every field (requires Xataface 1.2.6) [__global__] visibility:list=hidden [isbn] widget:label = ISBN visibility:list=visible [copyright_year] widget:label = "Year" widget:atts:size=4 visibility:list=visible [categories] widget:type=checkbox vocabulary = book_categories [media] widget:type=checkbox vocabulary = book_media [borrower_id] widget:type=select vocabulary=users [due_date] widget:description = "The date that the book is due to be returned to the library" visibility:list=visible [cover_art_url_small] visibility:browse=hidden [cover_art_url_medium] ;visibility:browse=hidden [cover_art_url_large] visibility:browse=hidden visibility:find=hidden [amazon_description] widget:label = Description [amazon_reviews] [amazon_url] [amazon_refresh_timestamp] widget:type=static [date_created] timestamp=insert widget:type = static [date_modified] timestamp=update widget:type=static [created_by] widget:type=static [modified_by] widget:type=static [notes] </code> This is an example from the [http://apps.weblite.ca/index.php?-action=view&-table=packages&package_id=%3D2 Library DB] application for the books table. ===Field Directives=== The following directives may be added to a field's section of the fields.ini file to customize the field's behavior. Some directives are not applicable to all fields. {| class="listing listing2" |- ! Name ! Description ! Version |- | [[column:label]] | Specifies a custom label to use in list view for the column. If this is not specified, then the value of [[widget:label]] will be used. | 1.3 |- | [[column:legend]] | Adds a small amount of help text to the column header for this field in list view. Default is blank. E.g. <nowiki><br/><img src="http://media.weblite.ca/files/photos/Screen%20shot%202011-02-08%20at%205.05.55%20PM.png?max_width=640"/><br/></nowiki>In this photo it shows the text "*Paper Uploaded" set as the [[column:legend]] for "field 1". | 1.3 |- | [[date_format]] | Specifies how the field should be formatted when displayed. Takes same parameters as PHP [http://php.net/strftime strftime] function. | 2.0 |- | [[display]] | Specifies the layout of the field on the edit form. Most fields have an implicit value of "inline" meaning the widget and its label appear on the same line. Textareas and htmlareas have an implicit value of "block" meaning that the label and widget appear in separate rows (label above the widget). You can set this value explicitly also to override the layout of a field. | 0.8 |- | [[display_format]] | A pattern that can be used to define the display format of the field. This takes the same parameters as the PHP [http://php.net/sprintf sprintf] function. | 2.0 |- | [[encryption]] | Primarily used with password fields, indicates the type of encryption that should be used to save the field. Supports "md5", "sha1", "encrypt", and "password". | 0.6 |- | event.date | For use by the [[Calendar Action]]. Indicates that the field stores the date of the record when interpreted as an event. Possible values "0" or "1". | 1.0 |- | event.start | For use by the [[Calendar Action]]. Indicates that the field stores the start time of the record when interpreted as an event. Possible values "0" or "1". | 1.0 |- | event.end | For use by the [[Calendar Action]]. Indicates that the field stores the end time of the record when interpreted as an event. Possible values "0" or "1". | 1.0 |- | event.location | For use by the [[Calendar Action]]. Indicates that the field stores the location of a record when interpreted as an event. Possible values "0" or "1". | 1.0 |- | [[filter]] | Boolean value (0 or 1) indicating whether this field should be [[filterable]] in [[list view]]. | 0.8 |- | [[frozen_description]] | The field description shown when the widget is frozen (i.e. uneditable). If this is not specified, no field description is shown in this case. | 1.2 |- | [[group]] | The name of the field group that this field belongs to. Fields with the same "group" value will be rendered in the same field group on the form. | 0.5 |- | [[Key]] | If you are using a View for the table you need to explicitly mark the fields that comprise the primary key. E.g. Key=PRI | 0.6 |- | [[label_link]] | An optional URL for the field label to link to. This would usually be some "help" page that explains what the field is for. The link will be a link in both the view and edit tabs. | 1.1.3 |- | [[ignore]] | Boolean value (0 or 1) indicating whether this field should be ignored on the edit form. This is handy if the field is going to be constantly updated in the background (via a cron job perhaps) and you don't want the edit form to interfere. | 1.0 |- | [[logo]] | Boolean value (0 or 1) to indicate if this field should be treated as a logo field. Logo fields are displayed in the upper left of the [[view tab]] for a record, and are assumed to contain an image. If no logo field is explicitly specified, Xataface will make a best guess as to which field should be used. | 0.7 |- | [[money_format]] | For fields containing monetary amounts, this specifies the format. Takes same parameters as PHP [http://php.net/money_format money_format] function. | 2.0 |- | [[noLinkFromListView]] | Boolean value (0 or 1) to indicate if this field should be linked when in list view (or in a related list). Default value is 0 to indicate that the field IS linked. It is common to use this directive when using a custom xxx__renderCell() method that contains its own links. | 1.1 |- | [[not_findable]] | A flag to indicate that this field can not be used as part of a query. This is helpful if you want a field to remain completely confidential to prevent people from finding records based on the value of this field. This flag is even necessary if the permissions for the field don't permit viewing the value of the field. | 1.1 |- | [[number_format]] | For numeric fields, this indicates the number of decimal places to display when displaying this field. E.g. 2 | 2.0 |- | [[order]] | The order of the field when laid out on forms and lists. Can contain any floating point number or integer (e.g. 0, 10, -10, 235.4) | 0.6 |- | [[relationship]] | Used only with complex fields that involve editing related records (e.g. [[grid]]). This is the name of the relationship that the field should be edited. | 0.8 |- | [[repeat]] | Boolean value (0 or 1) used in conjunction with a select widget to indicate whether to enable a multi-select. | ? |- | [[section]] | The name of the section that this field should belong to in the [[view tab]]. | 0.7 |- | [[secure]] | A boolean flag for use with [[container fields]] to indicate that it should use secure URLs for the file downloads (i.e. it will obey the application permissions). Without this directives, uploaded files are served directly by apache and don't obey the Xataface permissions defined per record. | 1.3 |- | [[struct]] | A boolean (0 or 1) value indicating whether this field is considered a structure. A value of 1 indicates that this field is a structure and should not be truncated under any circumstances. Normally fields are truncated at 255 chars in list view. This is useful if the field contains XML or other structured data so that attempts to truncate it would destroy integrity. | 1.1.2 |- | [[tab]] | If tabbed forms are enabled, then this specifies the name of the tab that this field belongs to on the edit form. | 0.8 |- | [[timestamp]] | Indicates when a timestamp should be set in the field (only applicable for date and time fields). Possible values are "insert" and "update" | 0.7 |} {| class="listing listing2" |- ! Name ! Description ! Version |- | [[title]] | Boolean value (0 or 1) indicating whether this field should be treated as a title field. | 0.7 |- | [[transient]] | Boolean value (0 or 1) indicating whether this field is a transient field or not. A transient field is a field that is defined in the fields.ini file but not in the database. Hence the values that are input into this field on the edit form are not saved to the database. | 0.8 |- | [[Type]] | The data type of the field (note the capital "T" as Xataface is case sensitive). This value is only overridden for [[container]] fields, however its value can be accessed programmatically for any field. | 0.5 |- | [[validators|validators:VALIDATOR_NAME]] | A prefix for a validation type on the current field. (Replace "VALIDATOR_NAME" with the name of the validator to be used. e.g. required). There are many validators available to be used. | 0.5 |- | [[validators:VALIDATOR_NAME:message]] | The message the should be displayed if the form fails to validator due to the "VALIDATION_NAME" validation rule. | 0.5 |- | [[viewgroup]] | The name of the field grouping that this field will belong to in the view tab. If this is not present, then it will be grouped according to the [[group]] directive. | 1.0 |- | [[visibility:browse]] | Indicates whether the field should be visible in browse mode (i.e. in the "view" tab). Possible values are "visible" and "hidden". | 0.6 |- | [[visibility:csv]] | Indicates whether the field should be included in CSV exports. Possible values are "visible" and "hidden". (1.0 beta 4) | 1.0b4 |- | [[visibility:find]] | Indicates whether the field should be visible in find mode. Possible values are "visible" and "hidden" | 1.0 |- | [[visibility:list]] | Indicates whether the field should be visible in list view. Possible values are "visible" and "hidden". | 0.6 |- | [[visibility:update]] | Indicates whether the field should be included in update and copy/replace forms. Possible values are "visible" and "hidden". | 1.3 |- | [[vocabulary]] | The [[valuelist]] that should be used as the options to select. This is only applicable for fields that have options to select like a select list or a checkbox group. | 0.5 |- | [[widget:atts]] | A namespace for attributes that should be added to the HTML widget. This allows you to specify things like javascript events, styles, widget size, etc.. | 0.5 |- | [[widget:columns]] | For checkbox groups, this specifies the number of columns to use for laying out the checkboxes. | 1.0 |- | [[widget:description]] | Help text to give the user a hint about how to edit the field's content. | 0.1 |- | [[widget:editor]] | The type of HTML editor that should be used. This is used only when [[widget:type]] is set to [[widget:type htmlarea|htmlarea]] Acceptable values include: * [http://www.fckeditor.net/ fckeditor] (default) * [http://tinymce.moxiecode.com/ tinymce] (version 0.6 or higher) * [http://www.nicedit.com/ nicedit] (version 1.0 or higher) | all |- | [[widget:editvalues]] | Used with select lists to allow users to add values to the select list. E.g. widget:editvalues=1 | 0.8 |- | widget:focus | Sets default focus. 0 or 1. (Javascript focus in a form) | 0.6 |- | [[widget:label]] | The label that should be used for the current field on edit forms, column headings, and other relevant locations. | 0.1 |- | [[widget:question]] | Text displayed just before the widget. This is almost the same as [[widget:description]] except that this text is guaranteed to be displayed before the widget, whereas [[widget:description]] may be displayed below or beside the widget. | 0.1 |- | [[widget:type]] | The type of widget that should be used (e.g. checkbox, select, text, etc..) | 0.1 |- | [[xml]] | A flag for use with calculated fields (i.e. fields defined in the [[delegate class]] via the [[field__fieldname]] method) that will include the field in XML output produced by the [[export xml action]]. Default is 0, but setting this value to 1 wil cause the field to be included. | 1.2.7 |} ===Applying Directives to All fields (__global__)=== Xataface 1.2.6 includes support for a [[__global__]] section that allows you to specify directives that should be applied to all fields. These directives can be overridden on a field by field basis. The [[__global__]] section can take all the same directives that a normal field section takes. ===widget:atts:class Values=== The widget:atts:class directive allows you to assign a CSS class to a field's widget. There are certain CSS classes that have meaning to Xataface and will cause additional functionality to automatically be added to the field. These built-in classes are listed below: {| class="listing listing2" |- ! Name ! Description ! Version |- | [[passwordTwice]] | Applicable only to password fields. If you set widget:atts:class=passwordTwice, then this will convert the password field into two fields whereby both fields need to match in order for submission to continue on the edit form. This operates as a password verification field." | 1.3rc2 |} ===Global Directives=== The following directives can be added to the beginning of the fields.ini file (before any field sections) to customize field groups and the table as a whole. {| class="listing listing2" |- ! Name ! Description ! Version |- | [[__dependencies__]] | A comma-delimited list of tables that this table is dependent upon for caching purposes. E.g. if any table in this list is modified, then the query cache is cleared for queries on this table. See this [http://xataface.blogspot.com/2009/06/using-query-caching-in-xataface.html blog article] for more information about query caching. | 1.2 |- | [[__isa__]] | The name of the parent table of the current table. This directive allows you to have a heirarchical structure amongst the tables in your application. | 0.8 |- | [[__source_tables__]] | A comma-delimited list of tables that this table/view is derived from. This is used with the query caching feature and is necessary to use this directive if the table is actually a view. If this directive is not set, then any queries involving this view will not use the query cache because Xataface would have no way to discern the update time of the view. See this [http://xataface.blogspot.com/2009/06/using-query-caching-in-xataface.html blog article] for more information about query caching. | 1.2 |- | [[__sql__]] | Defines a custom select query to override the default select query for the current table. (The default select query is generally "select * from tablename"). | 0.7 |- | [[__prefs__]] | Sets preferences for this table and its records. | 1.0b4 |} ===Field Groups=== The [[group]] directive allows you to group multiple fields together so that they will be rendered in the same field group on forms. You can also configure these groups as a whole by defining a section named "[fieldgroup:GROUPNAME]" (where GROUPNAME is the name of the field group, corresponding to the [[group]] directive values for the fields) in the fields.ini file. This section provides a few basic directives to customize some aspects of the field group: * label * order * description * template * more... The most common use of these sections is to customize the label or order of groups, especially when there are multiple field groups in the table. For example, suppose we have a table "people" with fields "first_name", "last_name", "phone", "fax", "email", "address", "city", and "country". Suppose these fields are grouped as follows: * "first_name" and "last_name" * "phone", "fax", and "email" * "address", "city", and "country" so that the fields.ini file looks like: <code> [first_name] group=name [last_name] group=last_name [phone] group=contact [fax] group=contact [email] group=contact [address] group=address [city] group=address [country] group=address </code> By default, the "name" group will appear first in the form, followed by "contact" and "address". If we want to place "address" first we could add the following section to our fields.ini file: <code> [fieldgroup:address] order=-1 </code> Since the default order value is 0 on other groups, setting the "order" parameter to -1 will place the "address" group before all others. ====Field Group Directives==== The following directives are applicable in a fieldgroup section: {| class="listing listing2" |- ! name ! description ! version |- | [[fieldgroup order|order]] | Specifies the order of the group with respect to other groups on the form. Accepts any numerical value (e.g. 0, 1, -1, 25.43), with lower values appearing first. Default value is 0. | 0.6 |- | [[fieldgroup label|label]] | Specifies the label that should be used for the field group. | 0.6 |- | [[label_link]] | Specifies a URL that the field group label should link to. | 1.1.3 |- | [[fieldgroup template|template]] | The path to a custom template that should be used to render the fields of the field group. | 1.0 |- | [[fieldgroup collapsed|collapsed]] | Boolean value (0 or 1) indicating whether the field group should be collapsed by default (user can expand it). | 1.0 |} fields.ini directives en 0 widget:type 4 widget:type ==widget:type Directive Reference== The widget:type directive in the [[fields.ini file]] specifies the type of widget that should be used to edit a particular field in HTML forms. Xataface uses [http://pear.php.net/package/HTML_QuickForm/ HTML_QuickForm] for its form generation so theoretically any widget supported by HTML_QuickForm should work with Xataface. ===Available Widget Types=== {| class="listing listing2" |- ! Name ! Description ! Version |- | [[advmultiselect]] | Two select lists with add/remove buttons. Selected items appear in the right select list. Options may be selected from the left select list. | 1.0 |- | [[autocomplete]] | An autocomplete. text field. This is not to be confused with the [[yui_autocomplete]] widget. The main difference is that this widget does not provide a drop-down list of possibilities, it just tries to complete what the user is typing inside the text field based on a valuelist. | all |- | [[calendar]] | A DHTML pop-up calendar to select the date. [[Image:http://media.weblite.ca/files/photos/calendar_widget.png?max_width=400]] | 0.5.3 |- | [[checkbox]] | A checkbox or checkbox group. Example 1: Checkbox as boolean on Tinyint field. [[Image:http://media.weblite.ca/files/photos/checkbox_widget.png?max_width=400]] Example 2: Checkbox group to allow multiple selections. [[Image:http://media.weblite.ca/files/photos/checkbox-group_widget.png?max_width=500]] | all |- | [[date]] | Select lists for month, year, day, hour, etc... | all |- | [[file]] | A file widget (default type for [[container]] fields and [[blob]] fields. [[Image:http://media.weblite.ca/files/photos/file_widget.png?max_width=400]] | all |- | [[grid]] | A grid widget for editing multiple rows of related records inside the edit form. Supports adding/removing/reordering. As of version 1.2.5, file uploads are not supported in the grid widget. [[Image: http://media.weblite.ca/files/photos/grid_widget.png?max_width=500]] | 1.0 |- | [[group]] | A compound widget for editing multiple fields but storing the data in a single XML field. [[Image:http://media.weblite.ca/files/photos/group_widget.png?max_width=400]] | all |- | [[hidden]] | A hidden field | all |- | [[htmlarea]] | A WYSIWYG (What you see is what you get) HTML editor. This defaults to [http://www.fckeditor.net/ FCKeditor], but [http://tinymce.moxiecode.com/ TinyMCE] is also supported. [[Image:http://media.weblite.ca/files/photos/htmlarea_widget.png?max_width=400]] | all |- | [[lookup]] | A field that allows users to look-up a record from another table. THis is a good alternative to a select list. It doesn't use a vocabulary, so this is appropriate when vocabularies would be unpractical (for large vocabularies). You do, however need to specify the widget:table directive for the field so that the lookup knows from which table to load the records. [[Image:http://media.weblite.ca/files/photos/Picture%2023.png?max_width=640]] | 1.2 |- | [[password]] | A password field. [[Image:http://media.weblite.ca/files/photos/password_widget.png?max_width=400]] | all |- | [[select]] | A select list. Example 1: A single select. [[Image:http://media.weblite.ca/files/photos/select_widget.png?max_width=400]] Example 2: A multi-select. To use a multi-select, add repeat=1 to your fields.ini. [[Image:http://media.weblite.ca/files/photos/multi-select_widget.png?max_width=500]] | all |- | [[table]] | A compound widget for editing tabular data. This widget dictates the storage format as XML. [[Image:http://media.weblite.ca/files/photos/table_widget.png?max_width=400]] | all |- | [[text]] | A text field [[Image:http://media.weblite.ca/files/photos/text_widget.png?max_width=400]] | all |- | [[textarea]] | A text area (multi-line text field) [[Image:http://media.weblite.ca/files/photos/textarea_widget.png?max_width=400]] | all |- | [[time]] | A select list of times separated by a specified interval (default 30 minutes). | 0.7 |- | [[yui_autocomplete]] | An autocomplete widget ported from the [http://developer.yahoo.com/yui/autocomplete/ Yahoo UI Library]. [[Image:http://media.weblite.ca/files/photos/yui_autocomplete.png?max_width=400]] | 1.0 |} en 0 valuelists.ini_file 5 valuelists.ini_file ==valuelists.ini file Reference== [[toc]] The valuelists.ini file stores value lists that can be used as [[vocabulary|vocabularies]] for select lists, checkbox groups, and other widgets the provide the user with options to choose from. Each table can have an associated valuelists.ini file located in its [[table configuration directory]]. E.g. for a table named "people" its valuelists.ini file will be stored in "tables/people/valuelists.ini". In addition you can define an application-wide valuelists.ini file in the root of your application's directory, whose valuelists can be used by any table. ===Syntax=== The valuelists.ini file uses [[INI file syntax]], where a valuelist is defined by a single section of the INI file. E.g. <code> [colors] r=Red b=Blue g=Green </code> This example would define a single valuelist named "colors" with 3 values: r,g, and b (with corresponding labels "Red", "Green", and "Blue). The values (the left of the equals sign) are stored in the database, while the labels are rendered on screen for the user's convenience. ===Dynamic Valuelists=== It is often advantageous to load valuelists from the database rather than store them directly in the valuelists.ini file. The __sql__ directive allows you to specify an SQL query which selects up to 2 columns (the first is the id and the second, the label). E.g. <code> [colors] __sql__ = "select colorCode, colorName from colors" </code> ===Defining Valuelists in a Delegate Class=== If you require more flexibility with the definition of your valuelists than can be gained from the valuelists.ini file, you can define your valuelist using PHP inside a delegate class. Essentially you just create a method that returns an associative array, where the keys are the IDs that are stored in the database, and the values are the values that are visible in the select list. e.g. In either the application delegate class or a table delegate class: <code> function valuelist__colors(){ return array( 'r'=>'Red', 'g'=>'Green', 'b'=>'Blue' ); } </code> This method is called each time the valuelist is about to be used, so if your method performs any sort of intensive processing, it is a good idea to use a caching scheme so that it only runs the critical code once per request. For example, you could use a static variable as follows: <code> function valuelist__colors(){ static $colors = -1; if ( !is_array($colors) ){ $colors = array(); $res = mysql_query("select colorCode, colorName from colors", df_db()); if ( !$res ) throw new Exception(mysql_error(df_db())); while ($row = mysql_fetch_row($res) ) $colors[$row[0]] = $row[1]; } return $colors; } </code> In this example the database query is only executed once per request to load the $colors variable. The rest of the time it simply loads the cached value from $colors. valuelists, dynamic valuelists, programmatically defined valuelists en 0 actions.ini_file 6 actions.ini_file ==actions.ini file Reference== [[toc]] The actions.ini file stores information about the various [[action]]s that can be performed by your application. An action may be manifested in two ways: # As a web page # As a menu item And there is no reason why an action cannot serve in both capacities simultaneously. All menu items and functions that Xataface performs are defined in the Xataface actions.ini file (in the root of the Xataface installation dirctory). You can also create an actions.ini file in your application's root directory to override existing Xataface actions, or to create your own. If you want to modify an existing action instead of overriding it, you can use this syntax. <code> [browse > browse] label = Browse </code> The &gt; symbol simply means to inherit from the existing browse action. All the attributes are the same, and we just override the label to Browse (originally was Details) Additionally, for actions that pertain only to a single table, an actions.ini file may be placed in any [[table configuration directory]]. ===Syntax=== As with the [[fields.ini file]] and the [[valuelists.ini file]], the actions.ini file uses the simple [[INI file syntax]] to define its actions. Each action is defined in its own section, and can have a number of directives to specify the action's behavior. Here is a snippet from the Xataface actions.ini file to give you an idea: <code> ;; Show the details of the current record [browse] label = Details category = table_tabs url = "{$this->url('-action=view')}" accessKey = "b" mode = browse permission = view order=0 ;; Show a list of the records in the current found set [list] label = List category = table_tabs url = "{$this->url('-action=list')}" accessKey = "l" mode = list template = Dataface_List_View.html permission = list order=0.5 ;; Show a "Find Record Form" [find] label = Find category = table_tabs url = "{$this->url('-action=find')}" accessKey = "f" mode = find permission = find template = Dataface_Find_View.html order=0.75 </code> This snippet shows the definition of the browse, list, and find actions - three of the most central actions in a Xataface application. Notice how each action has its own section (according to [[INI file syntax]]) with a number of directives which specify how the action behaves. For instance, each action has a "category" value of "table_tabs", which tells Xataface to display the actions as part of the table tabs in the user interface. ===Directives=== {| class="listing listing2" |- ! Name ! Description ! Version |- | [[action allow_override|allow_override]] | An optional directive to indicate that this action can be overridden by more specific directives in another ini file. Currently there is only support for a value of "relationships.ini" indicating that the settings can be overridden in the relationships.ini file. In order for this to work, related=1 must also be set. | 1.3rc4 |- | [[action label|label]] | The label to display if the action is used as a menu item. | all |- | [[action category|category]] | The name of the action's category which can be used to group this action together with other similar actions to be used in a menu in the user interface. | all |- | [[action url|url]] | If the action appears as a menu item, this is the URL that the menu item points to. This may contain PHP expressions inside curly braces. | all |- | [[action accessKey|accessKey]] | The key code to automatically select this action if it is included as a menu item. I.e. ALT+accessKey calls the action. | all |- | [[action mode|mode]] | This indicates which tab of the table tabs (find, details, list, etc...) that this action should appear to be part of when the action is viewed as a web page. If this is left undefined, or it does not match any existing visible action in the table tabs, then no tab will appear to be selected. | all |- | [[action permission|permission]] | The name of a permission required to both see the action as part of a menu and to access the action as a web page. | all |- | [[action visible|visible]] | A boolean value indicating whether the action should be visible as a menu item. | all |- | [[action condition|condition]] | A boolean value or a PHP expression evaluating to a boolean value to indicate whether the action should be visible as a menu item. | all |- | [[action url_condition|url_condition]] | A PHP expression evaluating to a boolean value to indicate whether the URL directive should be evaluated. This basically checks to make sure that its OK to evaluate the "url" expression, just in case the current state of affairs would cause it to throw a fatal error. | all |- | [[action order|order]] | A numeric value indicating the order in which the action should be displayed as part of a menu. Low numbers result in higher placement in the menu. | all |- | [[action icon|icon]] | The path to an icon that should be used when the action appears as a menu item. | all |- | [[action template|template]] | The path to the template that should be used when the action is displayed as a web page. | all |- | [[action description|description]] | Mouseover text for the action (when displayed as a menu item). | all |} ===PHP Expression Context=== Notice that the [[action url|url]], [[action condition|condition]], and [[action url_condition|url_condition]] directives allow you to use a PHP expression for their values. In order for this to be helpful, you should know a little bit about the context and environment in which these expressions will be executed. All expressions are evaluated immediately prior to being rendered, so the same action can be displayed multiple times in the same page, but have very different resulting values for their [[action url|urls]] and [[action condition|conditions]]. These expressions are all executed within the context of the Dataface_Application::parseString() method, with the following variables loaded in the local symbol table (i.e. you can use the following variables in your expressions). {| class="listing listing2" |- ! Name ! Description ! Version |- | [[action context:site_url|$site_url]] | The URL to the current application's directory (not including "index.php") | all |- | $site_href | The URL to the current application including "index.php" | all |- | $dataface_url | The URL to the xataface installation directory. | all |- | $table | The name of the current table (i.e. the value of the "-table" request parameter" | all |- | $query | An associative array of the current query variables. | all |- | $app | A reference to the current Dataface_Application object. Alias of "$this" | all |- | $resultSet | A reference to the Dataface_QueryTool object for the current query. | all |- | [[action context:record|$record]] | A reference to the current Dataface_Record object. | all |- | [[action context:context|$context]] | An associative array of context variables that are passed to the action from the context in which the action is called. | all |} en 0 Delegate_class_methods 7 Delegate_class_methods ==Delegate Class Reference== [[toc]] A delegate class is a PHP class that complements a particular table with custom bahaviors. Basic table metadata can be supplied using the [[fields.ini file]], however some things are better customized using PHP. ===Delegate Class Location=== The delegate class should be located in a file named TABLENAME.php (where TABLENAME is the name of the table with which the delegate class is associated) inside the table's [[table configuration directory|configuration directory]]. E.g. given a table named "people", you would place the delegate class in the file "tables/people/people.php" ===Basic Delegate Class=== <code> <?php class tables_people {} ?> </code> ===Available Methods=== ====Table Settings==== {| class="listing listing2" ! Name ! Description ! Version |- | [[sql delegate method|__sql__]] | Defines the SQL query that can be used to fetch records of this table. This is identical to the [[fields.ini file]] [[__sql__]] directive, except that by defining it in the delegate class you have more flexibility. | 1.0 |} ====Permissions==== {| class="listing listing2" ! Name ! Description ! Version |- | [[getPermissions]] | Returns the permissions available for a given record. | 0.6 |- | getRoles | Returns the roles allowed for a given record. | 1.0 |- | [[__field__permissions]] | Returns the default permissions for a field of a given record. | 1.0 |- | __field__roles | Returns the default roles for a field of a given record. | 1.0 |- | [[fieldname__permissions]] | Returns the permissions that are allowed for the field "fieldname" on a given record. | 0.7 |- | fieldname__roles | Returns the roles that are allowed for the field "fieldname" on a given record. | 1.0 |- | rel_relationshipname__permissions | Returns the permissions pertaining to the relationship ''relationshipname'' on a given record. | 1.0 |- | rel_relationshipname__roles | Returns the role or roles pertaining to the relationship ''relationshipname'' on a given record. | 1.0 |} ====Triggers==== {| class="listing listing2" ! Name ! Description ! Version |- | [[after_action_edit]] | Trigger called after the edit action is succesfully completed. | 0.7 |- | [[after_action_new]] | Trigger called after the new action is successfully completed. | 0.7 |- | [[after_action_delete]] | Trigger called after the delete action is successfully completed. | 0.7 |- | [[afterAddExistingRelatedRecord]] | Trigger called after an existing related record is added. | 0.5 |- | [[aftereAddNewRelatedRecord]] | Trigger called after a new related record is added. | 0.5 |- | [[afterCopy]] | Trigger called after a record is copied. | 1.3 |- | [[afterDelete]] | Trigger called after a record is deleted. |0.5 |- | [[afterAddRelatedRecord]] | Trigger called after a related record of this table is added (either an existing record or a new record). | 0.5 |- | [[afterRemoveRelatedRecord]] | Trigger called after a related record is removed from a relationship. | 1.1.6 |- | [[afterInsert]] | Trigger called after a given record is inserted. | 0.5 |- | [[afterSave]] | Trigger called after a given record is saved (insert or update). | 0.5 |- | [[afterUpdate]] | Trigger called after a given record is updated. | 0.5 |- | [[beforeAddExistingRelatedRecord]] | Trigger called before an existing related record is added. | 0.5 |- | [[beforeAddNewRelatedRecord]] | Trigger called before a new related record is added. | 0.5 |- | [[beforeAddRelatedRecord]] | Trigger called before a related record of this table is added (either an existing record or a new record). | 0.5 |- | [[beforeCopy]] | Trigger called before a record is copied. | 1.3 |- | [[beforeDelete]] | Trigger called before a record is deleted. | 0.5 |- | [[beforeRemoveRelatedRecord]] | Trigger called before a related record is removed. | 1.1.6 |- | [[beforeSave]] | Trigger called before a given record is saved (insert or update). | 0.5 |- | [[beforeInsert]] | Trigger called before a given record is inserted. | 0.5 |- | [[beforeUpdate]] | Trigger called before a given record is updated. | 0.5 |- | [[init]] | This method is called the first time the table is loaded. It allows you to specify initialization details. | 0.8 |} ====Field Filters==== {| class="listing listing2" ! Name ! Description ! Version |- | fieldname__htmlValue | Returns the value of the field "fieldname" for a given record as HTML. | 0.5 |- | fieldname__display | Returns the value of the field "fieldname" appropriate for displaying. | 0.5 |- | [[fieldname__default]] | Returns the default value for the field ''fieldname''. New record forms will be prepopulated with this value. | 0.7 |- | [[fieldname__validate]] | Validates the input for the field ''fieldname''. | 0.6 |- | fieldname__parse | Parses the input value for the field ''fieldname''. This is called by Xataface inside the setValue() method or each record to normalize input values before they are stored in the object (not the database). | 0.5 |- | fieldname__toString | Converts the value of the field ''fieldname'' to a string. This string representation is used as the basis for most higher level data retrieval methods (such as serialize and display). This could be treated as an inverse to the [[fieldname__parse]] method. | 0.5 |- | fieldname__serialize | Converts a value of the field ''fieldname'' to be saved in the database. This should return a string representation of the value that is suitable for database storage. | 0.5 |- | fieldname__link | A link that appears beside the field ''fieldname'' on the edit form. | 0.6 |- | [[field__pushValue]] | Converts form input for field ''fieldname'' to be ready to store in a Dataface_Record. | 0.6 |- | [[field__pullValue]] | Converts a value for field ''fieldname'' in a Dataface_Record object to be ready to be inserted as a value on an HTML form. | 0.6 |- | [[field__fieldname]] | Effectively creates a calculated field named "fieldname" available on the given record. | 0.6 |- | [[no_access_text]] | Replace the default NO ACCESS permission text with another text. | 1.1.6 |- | [[no_access_link]] | Replace the default link of the NO ACCESS permission link with another link. | 1.1.6 |} ====Template Customization==== {| class="listing listing2" ! Name ! Description ! Version |- | [[block__blockname]] | Outputs content that is meant to override a slot or a block named "blockname". | 0.6 |} ====List Tab Customization==== {| class="listing listing2" ! Name ! Description ! Version |- | css__tableHeaderCellClass | Returns a custom CSS class for a table header cell (th tag) in the list view. Takes the name of a table column as a parameter. | 2.0alpha2 |- | css__tableRowClass | Returns a custom CSS class for a table row (tr tag) in list view. Takes a Dataface record as a parameter. | 1.2 |- | fieldname__renderCell | Overrides the table cell content for the "fieldname" field in list view with custom HTML. | 1.0 |- | renderRow | Overrides the the html used for a row in list view for the given record. | 0.7 |- | renderRowHeader | Overrides the header for the table in list view. | 0.7 |- | renderRelatedRow | Overrides the html used for a row in a related record list for a given related record. | 1.0 beta 4 |- | renderRelatedRowHeader | Overrides the html used for the header in a related list. | 1.0 beta 4 |} ====Record Metadata==== {| class="listing listing2" ! Name ! Description ! Version |- | [[getBreadCrumbs]] | Returns the bread crumbs (i.e. you are here) for a given record as an associative array of path parts. | 0.6 |- | [[getChildren]] | Returns a list of Dataface_Record objects that are to be considered children of the given record. | 0.8 |- | [[getCreated]] | Returns a unix timestamp marking the date that a record was created. | 0.9 |- | getDescription | Returns a string description summary of this record. This is used for indexing, RSS feeds, and anywhere that a brief summary of a record is appropriate. | 0.7 |- | getPublicLink | Returns the public URL of this record (in case it is different than the standard URL). | 0.8 |- | getTitle | Returns the title for a given record. The title is used in various parts of the application to represent the record. | 0.5 |- | [[getURL]] | Overrides the getURL() method for a record. Returns the URL that should be used to display the given record. | 0.6 |- | titleColumn | Returns a string SQL select expression that is used to describe the title of records. | 0.5 |} ====View Tab Customization==== {| class="listing listing2" ! Name ! Description ! Version |- | [[How_to_Add_Custom_Sections_to_View_Tab|section__sectionname]] | Defines a section to be displayed in the view tab for the given record. | 0.7 |} ====Search Setup==== {| class="listing listing2" ! Name ! Description ! Version |- | getSearchableText | If [[_index|Indexing]] is turned on, then this returns the text that should be stored in the index for this record for searchability. | 1.0 |} ====RSS Feed Customization==== {| class="listing listing2" ! Name ! Description ! Version |- | [[getFeedItem]] | For RSS Feeds, overrides the defaults and returns an associative array with feed elements for a particular record | 1.0 |- | [[getFeed]] | For RSS feeds, overrides the default feed for a query, returning an array of feed items. | 1.0 |- | getFeedSource | Overrides the default feed source parameter for an RSS feed. | 1.0 |- | [[getRelatedFeed]] | For RSS feeds, overrides the default feed for a related feed. | 1.0 |- | getRSSDescription | Overrides the default generated RSS description for a record. | 1.0 |} ===XML Output Customization=== {| class="listing listing2" ! Name ! Description ! Version |- | [[toXML]] | Overrides the default XML produced for a record in the [[export xml]] action. Returns an XML string. | 1.2.7 |- | [[getXMLHead]] | Returns a string to be included at the beginning of XML output for a particular record. (just inside the opening tag). | 1.2.7 |- | [[xmlTail]] | Returns a string to be included at the end of XML output for a particular record. (just inside the closing tag). | 1.2.7 |} ====Valuelist Customization==== {| class="listing listing2" ! Name ! Description ! Version |- | [[valuelist__valuelistname]] | Defines a valuelist named ''valuelistname''. | 0.7 |} ====Importing Records==== {| class="listing listing2" ! Name ! Description ! Version |- | [[__import__filtername]] | Defines an import filter to named ''filtername'' which is used to import records into the table. | 0.7 |} RSS,Feeds,delegate classes, triggers en 0 Internet_Media_Manager 8 Internet Media Manager '''Manage your videos and photos all in one place''' [[toc]] ===Watch the Guided Tour (6 minutes)=== <nowiki> <embed src="http://media.weblite.ca/lib/flvplayer.swf" width="640" height="448" bgcolor="#FFFFFF" type="application/x-shockwave-flash" pluginspage="http://www.macromedia.com/go/getflashplayer" flashvars="file=http%3A%2F%2Fs3.amazonaws.com%2Fweblite_media%2Fintro_video.flv&image=http%3A%2F%2Fmedia.weblite.ca%2Ffiles%2Fphotos%2Fintro_video.flv.AbpY0Y.jpg&showdigits=true&autostart=false" /> </nowiki> ===Introduction=== The Internet Media Manager is a web-based database application that allows webmasters to centrally store their images and videos to be served on their website(s). It provides a Youtube-like interface whereby users can simply copy and paste code snippets to embed images and videos into their web pages. It also provides a photo gallery component that allows users to easily embed a gallery of images into their web pages by simply copying and pasting a snippet of javascript code. ===Purpose=== I created this application because: # I didn't want to have to resize images in Photoshop anymore before uploading them to the web. # I wanted to be able to embed videos, images, and photo galleries into my web pages without having to muck around with HTML code. IMM (Internet Media Manager) allows you to resize your photos to any size you want, and embed these resized images in your web pages by copying and pasting a snippet of HTML. Similarly it makes embedding videos and photo galleries into your website a snap. ===Features=== * Add/Edit/Delete/Categorize images and videos in a searchable database. * Import multiple images or videos at once by uploading a ZIP file. * Large file imports via FTP/SSH. * Embed video and images directly into other web pages by copying and pasting HTML snippets (like Youtube). * Resize images and videos. * FLV video support (like Youtube). * Search media by content type, category, keyword, etc.. * Includes javascript photo gallery component that can be embedded into any web page. * Amazon Simple Storage Service (S3) integration. ===Requirements=== * [http://www.php.net|PHP] 5.2+ * [http://www.mysql.com|MySQL] 4.1+ * [http://ca.php.net/gd|GD_Image_Processing_Library] * [http://ffmpeg.mplayerhq.hu/|FFMPEG] (optional - if you want to automatically generate poster images for videos). ===Download=== * [https://sourceforge.net/projects/immgr/files/|Internet Media Manager 0.3] ===Installation=== # Download the latest version from Sourceforge. # Extract the files and copy to your web server. # Point your web browser to the install.php and follow the instructions. ===Screenshots=== <nowiki> <script language="javascript" type="text/javascript" src="http://media.weblite.ca/index.php?-action=gallery&-table=files&categories=3&-cursor=0&-skip=0&-limit=30&-mode=list&-photo_max_width=500&--format=js"></script> <div style="clear:both"></div> </nowiki> ===Screencasts=== How to import multiple images at once in a ZIP archive. <nowiki><iframe title="YouTube video player" width="640" height="510" src="http://www.youtube.com/embed/0gfRJ5HkRsI" frameborder="0" allowfullscreen></iframe></nowiki> ===Support=== Visit the [http://xataface.com/forum/viewforum.php?f=12|Support_forum]. Internet Media Manager,resize photos,image gallery,photo gallery,video gallery en 0 __prefs__ 9 __prefs__ ==__prefs__ fields.ini Section== A global section of the [[fields.ini file]] that sets the preferences for the given table and its records. E.g. <code> [__prefs__] hide_posted_by=1 ; Hides the "Posted by" text in glance lists (e.g. related records in the view tab). hide_updated=1 ; Hides the "Updated" text in glance lists (e.g. the related records in the view tab). </code> ===Available Preferences=== Ultimately, all of the preferences available at a global level should be available here, however currently this is not the case and only selected preferences are available at the table level. {| class="listing listing2" ! Name ! Description ! Version |- | [[hide_posted_by]] | HIdes the ''posted_by'' text in glance lists. E.g. In the view tab of a record, the related records are shown in the left column. This will hide the ''posted_by'' text next to each related record. | 1.0b4 |- | [[hide_updated]] | Hides the ''updated'' text in glance lists. E.g. In the view tab of a record, the related records are shown in the left column. This will hide the ''updated'' text next to each related record. | 1.0b4 |- |} en 0 preferences 10 preferences ==Xataface Preferences== [[toc]] Xataface preferences can be defined in 3 ways: # In the ''[_prefs]'' section of rhe [[conf.ini file]] for global static preferences. # Implementing the [[getPreferences]] method in the [[Application Delegate Class]] # In the [[__prefs__]] section of the fields.ini file for a table for static preferences on that table. (Limited to only certain preferences). ===Example [_prefs] section=== In the conf.ini <code> [_prefs] hide_updated=1 hide_posted_by=1 </code> ===Example [[getPreferences]] method=== In the [[Application Delegate Class]]: <code> function getPreferences(){ return array('hide_update'=>1, 'hide_posted_by'=>1); } </code> ===Available Preferences=== {| class="listing listing2" ! Name ! Description ! Default ! Version |- | show_result_stats | Show the result statistics (e.g. found x of y records in table z) | 1 | 0.6 |- | show_jump_menu | Show he drop-down menu that allows you to "jump" to any record in the found set. | 1 | 0.6 |- | show_result_controller | Show Next, previous, page number .. links... | 1 | 0.6 |- | show_table_tabs | Show Details, List, Find, etc... tabs. | 1 | 0.6 |- | show_actions_menu | Show New record, Show all, delete, etc.. | 1 | 0.6 |- | show_logo | Show logo at top of app | 1 | 0.6 |- | show_tables_menu | Show the tabs to select a table. | 1 | 0.6 |- | show_search | Show search field in upper right. | 1 | 0.6 |- | show_record_actions | Show actions related to particular record | 1 | 0.6 |- | show_bread_crumbs | Show bread crumbs at top of page to show where you are. | 1 | 0.6 |- | show_record_tabs | View, Edit, Translate, History, etc... | 1 | 0.6 |- | show_record_tree | Show tree to navigate the relationships of this record. | 1 | 0.6 |- | list_view_scroll_horizontal | Whether to scroll list horizontal if it exceeds page width | 1 | 0.6 |- | list_view_scroll_vertical | Whether to scroll list vertical if it exceeds page height. | 1 | 0.6 |- | hide_posted_by | Whether to hide the ''posted by'' text in glance lists (e.g. in the view tab, the related records are shown in the left column. This hides the ''posted by'' text next to each related record. | 0 | 1.0b4 |- | hide_updated | Whether to hide the ''updated'' text in the glance lists (e.g. in the view tab, the related records are shown in the left column. This hides the ''updated'' text next to each related record. | 0 | 1.0b4 |- | SummaryList_logo_width | The width of the logo to be used as the preview image in summary lists. | null | 0.7 |- | SummaryList_hideSort | Hides the sort control for a summary list (the box that allows users to sort by column). | 0 | 0.7 |- | hide_user_status | Hides the user's status (e.g. "You are logged in as ..." | 0 | 0.7 |- | hide_personal_tools | Hides the personal tool links in upper right. This includes likes such as "Control Panel" and "My Profile" | 0 | 0.7 |- | hide_resultlist_controller | Hides the controller for a result list (E.g. next/back/results per page etc...). | 0 | 0.7 |- | hide_related_sections | Hides the sections of the view tab that show the related records. These are the sortable section boxes. Not the related tabs. | 0 | 1.3 |- | hide_record_search | Hides the record search form that appears in the view tab. Not to be confused with the find tab. | 0 | 1.3 |- | show_resultlist_controller_only_when_needed | Sets the resultlist controller (e.g. back/next/results per page/etc...) to only show up if paging is required (i.e. if there are more records than can be shown on one page (according to the '-limit' parameter). | 0 | 1.0 |- | hide_record_view_logo | Hides the logo for a record that appears in the upper left of the view tab for each record. | 0 | 0.7 |- | horizontal_tables_menu | Whether to force the tables menu to appear as tabs along the top of the page (alternative is as a menu on the left). If there are 10 or fewer allowed tables, then the default is 1, otherwise the default is set to 0. | 1 | 0.6 |- | hide_result_filters | In list view, setting this value to 1 will cause the column filters to be hidden (the select lists to filter the results). | 0 | 0.7 |- | disable_select_rows | A value of 1 causes the checkboxes in each row of the list view to be hidden. | 0 | 0.7 |- | result_list_use_geturl | Use the getURL() method to link to records in the list view rather than the default (which uses the -cursor parameter). | 0 | 0.7 |- | disable_ajax_record_details | Whether to disable the ajax record details (the '+' sign beside each record in list view that expands to show the record details. | 1 | 0.7 |- | use_old_resultlist_controller | As of Xataface 1.1, a new style result list controller is used that resembles facebook. It is more slimmed down and is easier to manage. If you prefer the old controller, set this preference to 1. | 0 | 1.1 |} ===Inverse Preferences=== The following preferences perform the inverse of some of the options above. When these options are set to 1, their respective option is set to 0. {| class="listing listing2" ! Name ! Inverse |- | hide_nav_menu | show_tables_menu |- | hide_view_tabs | show_table_tabs |- | hide_result_controller | show_result_controller |- | hide_table_result_stats | show_result_stats |- | hide_search | show_search |} preferences, prefs, getPreferences en 0 block__blockname 11 block__blockname ===Available Blocks=== This is a grep to show the blocks that are defined in Xataface templates: * Dataface_ActionsMenu.html:actions_menu_head * Dataface_ActionsMenu.html:actions_menu_tail * Dataface_Add_Existing_Related_Record.html:before_add_existing_related_record_form * Dataface_Add_Existing_Related_Record.html:before_add_existing_related_`$ENV.relationship`_form * Dataface_Add_Existing_Related_Record.html:after_add_existing_related_`$ENV.relationship`_form * Dataface_Add_Existing_Related_Record.html:after_add_existing_related_record_form * Dataface_Add_New_Related_Record.html:before_add_new_related_record_form * Dataface_Add_New_Related_Record.html:before_add_new_related_`$ENV.relationship`_form * Dataface_Add_New_Related_Record.html:after_add_new_related_`$ENV.relationship`_form * Dataface_Add_New_Related_Record.html:after_add_new_related_record_form * Dataface_AjaxEventDetails.html:before_event_details * Dataface_AjaxEventDetails.html:after_event_details * Dataface_Delete_Record.html:before_delete_record_form * Dataface_Delete_Record.html:after_delete_record_form * Dataface_Edit_Record.html:before_edit_record_form * Dataface_Edit_Record.html:after_edit_record_form * Dataface_FindForm.html:findform_before_`$element.field.name`_row * Dataface_FindForm.html:findform_before_`$element.field.name`_widget * Dataface_FindForm.html:findform_after_`$element.field.name`_widget * Dataface_FindForm.html:findform_after_`$element.field.name`_row * Dataface_FindForm.html:before_findform_table * Dataface_FindForm.html:findform_before_`$element.field.name`_row * Dataface_FindForm.html:findform_before_`$element.field.name`_widget * Dataface_FindForm.html:findform_after_`$element.field.name`_widget * Dataface_FindForm.html:findform_after_`$element.field.name`_row * Dataface_FindForm.html:after_findform_table * Dataface_Find_View.html:before_find_form * Dataface_Find_View.html:after_find_form * Dataface_Form_Section_Template.html:before_quickform_table * Dataface_Import_RelatedRecords.html:before_import_related_records_form * Dataface_Import_RelatedRecords.html:before_import_related_`$ENV.relationship`_form * Dataface_Import_RelatedRecords.html:after_import_related_`$ENV.relationship`_form * Dataface_Import_RelatedRecords.html:after_import_related_records_form * Dataface_List_View.html:before_result_list * Dataface_List_View.html:after_result_list * Dataface_Login_Prompt.html:before_login_form * Dataface_Login_Prompt.html:after_login_form * Dataface_Main_Template.html:custom_stylesheets2 * Dataface_Main_Template.html:head * Dataface_Main_Template.html:body_atts * Dataface_Main_Template.html:before_body * Dataface_Main_Template.html:before_header * Dataface_Main_Template.html:after_header * Dataface_Main_Template.html:before_search * Dataface_Main_Template.html:after_search_form_submit * Dataface_Main_Template.html:after_search * Dataface_Main_Template.html:before_nav_menu * Dataface_Main_Template.html:after_nav_menu * Dataface_Main_Template.html:before_language_selector * Dataface_Main_Template.html:after_language_selector * Dataface_Main_Template.html:before_user_status_logged_in * Dataface_Main_Template.html:after_user_status_logged_in * Dataface_Main_Template.html:before_user_status_not_logged_in * Dataface_Main_Template.html:after_user_status_not_logged_in * Dataface_Main_Template.html:before_personal_tools * Dataface_Main_Template.html:after_personal_tools * Dataface_Main_Template.html:before_bread_crumbs * Dataface_Main_Template.html:after_bread_crumbs * Dataface_Main_Template.html:before_main_table * Dataface_Main_Template.html:before_left_column * Dataface_Main_Template.html:before_record_tree * Dataface_Main_Template.html:after_record_tree * Dataface_Main_Template.html:before_nav_menu * Dataface_Main_Template.html:after_nav_menu * Dataface_Main_Template.html:before_application_menu * Dataface_Main_Template.html:after_application_menu * Dataface_Main_Template.html:after_left_column * Dataface_Main_Template.html:before_main_column * Dataface_Main_Template.html:before_message * Dataface_Main_Template.html:message * Dataface_Main_Template.html:after_message * Dataface_Main_Template.html:before_errors * Dataface_Main_Template.html:error * Dataface_Main_Template.html:after_errors * Dataface_Main_Template.html:before_table_tabs * Dataface_Main_Template.html:before_menus * Dataface_Main_Template.html:after_menus * Dataface_Main_Template.html:before_main_section * Dataface_Main_Template.html:before_recently_viewed * Dataface_Main_Template.html:after_recently_viewed * Dataface_Main_Template.html:before_record_content * Dataface_Main_Template.html:after_record_content * Dataface_Main_Template.html:after_main_section * Dataface_Main_Template.html:before_fineprint * Dataface_Main_Template.html:after_fineprint * Dataface_Main_Template.html:before_global_footer * Dataface_Main_Template.html:after_global_footer * Dataface_Main_Template.html:before_main_section * Dataface_Main_Template.html:before_recently_viewed * Dataface_Main_Template.html:after_recently_viewed * Dataface_Main_Template.html:before_record_content * Dataface_Main_Template.html:after_record_content * Dataface_Main_Template.html:after_main_section * Dataface_NavMenu.html:tables_menu_head * Dataface_NavMenu.html:tables_menu_tail * Dataface_NavMenu.html:tables_menu_head * Dataface_NavMenu.html:tables_menu_tail * Dataface_New_Record.html:before_new_record_form * Dataface_New_Record.html:after_new_record_form * Dataface_Record_Template.html:before_details_controller * Dataface_Record_Template.html:after_details_controller * Dataface_Record_Template.html:before_record_heading * Dataface_Record_Template.html:after_record_heading * Dataface_Record_Template.html:before_record_tabs * Dataface_Record_Template.html:before_record_content * Dataface_Record_Template.html:after_record_content * Dataface_Record_Template.html:before_record_footer * Dataface_Record_Template.html:after_record_footer * Dataface_Registration.html:before_registration_form * Dataface_Registration.html:after_registration_form * Dataface_Related_Records_List.html:before_related_`$ENV.relationship`_records_list * Dataface_Related_Records_List.html:after_related_`$ENV.relationship`_records_list * Dataface_Remove_Related_Record.html:before_remove_related_record_form * Dataface_Remove_Related_Record.html:before_remove_related_`$ENV.relationship`_record_form * Dataface_Remove_Related_Record.html:after_remove_related_`$ENV.relationship`_record_form * Dataface_Remove_Related_Record.html:after_remove_related_record_form * Dataface_View_Record.html:before_view_tab_content * Dataface_View_Record.html:before_record_actions * Dataface_View_Record.html:after_record_actions * Dataface_View_Record.html:after_view_tab_content * Dataface_related_records_checkboxes.html:before_related_`$ENV.relationship`_records_checkboxes * Dataface_related_records_checkboxes.html:before_related_records_checkboxes * Dataface_related_records_checkboxes.html:after_related_records_checkboxes * Dataface_related_records_checkboxes.html:after_related_`$ENV.relationship`_records_checkboxes * Dataface_set_translation_status.html:before_details_controller * Dataface_set_translation_status.html:after_details_controller ===Available Slots=== * Dataface_ActionsMenu.html:actions_menu * Dataface_Add_Existing_Related_Record.html:add_existing_related_`$ENV.relationship`_form * Dataface_Add_Existing_Related_Record.html:add_existing_related_record_form * Dataface_Add_New_Related_Record.html:add_new_related_`$ENV.relationship`_form * Dataface_Add_New_Related_Record.html:add_new_related_record_form * Dataface_AjaxEventDetails.html:event_details * Dataface_Delete_Record.html:delete_record_form * Dataface_Edit_Record.html:edit_record_form * Dataface_FindForm.html:findform_`$element.field.name`_row * Dataface_FindForm.html:findform_`$element.field.name`_widget * Dataface_FindForm.html:findform_`$element.field.name`_row * Dataface_FindForm.html:findform_`$element.field.name`_widget * Dataface_Find_View.html:find_form * Dataface_Import_RelatedRecords.html:import_related_`$ENV.relationship`_form * Dataface_Import_RelatedRecords.html:import_related_records_form * Dataface_List_View.html:result_list * Dataface_List_View_summary.html:result_list * Dataface_Login_Prompt.html:login_form * Dataface_Main_Template.html:doctype_tag * Dataface_Main_Template.html:html_tag * Dataface_Main_Template.html:html_head * Dataface_Main_Template.html:html_title * Dataface_Main_Template.html:dataface_stylesheets * Dataface_Main_Template.html:custom_stylesheets * Dataface_Main_Template.html:dataface_javascripts * Dataface_Main_Template.html:custom_javascripts * Dataface_Main_Template.html:head_slot * Dataface_Main_Template.html:html_body * Dataface_Main_Template.html:global_header * Dataface_Main_Template.html:search_form * Dataface_Main_Template.html:language_selector * Dataface_Main_Template.html:user_status_logged_in * Dataface_Main_Template.html:user_status_not_logged_in * Dataface_Main_Template.html:personal_tools * Dataface_Main_Template.html:bread_crumbs * Dataface_Main_Template.html:main_table * Dataface_Main_Template.html:left_column * Dataface_Main_Template.html:application_menu * Dataface_Main_Template.html:main_column * Dataface_Main_Template.html:table_tabs * Dataface_Main_Template.html:menus * Dataface_Main_Template.html:main_section * Dataface_Main_Template.html:record_content * Dataface_Main_Template.html:fineprint * Dataface_Main_Template.html:global_footer * Dataface_Main_Template.html:main_section * Dataface_Main_Template.html:record_content * Dataface_Main_Templateold.html:doctype_tag * Dataface_Main_Templateold.html:html_tag * Dataface_Main_Templateold.html:html_head * Dataface_Main_Templateold.html:html_title * Dataface_Main_Templateold.html:dataface_stylesheets * Dataface_Main_Templateold.html:custom_stylesheets * Dataface_Main_Templateold.html:dataface_javascripts * Dataface_Main_Templateold.html:custom_javascripts * Dataface_Main_Templateold.html:head_slot * Dataface_Main_Templateold.html:html_body * Dataface_Main_Templateold.html:global_header * Dataface_Main_Templateold.html:search_form * Dataface_Main_Templateold.html:language_selector * Dataface_Main_Templateold.html:user_status_logged_in * Dataface_Main_Templateold.html:user_status_not_logged_in * Dataface_Main_Templateold.html:personal_tools * Dataface_Main_Templateold.html:bread_crumbs * Dataface_Main_Templateold.html:main_table * Dataface_Main_Templateold.html:left_column * Dataface_Main_Templateold.html:application_menu * Dataface_Main_Templateold.html:main_column * Dataface_Main_Templateold.html:table_tabs * Dataface_Main_Templateold.html:menus * Dataface_Main_Templateold.html:main_section * Dataface_Main_Templateold.html:record_content * Dataface_Main_Templateold.html:fineprint * Dataface_Main_Templateold.html:global_footer * Dataface_Main_Templateold.html:main_section * Dataface_Main_Templateold.html:record_content * Dataface_NavMenu.html:tables_menu_options * Dataface_NavMenu.html:tables_menu_options * Dataface_New_Record.html:new_record_form * Dataface_Record_Template.html:record_heading * Dataface_Record_Template.html:record_content * Dataface_Record_Template.html:record_footer * Dataface_Registration.html:registration_form * Dataface_Related_Records_List.html:before_related_list * Dataface_Related_Records_List.html:related_`$ENV.relationship`_records_list * Dataface_Related_Records_List.html:related_records_list * Dataface_Related_Records_List.html:after_related_list * Dataface_Remove_Related_Record.html:remove_related_`$ENV.relationship`_record_form * Dataface_Remove_Related_Record.html:remove_related_record_form * Dataface_View_Record.html:view_tab_content * Dataface_View_Record.html:record_actions * Dataface_View_Record.html:record_search * Dataface_View_Record.html:`$section.name`_section_content * Dataface_View_Record.html:record_view_main_section * Dataface_View_Record.html:`$section.name`_section_content * Dataface_related_records_checkboxes.html:related_`$ENV.relationship`_records_checkbox_form * Dataface_related_records_checkboxes.html:related_records_checkbox_form * global_header.html:site_logo en 0 Application_Delegate_Class 12 Application Delegate Class [[toc]] ===Synopsis=== The application delegate class is similar to the [[Delegate_class_methods|table_delegate_class]] except that it is applicable to the application as a whole, not just one table. It allows the developer to implement hooks that will be executed by Xataface to modify behavior. Examples of customizations that can be made with the Application Delegate class include: * Permissions * User Preferences * Custom content to be inserted into templates. * Triggers * more. ===Location=== The delegate class is optional and should be located in the conf/ApplicationDelegate.php file in the application directory. ===Example=== <code> <?php class conf_ApplicationDelegate { function getPermissions(&$record){ return Dataface_PermissionsTool::NO_ACCESS(); } } </code> ===Available Methods=== ====Triggers==== {| class="listing listing2" ! Name ! Description ! Version |- | after_action_activate | Trigger called after activation is complete. Activation occurs after a user registers and responds to the registration confirmation email. | 1.2.5 |- | after_action_login | Trigger called after a user logs in | 1.0 |- | after_action_logout | Trigger called after a user logs out | 1.0 |- | after_action_edit | Trigger called after the edit action completes. | 1.0 |- | after_action_new | Trigger called after new action completes. | 1.0 |- | after_action_delete | Trigger called after the delete action completes. | 1.0 |- | [[after_action_activate]] | Trigger called after successfully email validation (after registering). | 1.2 |- | [[before_authenticate]] | Trigger called just before authentication is carried out. This allows you to change the authentication type based on such things as SESSION variables etc... | 1.2.5 |- | [[beforeHandleRequest]] | Trigger called on each page request immediately before the action handler is called. This is handy if you need to perform some action on each page request, such as changing the default action depending on the logged in user. | 1.0 |- | [[loginFailed]] | Trigger called after a failed login attempt. Allows you to provide your own logging. | 2.0.1 |- | [[startSession]] | If implemented, this overrides how Xataface starts its sessions. If you implement this method, your custom method should at least include a call to [http://php.net/session_start session_start]. | 1.2.5 |} ====Preferences==== {| class="listing listing2" ! Name ! Description ! Version |- | getPreferences | Returns the user preference settings. | 0.6 |} ====Permissions==== {| class="listing listing2" ! Name ! Description ! Version |- | getPermissions | Returns the permissions available for a given record. | 0.6 |- | getRoles | Returns the roles allowed for a given record. | 1.0 |- | __field__permissions | Returns the default permissions for a field of a given record. | 1.0 |- | __field__roles | Returns the default roles for a field of a given record. | 1.0 |- | fieldname__permissions | Returns the permissions that are allowed for the field "fieldname" on a given record. | 0.7 |- | fieldname__roles | Returns the roles that are allowed for the field "fieldname" on a given record. | 1.0 |- | rel_relationshipname__permissions | Returns the permissions pertaining to the relationship ''relationshipname'' on a given record. | 1.0 |- | rel_relationshiopname__roles | Returns the role or roles pertaining to the relationship ''relationshipname'' on a given record. | 1.0 |} See [[permissions]] for more information about Xataface's permissions architecture and how to implement custom application permissions. <nowiki><a name="registration"></a></nowiki> ====Registration==== {| class="listing listing2" ! Name ! Description ! Version |- | [[beforeRegister]] | Trigger called before the user registration form is saved. | 1.0 |- | [[afterRegister]] | Trigger called after registration form is saved. | 1.0 |- | [[validateRegistrationForm]] | Validates the input into the registration form. | 1.0 |- | [[sendRegistrationActivationEmail]] | Overrides the sending of the registration activation email. | 1.0 |- | [[getRegistrationActivationEmailInfo]] | Overrides the activation email info. Returns an associative array of the email details (e.g. subject, to, headers, etc... | 1.0 |- | [[getRegistrationActivationEmailSubject]] | Returns the subject of the activation email. | 1.0 |- | [[getRegistrationActivationEmailMessage]] | Returns the message body for the activation email. | 1.0 |- | [[getRegistrationActivationEmailParameters]] | Returns the parameters for the actication email. | 1.0 |- | [[getRegistrationActivationEmailHeaders]] | Returns the headers for the activation email. | 1.0 |- | [[after_action_activate]] | Trigger fired after activation is complete. | 1.2 |} See [[registration form]] for more information about Xataface's registration system and how to allow users to register for an account on your application. <nowiki><a name="password-reset"></a></nowiki> ====Forgot Password==== {| class="listing listing2" ! Name ! Description ! Version |- | [[generateTemporaryPassword]] | Optional method to override the generation of a random temporary password for users when they use the forgot password function. | 2.0.2 |- | [[getPasswordChangedEmailInfo]] | Optional method to define the settings for the email that is sent to the user upon successful resetting of their password using the password reset function. | 1.3 |- | [[getResetPasswordEmailInfo]] | Optional method to define the settings for the email that is sent when a user requests to reset their password. This step comes before the password changed email as first the user requests a password reset and receives this email. Then they click a link in this email to reset the password upon which time they receive a second email containing their temporary password. That email is generated by the [[getPasswordChangedEmailInfo]] method if defined. If this method is not defined then a generic email predefined in Xataface will be sent instead. | 1.3 |} ====RSS Feed Customization==== {| class="listing listing2" ! Name ! Description ! Version |- | [[getFeedItem]] | For RSS Feeds, overrides the defaults and returns an associative array with feed elements for a particular record | 1.0 |- | [[getFeed]] | For RSS feeds, overrides the default feed for a query, returning an array of feed items. | 1.0 |- | getFeedSource | Overrides the default feed source parameter for an RSS feed. | 1.0 |- | [[getRelatedFeed]] | For RSS feeds, overrides the default feed for a related feed. | 1.0 |- | getRSSDescription | Overrides the default generated RSS description for a record. | 1.0 |} ====Template Customization==== {| class="listing listing2" ! Name ! Description ! Version |- | [[block__blockname]] | Outputs content that is meant to override a slot or a block named "blockname". | 0.6 |- | [[getNavItem]] | Overrides the navigation menu item for a particular table. | 1.3 |- | [[navItemIsSelected]] | Overrides the "selected" setting for nav menu items. This is used by the default implementation of [[getNavItem]]. | 1.3 |- | [[getTemplateContext]] | Returns an associative array of variables that should be made available to all templates. | 1.0 |} ====Output Cache Customization==== {| class="listing listing2" ! Name ! Description ! Version |- | [[getOutputCacheUserId]] | Returns a unique user id that is used by the output cache to ensure that different users don't use the same cached page (unless appropriate). This is generally not necessary as the output cache by default uses a different cache for each user... but in some cases you may want to use a different cache for the same user. | 2.0 |} ====Valuelist Customization==== {| class="listing listing2" ! Name ! Description ! Version |- | [[valuelist__valuelistname]] | Defines a valuelist named ''valuelistname''. | 0.7 |} application delegate class en 0 beforeRegister 13 beforeRegister ==beforeRegister() Trigger== A trigger that can be implemented in the [[Application Delegate Class]] or the [[Table Delegate Class]], to be executed before the registration form is saved. This can be used to perform some custom actions like emailing the administrator. ===Signature=== function beforeRegister( Dataface_Record &$record ) : mixed ====Parameters==== {| class="listing listing2" ! Name ! Description |- | &$record | A Dataface_Record object encapsulating the record that is being inserted in the users table for this registration. |- | returns | Mixed. If this method returns a PEAR_Error object, then registration will fail with an error. |} ===Example=== <code> <?php class conf_ApplicationDelegate { function beforeRegister(&$record){ // mail the admin to let him know that the registration is occurring. mail('admin@example.com', 'New registration', 'A new user '.$record->val('username').' has registered); } } </code> ===See Also=== * [[afterRegister]] * [[validateRegistrationForm]] * [[sendRegistrationActivationEmail]] * [[getRegistrationActivationEmailInfo]] * [[getRegistrationActivationEmailSubject]] * [[getRegistrationActivationEmailMessage]] * [[getRegistrationActivationEmailParameters]] * [[getRegistrationActivationEmailHeaders]] en 0 afterRegister 14 afterRegister ==afterRegister() Trigger== A trigger that can be implemented in the [[Application Delegate Class]] or the [[Table Delegate Class]], to be executed after the registration form is saved. This can be used to perform some custom actions like emailing the administrator. ===Signature=== function afterRegister( Dataface_Record &$record ) : mixed ====Parameters==== {| class="listing listing2" ! Name ! Description |- | &$record | A Dataface_Record object encapsulating the record that is being inserted in the users table for this registration. |- | returns | Mixed. If this method returns a PEAR_Error object, then registration will fail with an error. |} ===Example=== <code> <?php class conf_ApplicationDelegate { function afterRegister(&$record){ // mail the admin to let him know that the registration is occurring. mail('admin@example.com', 'New registration', 'A new user '.$record->val('username').' has registered); } } </code> ===See Also=== * [[beforeRegister]] * [[validateRegistrationForm]] * [[sendRegistrationActivationEmail]] * [[getRegistrationActivationEmailInfo]] * [[getRegistrationActivationEmailSubject]] * [[getRegistrationActivationEmailMessage]] * [[getRegistrationActivationEmailParameters]] * [[getRegistrationActivationEmailHeaders]] en 0 validateRegistrationForm 15 validateRegistrationForm ==validateRegistrationForm() hook== A hook that validates the input into the user registration form to make sure that the input is valid. ===Signature=== function validateRegistrationForm( array $values ) : mixed ====Parameters==== {| class="listing listing2" ! Name ! Description |- | $values | An associative array of the input values of the registration form. |- | returns | Mixed. If this method returns a PEAR_Error object then the validation will fail - and the user will be asked to correct his input. |} ===Example=== <code> <?php class conf_ApplicationDelegate { function validateRegistrationForm($values){ if ( $values['age'] < 18 ){ return PEAR::raiseError("Sorry you must be at least 18 years old to join this site."); } return true; } } </code> ===Validation via the Users table Delegate class=== Note that since the registration form is just a "new record form" for the users table, it is also possible (and preferred) to do validation through the users [[table delegate class]]. ===See Also=== * [[afterRegister]] * [[beforeRegister]] * [[sendRegistrationActivationEmail]] * [[getRegistrationActivationEmailInfo]] * [[getRegistrationActivationEmailSubject]] * [[getRegistrationActivationEmailMessage]] * [[getRegistrationActivationEmailParameters]] * [[getRegistrationActivationEmailHeaders]] en 0 sendRegistrationActivationEmail 16 sendRegistrationActivationEmail ==sendRegistrationActivationEmail() Hook== A hook that can be implemented in the [[Application Delegate Class]] or the [[Table Delegate Class]] to override the sending of an activation email to the user. ===Signature=== function sendRegistrationActivationEmail( Dataface_Record &$record, string $activationURL ) : mixed ====Parameters==== {| class="listing listing2" ! Name ! Description |- | &$record | A Dataface_Record object encapsulating the record that is being inserted in the users table for this registration. |- | $activationURL | The URL where the user can go to activate their account. |- | returns | Mixed. If this method returns a PEAR_Error object, then registration will fail with an error. |} ===Example=== <code> <?php class conf_ApplicationDelegate { function sendRegistrationActivationEmail(&$record, $activationURL){ // mail the admin to let him know that the registration is occurring. $username = $record->val('username'); $email = $record->val('email'); mail($email, 'Welcome to the team', 'Welcome '.$record->val('username'). '. You have been successfully registered. Please visit '.$activationURL.' to activate your account' ); } } </code> ===See Also=== * [[beforeRegister]] * [[afterRegister]] * [[validateRegistrationForm]] * [[getRegistrationActivationEmailInfo]] * [[getRegistrationActivationEmailSubject]] * [[getRegistrationActivationEmailMessage]] * [[getRegistrationActivationEmailParameters]] * [[getRegistrationActivationEmailHeaders]] en 0 getRegistrationActivationEmailInfo 17 getRegistrationActivationEmailInfo ==getRegistrationActivationEmailInfo() Hook== A hook that can be implemented in the [[Application Delegate Class]] or the [[Table Delegate Class]] to override the default information that is used to send the registration activation email (the email that the user receives when they register). This should return an associative array with the keys: * subject - The subject of the activation email. * message - The message body of the activation email. * parameters - The parameters to be used in the mail() function for the activation email. * headers - The headers to use in the mail() function for the activation email. ===Signature=== function getRegistrationActivationEmailInfo( Dataface_Record &$record, string $activationURL ) : array ====Parameters==== {| class="listing listing2" ! Name ! Description |- | &$record | A Dataface_Record object encapsulating the record that is being inserted in the users table for this registration. |- | $activationURL | The URL where the user can go to activate their account. |- | returns | Mixed. If this method returns a PEAR_Error object, then registration will fail with an error. |} ===Example=== <code> <?php class conf_ApplicationDelegate { function getRegistrationActivationEmailInfo(&$record, $activationURL){ return array( 'subject' => 'Welcome to the site.. Activation required', 'message' => 'Thanks for registering. Visit '.$activationURL.' to activate your account', 'headers' => 'From: webmaster@example.com' . "\r\n" . 'Reply-To: webmaster@example.com' . "\r\n" . 'X-Mailer: PHP/' . phpversion() ); } } </code> ===Example 2: Only override the subject=== <code> <?php class conf_ApplicationDelegate { function getRegistrationActivationEmailInfo(&$record, $activationURL){ return array( 'subject' => 'Welcome to the site.. Activation required' ); } } </code> ===See Also=== * [[beforeRegister]] * [[afterRegister]] * [[validateRegistrationForm]] * [[sendRegistrationActivationEmail]] * [[getRegistrationActivationEmailSubject]] * [[getRegistrationActivationEmailMessage]] * [[getRegistrationActivationEmailParameters]] * [[getRegistrationActivationEmailHeaders]] en 0 getRegistrationActivationEmailSubject 18 getRegistrationActivationEmailSubject ==getRegistrationActivationEmailSubject() Hook== A hook that can be implemented in the [[Application Delegate Class]] or the [[Table Delegate Class]] to override the default registration activation email subject line (the email that the user receives when they register). ===Signature=== function getRegistrationActivationEmailSubject( Dataface_Record &$record, string $activationURL ) : string ====Parameters==== {| class="listing listing2" ! Name ! Description |- | &$record | A Dataface_Record object encapsulating the record that is being inserted in the users table for this registration. |- | $activationURL | The URL where the user can go to activate their account. |- | returns | Mixed. If this method returns a PEAR_Error object, then registration will fail with an error. |} ===Example=== <code> <?php class conf_ApplicationDelegate { function getRegistrationActivationEmailInfo(&$record, $activationURL){ reeturn 'Welcome to the site.. Activation required'; } } </code> ===See Also=== * [[beforeRegister]] * [[afterRegister]] * [[validateRegistrationForm]] * [[sendRegistrationActivationEmail]] * [[getRegistrationActivationEmailInfo]] * [[getRegistrationActivationEmailMessage]] * [[getRegistrationActivationEmailParameters]] * [[getRegistrationActivationEmailHeaders]] en 0 getRegistrationActivationEmailMessage 19 getRegistrationActivationEmailMessage ==getRegistrationActivationEmailSubject() Hook== A hook that can be implemented in the [[Application Delegate Class]] or the [[Table Delegate Class]] to override the default registration activation email message body (the email that the user receives when they register). ===Signature=== function getRegistrationActivationEmailSubject( Dataface_Record &$record, string $activationURL ) : string ====Parameters==== {| class="listing listing2" ! Name ! Description |- | &$record | A Dataface_Record object encapsulating the record that is being inserted in the users table for this registration. |- | $activationURL | The URL where the user can go to activate their account. |- | returns | Mixed. If this method returns a PEAR_Error object, then registration will fail with an error. |} ===Example=== <code> <?php class conf_ApplicationDelegate { function getRegistrationActivationEmailInfo(&$record, $activationURL){ return 'Thanks for registering. Please visit '.$activationURL.' to activate.'; } } </code> ===See Also=== * [[beforeRegister]] * [[afterRegister]] * [[validateRegistrationForm]] * [[sendRegistrationActivationEmail]] * [[getRegistrationActivationEmailInfo]] * [[getRegistrationActivationEmailSubject]] * [[getRegistrationActivationEmailParameters]] * [[getRegistrationActivationEmailHeaders]] en 0 relationships.ini_file 20 relationships.ini_file ==relationships.ini File Reference== [[toc]] ===Overview=== The relationship.ini file is a configuration file which is associated with a single table of a database application. It provides metadata about the table's relationships to other tables to help Xataface dictate how they should be included in the application. ===Field Directives=== The following directives may be added to a field's section of the relationship.ini file to customize the field's behavior. Some directives are not applicable to all fields. {| class="listing listing2" |- ! Name ! Description ! Version |- | __sql__ | The SQL query that defines this relationship. | all |- | [[action:visible]] | A boolean value (0 or 1) that indicates whether this relationship should be visible in the record tabs. | all |- | [[action:condition]] | An expression that evaluates to a boolean that determines at runtime whether the relationship's tab should appear in the record tabs. | all |- | [[action:delegate]] | The name of an alternative action that can be used instead of the standard related records list. One possible value for this would be "related_records_checkboxes" which would provide the user with a checkbox group to select the records that should be part of the relationship rather than the usual related record list. | 1.0 |- | [[section:limit]] | Integer. The number of records to show in the related record sections (in the view tab). Default is 5. | 1.0 |- | [[section:visible]] | Boolean value (0 or 1) indicating whether the relationship information should appear as a section on the left side of the table. | all |- | [[actions:addexisting]] | Boolean value (0 or 1) indicating whether the action to add existing records should exist in this relationship. | all |- | [[actions:addnew]] | Boolean value (0 or 1) indicating whether the action to add news records should exist in this relationship. | all |- | [[action:label]] | The label that appears in the relationship tab for this relationship. | all |- | [[list:type]] | Optional type of list to use for the related record list. Possible value: "treetable" | 0.8 |- | [[meta:class]] | An optional special class to assign to the relationship. E.g. "parent" or "children". | 0.8 |- | [[metafields:order]] | If the relationship should have a default order this specifies the field that should be used for this sort. | all |- | [[visibility:fieldName]] | If given the value hidden will make that particular fieldName disappear in the relationship. This will only be applied for that particular relationship. | all |- | [[visibility:find]] | If given the value hidden this will cause the related fields to not appear on the find form. Normally each relationship is provided a section of the find form to enable users to find records that contain at least one match in the related records. | 1.3rc4 |- | [[vocabulary:existing]] | Specifies a valuelist that can be used to provide the set of records that can be added to this relationship. If target table has a single column primary key then the valuelist should use the primary key for the value. If it has a multi-column primary key, then the value should be in the form key1=value1&key2=value2 etc... See also [[relationshipname__getAddableValues]] delegate class method for a programatic solution. | 1.0 |} ==Relationship Permissions== See [[Relationship Permissions]] ==See Also== * [http://xataface.com/documentation/tutorial/getting_started/relationships Getting started with relationships] relationships.ini file, relationships en 0 authentication 21 authentication ==Xataface Authentication== [[toc]] Xataface comes with authentication ready to roll out of the box. With a couple of [[_auth|configuration options]] in the [[conf.ini file]], you can activate the default authentication scheme which uses a table (of your choice) in the database to authenticate against. It supports [[password encryption]], and even includes a [[registration form]] if you choose to allow registrations for your application. In addition Xataface's authentication is pluggable, meaning you can write your own plug-ins to integrate your application with any authentication scheme you choose. Some authentication modules that already exist include: * [[CAS Authentication Module|Yale CAS]] * [[LDAP_or_Active_Directory|LDAP]] * [[Facebook Authentication Module|Facebook]] * [[HTTP Authentication Module|HTTP]] ====See Also:==== * [[Writing Custom Authentication Plugins]] * [[Authenticating Against the PHPBB Users table]] * [[Authenticating Against the Joomla! Users Table]] Depending on the complexity of the authentication scheme, these plugins may be easy or complex to create. ===Setting up Basic Authentication=== # Create a table (if you haven't already) to store your application's users. At the bare minimum, this table should have fields to store the username and password (you may call these fields whatever you like). An example table might be: <code> CREATE TABLE `users` ( `username` VARCHAR(32) NOT NULL, `password` VARCHAR(32) NOT NULL, PRIMARY KEY (`username`) ) </code> # Add the following ([[_auth|_auth section]]) to your [[conf.ini file]]: <code> [_auth] users_table=users username_column=username password_column=password </code> This tell Xataface which table you are storing your user accounts in, and the names of the username and password columns. # Add a sample user record to the users table if one does not exist yet.<code> INSERT INTO `users` (`username`,`password`) VALUES ('steve','mypass') </code> # Load your application in your web browser and you'll notice a "login" link in the upper right that allows you to log in. ===Using MD5 Encryption for the Password=== It is good practice to perform some type of encryption on passwords that you store in a database, so that they will be safe, even if your server's security is compromised. One common form of encryption it MD5. You can apply encryption to your passwords by defining the '''encryption''' property to the '''[password]''' field's section of the users table [fields.ini file]. E.g. <code> [password] encryption=md5 </code> This tells Xataface to save data to the password field of the users table with MD5 encryption. In order to switch to MD5 encryption with an existing Xataface installation, all un-encrypted (plain text) passwords must be first converted to MD5. There are several ways to do this. One method is to directly convert the passwords in the database with the MySQL MD5 function. This can be done from the command-line or using a tool such as phpMyAdmin. It can also be done solely within Xataface as follows, assuming a small number of users where you either know all of the passwords or are planning to change them: # Log in to your Xataface application as an existing user with ADMIN-level access. # Navigate to the users table. If you do not already have a link to it, modify your URL to include "-table=" and the name of your users table. # While logged in, add the encryption=md5 parameter to the fields.ini file as described above. # Select each user and re-enter or reset their password. It will now be stored with MD5 encryption. # After completing the above step for all users, you may log out and log back in to verify the change. ===Limiting Access Based on User=== Authentication and permissions are distinct issues, but they are related. It is quite common to require a user to log in to access a section of an application. Permissions can be defined in either the Application delegate class or a table's delegate class - or both. As an example, if we want to require users to log in to access our application we could define the following getPermissions() method to our application delegate class: <code> <?php class conf_ApplicationDelegate { function getPermissions(&$record){ // $record is a Dataface_Record object $auth =& Dataface_AuthenticationTool::getInstance(); $user =& $auth->getLoggedInUser(); if ( $user ) return Dataface_PermissionsTool::ALL(); else return Dataface_PermissionsTool::NO_ACCESS(); } } </code> ===Checking Who Is Logged In=== The [http://dataface.weblite.ca/Dataface_AuthenticationTool Dataface_AuthenticationTool] class handles all of the dirty work of Xataface's authentication. It provides public methods to check who is logged in and perform authentication if necessary. Anywhere inside your Xataface application you can find out who is logged in using one of the following two methods: * [http://dataface.weblite.ca/getLoggedInUser getLoggedInUser()] - Returns a [http://dataface.weblite.ca/Dataface_Record Dataface_Record] object representing a record from the users table. * [http://dataface.weblite.ca/getLoggedInUsername getLoggedInUsername()] - Returns a string. It is quite useful in the getPermissions() method of your delegate classes to find out who is logged in: <code> function getPermissions(&$record){ $auth =& Dataface_AuthenticationTool::getInstance(); $user =& $auth->getLoggedInUser(); if ( $user and $user->val('username') == 'shannah' ){ // Steve is logged in so we give him special permissions return Dataface_PermissionsTool::ALL(); } else { // Steve is not logged in so we give only read only permissions return Dataface_PermissionsTool::READ_ONLY(); } } </code> ====Checking Who is Logged In from a Template==== All templates in Xataface have access to the *$ENV* array that contains references to lots of useful information, including the currently logged in user: * '''$ENV.user''' - The user object of the currently logged in user (or null if nobody is logged in). This is a [http://dataface.weblite.ca/Dataface_Record Dataface_Record] object. * '''$ENV.username''' - The name of the currently logged in user. A string. For example: <code> <!-- Print 'Hello Steve' if Steve is logged in, 'Hello Helen' if Helen is logged in, or just 'Hello' if nobody is logged in. --> Hello {$ENV.username} <!-- Print some personal user info --> {if $ENV.user} Phone number: {$ENV.user->val('phone')}<br/> Email address: {$ENV.user->val('email')}<br/> {/if} </code> This example presumes that the users table has 'phone' and 'email' fields. ====See Also:==== * [http://xataface.com/documentation/tutorial/getting_started/permissions Permissions Section of Getting Started Tutorial] * [http://xataface.com/documentation/how-to/disallow_tables How to disallow access to tables in conf.ini file] * [http://xataface.com/documentation/how-to/security_filters How to use security filters to hide records from certain users] * [[LDAP_or_Active_Directory| Using LDAP or Active Directory for Authentication]] * [[_auth|_auth section directives in conf.ini file]] authentication, [_auth], CAS Authentication, Authentication Modules, Basic Authentication, Security en 0 Writing_Custom_Authentication_Plugins 22 Writing_Custom_Authentication_Plugins ==Writing a Custom Authentication Plugin for Xataface== [[toc]] Xataface has a pluggable [[authentication]] framework that allows you to easily write your own custom [[authentication]] modules to tie in with other systems. Several plugins have already been created including: * [[CAS Authentication Module|Yale CAS]] * [[LDAP Authentication Module|LDAP]] * [[Facebook Authentication Module|Facebook]] * [[HTTP Authentication Module|HTTP]] ===Example: Creating a custom authentication plugin=== Before we begin, a couple of conventions: # '''%XATAFACE_ROOT%''' refers to your Xataface installation directory. This is where all of the Xataface files are located includeing dataface-public-api.php # '''%SITE_ROOT%''' refers to your Xataface application's installation directory. This is where your conf.ini file, index.php, and other application files are stored. ====About our plugin==== Our plugin will be the simplest, most useless authentication plugin you can imagine. It simply checks an array of usernames and passwords to see if the password that the user supplied is valid. ====Creating our plugin==== # Create the '''%XATAFACE_ROOT%/modules/Auth''' directory if it doesn't exist already. This directory will store all of our Xataface authentication plugins. #Create the '''%XATAFACE_ROOT%/modules/Auth/XDB''' directory if it doesn't exist already. This directory will house all of the scripts and files associated with our custom plugin. #Create a new PHP file named '''XDB.php''' inside our '''XDB''' directory that we just created, with the following contents:<code> class dataface_modules_XDB { var $passwords = array( 'steve' => 'stevespass', 'mike' => 'foo' ); function checkCredentials(){ $auth =& Dataface_AuthenticationTool::getInstance(); $creds = $auth->getCredentials(); if ( @$this->passwords[$creds['UserName']] == $creds['Password'] ){ return true; } else { return false; } } } </code> # Now, change the '''[_auth]''' section of the conf.ini file to let Xataface know that we want to use our custom module:<code> [_auth] auth_type=XDB </code> # Try to log into your application. You'll notice that the only username/password combinations that are accepted are the ones that we specified in our '''$passwords''' array in our module. This is just a simple example, but you can see how this can be expanded to provide more complex modules. ===checkCredentials() not enough?=== Some authentication plugins will need more control than simply checking credentials. Some plugins may want to make use if their own login forms, or redirect to other sites to handle the authentication. Xataface's [http://dataface.weblite.ca/Dataface_AuthenticationTool authentication tool] is up to the task, as virtually all parts of the login/logout process can be overridden and customized in your module. The previous example shows how the getCredentials() method can be overridden, but there are other methods that can be implemented to customize the login process as well. e.g. * showLoginPrompt() - This method is called when it is time to display the login prompt for the user. It could also be made to redirect to another site that has a login prompt. * logout() - This is called when the user tries to log out. If there are any special cookies of variables that need to be cleaned up to facilitate a successful logout, you could implement this method. * [http://dataface.weblite.ca/getLoggedInUser getLoggedInUser()] * [http://dataface.weblite.ca/getLoggedInUsername getLoggedInUsername()] * getCredentials() - Handles the obtaining of credentials from the request or from the environment. * authenticate() - Handles the whole login process ===See Also:=== * [[Application Delegate Class]] for before/after login/logout triggers that may be more appropriate in some circumstances than creating a custom authentication plugin. * [[authentication|Xataface Authentication]] en 0 xataface_templates 23 xataface_templates ==Xataface Templates== [[toc]] Xataface uses the [http://smarty.php.net Smarty Template Engine] to power all of its templates. Templates are stored in the one of the following locations: * %XATAFACE_ROOT%/Dataface/templates * %SITE_ROOT%/templates Where %XATAFACE_ROOT% is the Xataface directory (includes files such as dataface-public-api.php), and %SITE_ROOT% is the path to your application. You may also have subdirectories within these templates directories. ===Cascading Templates=== Xataface uses a simple cascading technique for deciding which template to use. If there are templates in the %SITE_ROOT%/templates and %XATAFACE_ROOT%/Dataface/templates directories with the same name, then Xataface will use the one in the %SITE_ROOT%/templates directory. In this way, you are able to override any of Xataface's core templates by adding one of the same name to your %SITE_ROOT%/templates directory. The most common template to override is the Dataface_Main_Template.html template which defines the look and feel for the entire application (e.g. header, footer, etc...). Hence, if you wanted to customize the look & feel of your application, you would likely start by copying %XATAFACE_ROOT%/Dataface/templates/Dataface_Main_Template.html into the %SITE_ROOT%/templates directory and make modifications to it as desired. ===Useful Smarty Tags introduced by Xataface=== In addition to the standard set of Smarty tags, Xataface templates provide some of its own. ==Xataface Templates== Xataface uses the [http://smarty.php.net Smarty Template Engine] to power all of its templates. Templates are stored in the one of the following locations: * %XATAFACE_ROOT%/Dataface/templates * %SITE_ROOT%/templates Where %XATAFACE_ROOT% is the Xataface directory (includes files such as dataface-public-api.php), and %SITE_ROOT% is the path to your application. You may also have subdirectories within these templates directories. ===Cascading Templates=== Xataface uses a simple cascading technique for deciding which template to use. If there are templates in the %SITE_ROOT%/templates and %XATAFACE_ROOT%/Dataface/templates directories with the same name, then Xataface will use the one in the %SITE_ROOT%/templates directory. In this way, you are able to override any of Xataface's core templates by adding one of the same name to your %SITE_ROOT%/templates directory. The most common template to override is the Dataface_Main_Template.html template which defines the look and feel for the entire application (e.g. header, footer, etc...). Hence, if you wanted to customize the look & feel of your application, you would likely start by copying %XATAFACE_ROOT%/Dataface/templates/Dataface_Main_Template.html into the %SITE_ROOT%/templates directory and make modifications to it as desired. ===Useful Smarty Tags introduced by Xataface=== In addition to the standard set of Smarty tags, Xataface templates provide some of its own. {| class="listing listing2" |- ! Name ! Description ! Version |- | [[templates:tags:use_macro|use_macro]] | Include another template with the option to override certain sections. | 0.6 |- | define_slot | Marks a section that can be overridden by other templates that include this one via the use_macro tag. | 0.6 |- | fill_slot | Overrides content in a template that has been included via the use_macro tag. | 0.6 |- | block | Marks an insertion point where content can be inserted by delegate classes and modules. | 0.6 |- | load_record | Loads a [http://dataface.weblite.ca Dataface_Record] object from the database to be used in the template. | 0.6 |- | group | Groups an array of records together based on a field value. | 0.6 |- | img | Displays a thumbnail of an image. | 0.6 |- | actions | Loads an associative array of actions defined in the actions.ini file, based on certain criteria. | 0.6 |- | actions_menu | Displays a menu of actions based on certain criteria. | 0.6 |- | record_actions | A specialization of the actions_menu tag. This displays a menu of actions only in the record_actions category. | 0.6 |- | record_tabs | A specialization of the actions_menu tag. This displays a menu of actions only in the record_tabs category. | 0.6 |- | result_controller | Displays the paging controls for the current table's records. Use this for any listing of records. | 0.6 |- | result_list | Displays the result list (from the list tab) for the current request. | 0.6 |- | related_list | Displays the related records list for the current request. | 0.6 |- | bread_crumbs | Displays the bread crumbs for the current request. | 0.6 |- | search_form | Displays the find form for the current table. | 0.6 |- | language_selector | Displays a menu to select the user's preferred language. | 0.6 |- | next_link | Displays a link to the next XXX records. | 0.6 |- | prev_link | Displays a link to the previous XXX records. | 0.6 |- | jump_menu | Displays the select list of the records found in this found-set so that the user can jump directly to any record. | 0.6 |- | limit_field | Displays a text field for the user to select the number of records to display per page. | 0.6 |- | result_index | Displays the index of pages (1 to XXX) for this query. | 0.6 |- | summary_list | Displays a list of records in the current found set using a summary format rather than the regular table format. | 0.6 |- | sort_controller | Displays a control to sort the results on any column. | 0.6 |- | glance_list | Displays a simple, brief list of records matching certain criteria. | 0.6 |- | record_view | Loads structured data for a record as required for the view tab. | 0.6 |- | feed | Generates a link to an RSS feed based on certain criteria. | 0.6 |- | translate | Display a section of text in the user's selected language. (i18n). | 0.6 |- | if_allowed | The contents of this block are shown only if the user has certain permissions. | 0.6 |- | editable | Make a section of the page editable using AJAX. | 0.6 |- | abs | Convert a URL into an absolute URL. | 0.6 |} ===Useful Template Variables=== Xataface makes certain variables available to every template: {| class="listing listing2" |- ! Name ! Description ! Version |- | $ENV.REQUEST | Reference to the $_REQUEST array (HTTP Request parameters, both GET and POST) | 0.6 |- | $ENV.SESSION | Reference to the $_SESSION array (the session variables) | 0.6 |- | $ENV.DATAFACE_PATH | The file system path to the Xataface directory (i.e. the directory containing all of the Xataface files such as dataface-public-api.php). | 0.6 |- | $ENV.DATAFACE_URL | The URL to the Xataface directory. | 0.6 |- | $ENV.DATAFACE_SITE_PATH | The file system path to your application directory. (i.e. the directory containing your conf.ini and index.php files). | 0.6 |- | $ENV.DATAFACE_SITE_URL | The URL to your application directory. | 0.6 |- | $ENV.DATAFACE_SITE_HREF | The URL to your application's script. This differs from the $ENV.DATAFACE_SITE_URL variable in that this also includes the script name. | 0.6 |- | $ENV.SCRIPT_NAME | Same as $ENV.DATAFACE_SITE_HREF | 0.6 |- | $ENV.APPLICATION | A reference to the application's conf array (i.e. the parsed contents of the conf.ini file). | 0.6 |- | $ENV.APPLICATION_OBJECT | A reference to the Dataface_Application object for the application. | 0.6 |- | $ENV.SERVER | A reference to the $_SERVER array. | 0.6 |- | $ENV.QUERY | A reference to the current query (i.e. Dataface_Application::getInstance()->getQuery()) | 0.6 |- | $ENV.action | The name of the current action as specified by the -action REQUEST parameter. | 0.6 |- | $ENV.table | The name of the current table as specified by the -table REQUEST parameter. | 0.6 |- | $ENV.table_object | A reference to the current table. | 0.6 |- | $ENV.relationship | The name of the current relationship as specified by the -relationship REQUEST parameter. | 0.6 |- | $ENV.limit | The value of the -limit REQUEST parameter. This is the number of records to show per page. | 0.6 |- | $ENV.start | The value of the -start REQUEST parmeter. This is the starting point in the result set which is currently being displayed. | 0.6 |- | $ENV.resultSet | A reference to the [http://dataface.weblite.ca/Dataface_QueryTool Dataface_QueryTool] object for this result set. | 0.6 |- | $ENV.record | A reference to the [http://dataface.weblite.ca/Dataface_Record Dataface_Record] object that is matched by the current query. | 0.6 |- | $ENV.mode | The name of the current mode. e.g. find, list, browse | 0.6 |- | $ENV.language | The 2-digit ISO language code that is currently selected as the user's preferred language. | 0.6 |- | $ENV.prefs | A reference to the preferences array ($conf['_prefs']) | 0.6 |- | $ENV.search | The value of the current full-text search (i.e. the search that was entered into the upper right search field. | 0.6 |} ==Smarty Plugins== One of the most powerful features of [http://www.smarty.net Smarty] is its pluggable architecture. You can easily add your own custom plugins to a registered "plugins" directory to add functions, modifiers, blocks, and other features to your templates. Prior to Xataface 2.0, you Smarty plugins could only be placed in the ''lib/Smarty/plugins'' directory of the Xataface distribution folder. This is not very conducive to Xataface updates, though. In general it is best practice to not change anything inside the xataface directory. Most other configuration and extensions can be handled by making changes to your application's directory which override corresponding functionality in Xataface. As of Xataface 2.0, you can create a directory named ''plugins'' to your application directory, Smarty knows to look in this directory for plugins. For versions of Xataface prior to 2.0, you can make a small modification to the SkinTool to also add support as desribed in [http://xataface.com/forum/viewtopic.php?f=4&t=6722 this post]. ===Example Plugin=== The following is an example Smarty plugin adapted from [http://www.smarty.net/docs/en/plugins.functions.tpl this page] but modified slightly to work in Xataface. It is a simple "eightball" plugin that adds a tag {eightball} to Xataface that you can use in any of your templates. Whenever this tag is rendered it outputs one of a set of predefined strings randomly. # Add a ''plugins'' directory to your application directory. i.e. ''path/to/app/plugins'' # Add a file inside this ''plugins'' directory called ''<nowiki>function.eightball.php</nowiki>'' with the following content:<code> <?php /* * Smarty plugin * ------------------------------------------------------------- * File: function.eightball.php * Type: function * Name: eightball * Purpose: outputs a random magic answer * ------------------------------------------------------------- */ function smarty_function_eightball($params, Dataface_SkinTool $template) { $answers = array('Yes', 'No', 'No way', 'Outlook not so good', 'Ask again soon', 'Maybe in your reality'); $result = array_rand($answers); return $answers[$result]; } </code> # If you compare this function to the original example in [http://www.smarty.net/docs/en/plugins.functions.tpl the smarty tutorial] you'll notice that the 2nd parameter has been changed to type ''Dataface_SkinTool'' from ''Smarty_Internal_Template''. If you don't make this change, you will get a fatal error when you try to use the tag. This function defines an ''{eightball}'' tag that can be added to any Smarty template in Xataface. # Next we'll create a template that uses this tag. If your application doesn't have a ''templates'' directory, create one now (i.e. path/to/app/templates). # Add a file inside your templates directory called ''testing.html'' with the following content:<code> The eight ball says {eightball} </code> # Now we need to display this template somewhere in our interface. In this case, we'll choose the ''before_record_content'' block. (This will render the template before the main section of the view tab). Add the following method to your [[Application_Delegate_Class]]:<code> function block__before_record_content(){ df_display(array(), 'testing.html'); } </code> # Now if you load your application in a web browser and navigate to the details view for a record, you should see something like the following: <nowiki><img src="http://media.weblite.ca/files/photos/Screen_Shot_2012-04-16_at_12.33.01_PM.png?max_width=640"/></nowiki> ===See also:=== * [http://www.xataface.com/documentation/tutorial/getting_started/changing-look-and-feel Changing the Look & Feel of Xataface] (From the Getting Started Tutorial) * [http://www.xataface.com/documentation/tutorial/customizing-the-dataface-look-and-feel Cusomizing the Xataface Look & Feel] Tutorial templates, plugins, smarty en 0 templates:tags:use_macro 24 templates:tags:use_macro ==use_macro Template Tag== ===Synopsis=== The use_macro tag includes another template into the current template with the option to override certain sections. ===Parameters=== {| class="listing listing2" |- ! Name ! Description ! Version |- | file | The path the template to include (within the templates directory). | 0.6 |} ===Example=== In this example we will create a template for a user profile, but this template will include a slot that can be overridden by other templates to customize the user bio. ====user-profile.html==== <code> <html> <head> <title>User profile</title> </head> <body> <h1>User bio</h1> <div id="bio"> {define_slot name="bio"} This text will be overridden by other templates to place the correct bio information. {/define_slot} </body> </html> </code> ====steve-profile.html==== <code> {use_macro file="user-profile.html"} {fill_slot name="bio"} This is Steve's bio. It will override the text in the bio slot. {/fill_slot} {/use_macro} </code> ===See also:=== * [[xataface templates|Xataface templates]] * [[templates:tags:define_slot|The define_slot tag]] * [[templates:tags:fill_slot|The fill_slot tag]] * [http://www.xataface.com/documentation/tutorial/getting_started/changing-look-and-feel Changing the Look & Feel of Xataface] (From the Getting Started Tutorial) * [http://www.xataface.com/documentation/tutorial/customizing-the-dataface-look-and-feel Cusomizing the Xataface Look & Feel] Tutorial en 0 conf.ini_file 25 conf.ini_file ==conf.ini File== [[toc]] The conf.ini file is where most of the application-level configuration information is stored for a Xataface application. It contains information such as: * database connection information * which tables should appear in the tables menu. * [[preferences|preference settings]] * [[authentication]] settings * which add-on [[modules]] are to be used * output caching settings * history/undo settings * other misc settings. Every conf.ini file must contain at least the following sections: {| class="listing listing2" |- ! Name ! Description ! Version |- | _database | Contains database connection info. | all |- | _tables | Contains a list of tables that are to be included in the navigation menu of the application. | all |} The following optional sections may also be included: {| class="listing listing2" |- ! Name ! Description ! Version |- | [http://xataface.com/documentation/how-to/disallow_tables _allowed_tables] | Specifies tables that should be explicitly allowed to override disallowed tables listed or matched in the [http://xataface.com/documentation/how-to/disallow_tables _disallowed_tables] section. | 0.7 |- | [[_auth]] | Contains information about [[authentication]]. | 0.6 |- | [http://xataface.com/documentation/how-to/disallow_tables _disallowed_tables] | A list of tables or patterns that match tables that should be blocked from being accessed directly through the application. By default any table beginning with an underscore, 'dataface_', or ending in '__history' are blocked. This prevents unintended access to some of the automatically created tables in Xataface. | 0.7 |- | _feed | Configuration options for [[Introduction_to_RSS_Feeds_in_Xataface|RSS feeds]] that are generated by the application. | 1.0 |- | _history | Settings pertaining to the [http://xataface.com/documentation/how-to/history-howto history feature] (e.g. whether it has been enabled). | 0.7 |- | _index | Settings for the full site search indexing. | 1.0 |- | _modules | A list of [[modules]] that are enabled for this application. | 1.0 |- | [[_output_cache]] | Output cache settings. Using output caching can dramatically improve performance for busier sites. | 0.8 |- | _themes | A list of the themes that are to be applied to the application. | 0.8 |} ===Stand-alone Attributes=== Stand-alone attributes for an INI file must appear at the beginning of the INI file (before any of the sections). The conf.ini may contain the following stand-alone attributes. {| class="listing listing2" |- ! Name ! Description ! Values ! Version |- | cache_queries | Enables query caching. Enabling this feature can yield drastic performance improvements especially on busy sites with large databases. | boolean (0 or 1) | 1.2 |- | cache_queries_log | Enables logging of query caching to the file /tmp/querylog.log so that you can tell whether your queries are being cached, and which ones are being cached. | boolean (0 or 1) | 1.2 |- | default_action | The default action to be performed if it is not explicitly specified in the query (e.g. 'list', 'find', 'edit'). Default is 'list'. | string | 0.6 |- | debug | If this is set to 1, then the application will run in debug mode which displays the available slots and blocks on the screen, along with some other debug information. | 0 or 1 (default is 0) | 0.6 |- | default_browse_action | The default action to perform in the details tab. E.g. When you click on the "details" tab there are a number of sub-tabs including 'view', 'edit', etc... . The default value for this directive is 'view'. If you want to go directly to the edit form when clicking on a record in list view, you would set ''default_browse_action'' to 'edit'. | string | 0.6 |- | default_language | The default language to use. This is the 2-digit ISO language code. If this value is not specified it defaults to the first language listed in the ''[languages]'' section. | string (2-digit ISO language code) | 0.6 |- | default_limit | The default limit (i.e. the number of records to show per page) if none is explicitly specified in the query. Default is 30. | int | 0.6 |- | default_table | The default table to show if none is specified by the query. If you do not define this value, then the first table in the ''[_tables]'' section is used. | string |0.6 |- | disable_session_ip_check | Default behaviour automatically tracks the IP address of the user when they log in. If a request is made for a session from a different IP then the session is automatically destroyed and the user is logged out. | boolean | 1.3rc4 |- | title | A title for the application (appears in the browser title bar). | string | 0.6 |- | usage_mode | The usage mode of the application. If this value is set to ''edit'', then ajax inline editing is enabled (i.e. you can click on any value in the application to edit it inline. | 'view' or 'edit' | 0.6 |} ===Example 1: A simple conf.ini file=== <code> [_database] host="localhost" name="mydb" user="mydbuser" password="foo" [_tables] webpage_sites="Websites" translations = "Translations" packages="Packages" users=Users proof_jobs="Jobs" webpage_status="Webpages Status" </code> ===Example 2: A more complex conf.ini file=== <code> ;debug=1 ;default_action=home ;google_translate_url="http://weblite-dns2.com/proxy.php" google_translate_url="http://ec2-75-101-244-123.compute-1.amazonaws.com/proxy.php" title="Web Lite Translate" default_price_per_word=0.15 ;;Configuration settings for application title="translation_weblite_ca" scriptUrl="http://translation.weblite.ca/index.php" multilingual_content=1 [_database] host="localhost" name="mydb" user="mydbuser" password="foo" [_tables] webpage_sites="Websites" translations = "Translations" packages="Packages" users=Users proof_jobs="Jobs" webpage_status="Webpages Status" [_auth] users_table=users username_column=username password_column=password secret_code="ljkasdfjkldsafliasdoiudsfoi" allow_register=1 session_timeout=999999999 [_modules] modules_ShoppingCart="modules/ShoppingCart/ShoppingCart.php" [ShoppingCart_taxes] ;; This section is necessary to declare that we have NO taxes. [metatags] keywords = "translation, translate" description = "Good translation service" ;[_output_cache] ; enabled=1 [_mail] func=mail2 </code> en 0 permissions.ini_file 26 permissions.ini_file ==The permissions.ini File== [[toc]] The permissions.ini file stores custom permissions and roles that can be used by an application. It is an optional file that should be placed in the application root directory (i.e. the same directory where your conf.ini, and index.php files are located). The permissions.ini file allows you to define two things: # Permissions # Roles (i.e. sets of permissions). Permissions and roles are used throughout Xataface to limit access to actions, records, fields, and relationships. For example, each action in your application can specify a permission that is necessary to perform the action. Your delegate classes may include getPermissions() methods to define what permissions a user gets when interacting with different records. This file (permissions.ini) simply defines the permissions that can be used by your application. It doesn't actually assign those permissions. Assigning permissions is the job of the getPermissions() (or getRoles()) method. ===Defining Permissions=== Permissions are defined by standalone properties in the beginning of the permissions.ini file. For example, if you were desiging a proof-reading application, you might need permissions for "submit_for_proof", or "approve_text" to correspond with the submitting a document to be proof-read, and approving a document's proof. In this case we would have the following at the beginning of our permissions.ini file: <code> submit_for_proof = Submit a document to be proofread approve_text = "Approve this document's proof" </code> The left side of the equals sign is the name of the permission. The right side contains a human readable description of the permission and what it is for. ===Limiting Access to Actions based on Permissions=== At this point these permissions don't do anything. In order to be useful we need reference these permissions from an action or a section. For example, let's create an action called "submit_for_proof" which displays a form for a user to submit a document record to be proofread. Our actions.ini file entry might look something like: <code> [submit_for_proof] url="{$this->url('-action=submit_for_proof')}" label="Submit document for proof" category=record_actions permission=submit_for_proof template=submit_for_proof.html </code> And for completeness, since this make-believe action specifies th "submit_for_proof.html" template, we'll create the "submit_for_proof.html" template in the templates directory: <code> <html><body>You have permission to perform this action.</body></html> </code> ===Defining Who Get's Which Permissions=== Finally, in order to benefit from permissions, your application has to decide that it is going to use permissions (unless you define a getPermissions() method, users are granted ALL permissions by default. Hence if you try to access our submit_for_proof action, we'll see it without any problem. Regardless of who we are. So let's create a simple, but restrictive getPermissions() method in our application delegate class: <code> <?php class conf_ApplicationDelegate { function getPermissions(&$record){ return Dataface_PermissionsTool::READ_ONLY(); } } </code> Now if we try to access our submit_for_proof action it will give us a "Permission Denied" message, because we are only granted READ ONLY permissions (which is a role that includes the view permission and some others - but not our custom "submit_for_proof" permission. Now we'll make a small modification to our getPermissions() method to provide us with our submit_for_proof permission: <code> <?php class conf_ApplicationDelegate { function getPermissions(&$record){ $perms = Dataface_PermissionsTool::READ_ONLY(); $perms['submit_for_proof'] = 1; return $perms; } } </code> Now if we try to access our submit_for_proof action, it will show us our template with no error messages (hopefully). ===Roles=== Roles are sets of permissions. They are defined in the permissions.ini file as sections with lists of included permissions. It might be handy to create roles such as EDITOR or MANAGER which contain sets of permissions that are meant to be assigned to users of those types. For example an EDITOR may have the view and edit permissions, but not the delete permission. A MANAGER might have the view, edit, and delete permissions. You can define these two roles in the permissions.ini file as follows: <code> [EDITOR] view=1 edit=1 [MANAGER] view=1 edit=1 delete=1 </code> Then we could assign these roles to users using the Dataface_PermissionsTool::getRolePermissions() method: <code> function getPermissions(&$record){ $user =& Dataface_AuthenticationTool::getInstance()->getLoggedInUser(); if ( $user and $user->val('role') == 'EDITOR' ){ return Dataface_PermissionsTool::getRolePermissions('EDITOR'); } else if ( $user and $user->val('role') == 'MANAGER' ){ return Dataface_PermissionsTool::getRolePermissions('MANAGER'); } return Dataface_PermissionsTool::READ_ONLY(); } </code> Or equivalently we could use the getRoles() method of our delegate class instead of getPermissions(): <code> function getRoles(&$record){ $user =& Dataface_AuthenticationTool::getInstance()->getLoggedInUser(); if ( $user and $user->val('role') == 'EDITOR' ){ return 'EDITOR'; } else if ( $user and $user->val('role') == 'MANAGER' ){ return 'MANAGER' } return 'READ ONLY'; } </code> ===Xataface Core Permissions & Roles=== Xataface is distributed with its own permissions.ini file that defines some core permissions and roles. You can look at this permissions.ini file (located in the Xataface directory) to see what the format should look like. Any settings you place in your application's permissions.ini file will augment or override settings in Xataface's file. Some core permissions include: {| class="listing listing2" |- ! Name ! Description ! Version |- | view | Permission to view a record or field. This permission is required to access the view tab, and several other details tabs. | 0.6 |- | list | Permission to access the list tab. | 0.6 |- | calendar | Permission to access the calendar tab. | 0.6 |- | edit | Permission to edit a record or field. This also gives access to the edit tab. | 0.6 |- | new | Permission to edit a record or field for the purpose of creating a new record. This permission is required to access the new record form. | 0.6 |- | select_rows | Permission to select rows in list view to perform actions on them. | 0.6 |- | post | Permission to post a record using HTTP POST | 0.6 |- | copy | Permission to copy a record. | 0.6 |- | update_set | Permission to perform an update on a result set (i.e. access the update set action). | 0.8 |- | add new related record | Permission to add a new record to a relationship. See [[Relationship Permissions]] | 0.6 |- | add existing related record | Permission to add an existing record to a relationship. See [[Relationship Permissions]] | 0.6 |- | view related records | Permission to view the records in a relationship. See [[Relationship Permissions]] | 1.0 |- | delete | Permission to delete a record. | 0.6 |- | delete found | Permission to access the delete found set action (to delete multiple records at a time). | 0.6 |- | show all | Permission to access show all records action. | 0.6 |- | remove related record | Permission to remove a record from a relationship. See [[Relationship Permissions]] | 0.6 |- | delete related record | Permission to delete a record in a relationship. This is stronger than the remove related record permission in that it allows the user to delete the record from the database. See [[Relationship permissions]] | 0.6 |- | find | Permission to perform the find action. | 0.6 |- | import | Permission to perform the import action (to import records into the database). | 0.6 |- | export_csv | Permission to perform the Export CSV action (to export the result set in comma-separated-value format). | 0.6 |- | export_xml | Permission to perform the Export XML action (to export the result set as XML). | 0.8 |- | translate | Permission to translate a record into another language. This permission provides access to the "translate" tab. | 0.8 |- | history | Permission to view history information for a record (e.g. the history tab). This requires that history be enabled. | 0.8 |- | edit_history | Permission to edit history information such as undo/redo support for a record. | 0.8 |- | navigate | Permission to navigate through records of a table. | 0.6 |- | reorder_related_records | Permission to reorder the records of a relationship (this is different than just sorting). It sets a default order for the records. Requires the metafields:order directive to be set for the relationship. | 0.6 |- | ajax_save | Permission to save a record through AJAX. | 0.8 |- | ajax_load | Permission to load a record through AJAX. | 0.8 |- | ajax_form | Permission to access the inline editing ajax form for a record. | 0.8 |- | find_list | Permission to search current table. | 0.6 |- | find_multi_table | Permission to perform a site-wide search. | 0.8 |- | register | Permission to register for an account. | 0.8 |- | xml_view | Permission to view a result set as xml. | 0.8 |- | view_xml | View the XML for an individual record. | 0.8 |- | manage_output_cache | Management permission to clear the output cache. | 0.8 |- | manage_migrate | Permission to access the migration tool to migrate between versions. | 0.8 |- | manage | Permission to access the management control panel. | 0.8 |- | manage_build_index | Permission to rebuild the search index. | 0.8 |- | expandable | Whether the record can be expanded in the left nav menu | N/A |} Some core roles include: {| class="listing listing2" |- ! Name ! Permissions Included ! Version |- | READ ONLY | view, list, calendar, view xml, show all, find, navigate, ajax_load, find_list, find_multi_table, rss, export_csv, export_xml, and export_json | 0.6 |- | EDIT | All permissions in READ ONLY, and edit, add new related record, add existing related record, add new record, remove related record, reorder_related_records, import, translate, new, ajax_save, ajax_form, history, edit_history, copy, update_set, and select_rows | 0.6 |- | DELETE | All permissions in EDIT, and delete and delete found. | 0.6 |- | OWNER | All permissions in DELETE except navigate, new, and delete found. | 0.6 |- | REVIEWER | All permissions in READ ONLY, and edit and translate. | 0.6 |- | USER | All permissions in READ ONLY, and add new related record. | 0.6 |- | ADMIN | All permissions in DELETE and xml_view | 0.6 |- | MANAGER | All permissions in ADMIN and manage, manage_output_cache, manage_migrate, manage_build_index, and install. | 0.6 |} ===Extending and Overriding Roles=== The cleanest and easiest way to define a new role is to extend an existing role. Xataface allows you to extend roles via the '''extends''' keyword. For example, if you wanted to create a role '''TEST ROLE''' that contained all of the same permissions as the READ ONLY role, you could define it as follows in your application's permissions.ini file: <code> [TEST ROLE extends READ ONLY] </code> If we wanted it to contain the same permissions as READ ONLY but to also allow the edit permission we would define it as: <code> [TEST ROLE extends READ ONLY] edit=1 </code> If we wanted to disallow the list permission, we would do something like: <code> [TEST ROLE extends READ ONLY] edit=1 list=0 </code> ===Overriding Existing Roles=== You can also redefine existing roles: <code> [READ ONLY extends READ ONLY] my_permission=1 </code> This is handy if you have added your own custom permissions that you feel should be included in a core role. Note that there are some caveats regarding the order of how these roles are defined. Please refer to this forum post for more details: [http://www.xataface.com/forum/viewtopic.php?t=6187 Overriding Roles / Permissions] ==See Also== * [[Relationship Permissions]] * [[getPermissions]] - The getPermissionsMethod * [[Delegate class methods]] - Delegate class methods. * [http://xataface.com/documentation/tutorial/getting_started/permissions Getting started with Xataface permissions] permissions.ini, getPermissions, permissions en 0 filter 27 filter ==The filter attribute of the [[fields.ini file]]== The filter attribute with a value of 1 specifies that a field should be used as a filter field in list view. In list view, any filter fields will provide a select list with all of the possible values in that field. Selecting one of the items in this list will filter the results to only show records of that value. ===Example 1: Year, Make, Model=== The Fuel Economy Database has three fields with filter=1 : Year, Make, and Model. I.e., in their fields.ini file we have something like: <code> [Year] filter=1 [Make] filter=1 [Model] filter=1 </code> This causes 3 select lists to appear in list view. See the application [http://fueleconomydb.com/index.php?-action=list here] and notice the select lists for Year, Make, and Model just above the list of results. If you are filtering on a field where an ID is stored in the DB but you are using a vocabulary to associate it with a value, then it will still be sorted on the ID. If you want to sort on value then you should add a [[Grafted fields|grafted field]] with the value using the __sql__ directive of the fields.ini file, then use that grafted field as your filter field, like the following: <code> __sql__ = "select a.*, b.foo_name from a left join b on a.foo_id=b.foo_id" [foo_name] filter=1 </code> en 0 group 28 group ==group directive in [[fields.ini file]]== The group directive allows you to declare that certain fields of your table should be grouped together on the edit form and the view tab (and other logical places). For example, fields like address, city, state, country, postal_code would likely be grouped together as address_info. Grouping the fields together will make the fields appear in a section of their own in the view tab and the edit form. E.g. In your fields.ini file: <code> [address] group=address_info [city] group=address_info [state] group=address_info [country] group=address_info [postal_code] group=address_info </code> ===Configuring the Group as a Whole=== You can also configure your group in the fields.ini file by adding a '''fieldgroup:NAME''' section, where '''NAME''' is the name of the group. E.g. <code> [fieldgroup:address_info] label="Address Information" description = "Please enter your address information below" </code> ====See also:==== * [[fields.ini file]] - Scroll down to the '''Field Groups''' section. en 0 encryption 29 encryption ==encryption [[fields.ini file]] directive== The '''encryption''' directive is meant to be used on password fields only. It specifies that a certain type of encryption is to be used in the storing of values in this field. For example, many PHP/MySQL applications use MD5 encryption to store their passwords. If you want your Xataface application to be able to use the same users tables, then you'll need to specify the '''encryption''' directive for the password field. ===Possible Values=== {| class="listing listing2" |- ! Value ! Meaning ! Version |- | md5 | MD5 encryption | 0.6 |- | sha1 | SHA1 encryption | 1.0 |- | encrypt | MySQL encrypt function | 1.0 |- | password | MySQL password encryption | 1.0 |} ===E.g. in the users table [[fields.ini file]]=== <code> [password] encryption=md5 </code> en 0 modules 30 Xataface Modules [[toc]] Xataface provides a number of hooks that allow developers to create modules to extend its functionality. This page lists a handful of the currently available modules. * [[ShoppingCart|Shopping Cart]] - Converts your application into a shopping cart. * [[Filemaker]] - Export record sets as Filemaker XML. * [[DataGrid|Data Grid]] - Editable Datagrid. * [[Email]] - Convert your database into a email list. Send email to any found set. * [[reCAPTCHA module]] - A reCAPTCHA module to add CAPTCHA support to your Xataface forms. * [[XataJax]] - Platform for building Web 2.0 AJAX applications with Xataface. Will be a standard component for Xataface starting with version 1.3. ==Module Installation== You can add modules in either: # DATAFACE_PATH/modules directory (since 1.0) # DATAFACE_SITE_PATH/modules directory (since 1.3) Modules in the DATAFACE_SITE_PATH directory will supersede modules in the DATAFACE_PATH/modules directory (since 1.3). To activate a module for your application you also need to add an entry to the [[_modules]] section of your [[conf.ini file]]. Each module will come with its own installation instructions. ==Authentication Modules== Modules to add alternative authentication methods are added to the modules/Auth directory. ==Developing Your Own Modules== See [[Module Developers Guide]]. modules, captcha en 0