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 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 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 __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 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 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 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 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 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 ShoppingCart 31 ShoppingCart ==Xataface Shopping Cart Module== [[toc]] Status: Under development Current Version: 0.2 ===Synopsis=== Add a shopping cart to your xataface application. You can treat any record as a product that can be sold. Includes Paypal connectivity, shipping calculation, and more. ===Requirements=== * Xataface 1.0 or higher * PHP 5 or higher * MySQL 4.1 or higher ===Installation Instructions=== # Download the ShoppingCart module, extract it, and place the ShoppingCart directory in your Xataface modules directory. (i.e. /path/to/xataface/modules/ShoppingCart). # Add the following line to the [_modules] section of your [[conf.ini file]]:<code> modules_ShoppingCart=modules/ShoppingCart/ShoppingCart.php </code> # Add the following to the beginning of your [[index.php file]]:<code> function __autoload($class){ if ( $class == 'ShoppingCart' ) require_once 'modules/ShoppingCart/lib/ShoppingCart/ShoppingCart.class.php'; } </code> # In the [[fields.ini file]] for any table whose records you wish to represent items for sale, add the following:<code> [__implements__] InventoryItem=1 </code> # Specify which fields should be used for the item description, price, width, height, length, and weight in the [[fields.ini file]] for each table whose records you wish to represent items for sale by adding the following directives to the appropriate fields:<code> ShoppingCart.description=1 ShoppingCart.unitPrice=1 ShoppingCart.weight=1 ShoppingCart.width=1 ShoppingCart.height=1 ShoppingCart.length=1 </code> E.g. if your table has a field named ""price"" that you want to represent the unit price, you would have something like:<code> [price] ShoppingCart.unitPrice=1 </code> The shopping cart module will make its best guess on which fields to use for these values if they are not explicitly specified. # Specify the paypal account where money should be deposited by adding the following to your application's [[actions.ini file]]:<code> [view_cart] paypal.account="youremail@example.com" </code> ===Usage Instructions=== Once the Shopping Cart module is installed you can: # Add items to your shopping cart # View your cart contents # Checkout and pay with paypal ====Adding Items to the Cart==== In the View tab of any salable record, you'll notice a little block on the left side of the page with the heading "Add Item to Cart". This includes a field to specify the quantity and a button to add the item to the shopping cart. ====Viewing Cart Contents==== The Shopping Cart module automatically introduces an action to view the cart contents. This action is named "view_cart". Hence you can always view the cart contents by entering the URL: index.php?-action=view_cart . ====Checking Out==== # View the cart contents. # Click "Check out" # This will take you to a paypal page to pay for your items. ==Actions== This module adds the following actions to your application. {| class="listing listing2" |- ! Name ! Content-type ! Description ! Version |- | checkout | text/html | Sends user to paypal to pay for the contents of their cart. | 0.1 |- | calculate_shipping | text/html | Calculates the shipping charges for the cart. | 0.1 |- | add_to_cart | text/html | Adds an item to the cart. | 0.1 |- | clear_cart | text/html | Empties the shopping cart. | 0.1 |- | get_shipping_provinces | text/json | Returns JSON array of provinces for a given country. | 0.1 |- | invoices | text/html | Displays the current user's invoices. | 0.1 |- | payment_complete | text/html | Page that is displayed after a successful payment on paypal. | 0.1 |- | paypal_ipn | none | Handles paypal events such as successful payments. | 0.1 |- | refresh_shipping_methods | text/html | Refreshes the shipping methods available to the system. | 0.1 |- | set_shipping_method | text/html | Sets the selected shipping method to a particular method. | 0.1 |- | view_cart | text/html | View the cart contents. | 0.1 |} ==Blocks and Slots== This module adds the following blocks and slots to your applications. {| class="listing listing2" |- ! Name ! Description ! Version |- | shipping_method | A block with a form to select the shipping method. | 0.1 |- | add_to_cart | A block with a form to add a record/item to the shopping cart. | 0.1 |} ==Application Delegate Class Hooks== You can modify the shopping cart behavior by defining the following methods to the application delegate class. {| class="listing listing2" |- ! Name ! Description ! Version |- | isShippingMandatory | Returns a boolean value indicating whether the user must select a shipping method. | 0.1 |- | getDefaultShippingMethod | Returns a string with the name of the default shipping method to be used. | 0.1 |} ==Table Delegate Class Hooks== You can modify the behavior of the shopping cart by defining the following methods to the delegate class of any table that implements the InventoryItem ontology (i.e. any table that is to be used to store products that can be added to the cart). {| class="listing listing2" |- ! Name ! Description ! Version |- | field__taxes | A calculated field that returns an associative array of all applicable taxes for a product. | 0.1 |} ==Internal Storage== This module creates the following tables to store its data: ===dataface__invoices=== The dataface__invoices table stores the actual invoices for purchases made. An invoice is automatically created as soon as the user "checks out". {| class="listing listing2" |- ! Column Name ! Data Type ! Description ! Version |- | InvoiceID | int(11) | Auto incrementing primary key for the invoice. | 0.1 |- | dateCreated | datetime | The date that the invoice was created. | 0.1 |- | dateModified | datetime | The date that the invoice was last modified | 0.1 |- | status | enum | The status of the invoice (either PENDING, PAID, or APPROVED). | 0.1 |- | amount | decimal(10,2) | The total amount on the invoice. | 0.1 |- | paymentMethod | varchar(32) | The name of the payment method used. | 0.1 |- | referenceID | varchar(64) | ?? | 0.1 |- | username | varchar(32) | The username of the user who owns this invoice. | 0.1 |- | firstName | varchar(32) | The first name of the payer. | 0.1 |- | lastName | varchar(32) | The last name of the payer. | 0.1 |- | address_name | varchar(100) | The name on the shipping address. | 0.1 |- | address1 | varchar(100) | The shipping address line 1. | 0.1 |- | address2 | varchar(100) | The shipping address line 2. | 0.1 |- | city | varchar(40) | The shipping address city. | 0.1 |- | province | varchar(2) | The shipping province or state. | 0.1 |- | country | varchar(2) | The shipping country. | 0.1 |- | postalCode | varchar(32) | The shipping postal code. | 0.1 |- | shipping_method | varchar(50) | The name of the shipping method to use. | 0.1 |- | phone | varchar(32) | The phone number of the payer. | 0.1 |- | email | varchar(127) | The email address of the buyer. | 0.1 |- | data | text | Serialize shopping cart data. | 0.1 |} ===dataface__shipping_methods=== Stores the available shipping methods. {| class="listing listing2" |- ! Column Name ! Data Type ! Description ! Version |- | shipping_method_id | int(11) | Auto increment ID for a shipping method. | 0.1 |- | shipping_method_name | varchar(50) | The name of the shipping method. | 0.1 |- | shipping_method_label | varchar(100) | The label for the shipping method (displayed to the user). | 0.1 |- | shipping_method_enabled | tinyint(1) | Whether or not this shipping method is currently enabled. | 0.1 |- | shipping_method_module | varchar(32) | The name of the handler that this shipping method belongs to. | 0.1 |} ==Payment Handlers== Information about payment handlers to be added here. ==Shipping Handlers== The Shopping Cart module is itself modular, allowing you to develop custom shipping handlers for different types of shipping. A shipping handler is responsible for calculating shipping costs to a destination address. Currently only a UPS shipping handler has been created, but it is not difficult to create other handlers. ===Shipping Handler Public Interface=== {| class="listing listing2" |- ! Method ! Description ! Version |- | calculateShipping | Calculates the shipping cost for the current shopping cart, and adds the shipping cost to the cart as a line item. | 0.1 |- | getInfo | Returns an array of shipping methods that can be handled by this handler. | 0.1 |} en 0 DataGrid 32 DataGrid ==Xataface DataGrid Module== Created by Steve Hannah, [http://weblite.ca Web Lite Solutions Corp.] ===Synopsis=== The Xataface DataGrid module uses the Ext DataGrid component (http://extjs.com) to add an editable grid component to your Xataface application. [[toc collapse=0]] ===Requirements=== * PHP 4.3+ * MySQL 4.1+ * Xataface 0.8+ ===License=== This module is distributed with ExtJS 2.2, which is distributed under the GPL v 3 (http://extjs.com/products/license.php). In order to be compatible with the ExtJS license, this module is also distributed under the terms of the GPL v3 (http://www.gnu.org/copyleft/gpl.html). ===Demo Video=== <nowiki> <embed src="http://media.weblite.ca/lib/flvplayer.swf" width="640" height="500" bgcolor="#FFFFFF" type="application/x-shockwave-flash" pluginspage="http://www.macromedia.com/go/getflashplayer" flashvars="file=http%3A%2F%2Fs3.amazonaws.com%2Fweblite_media%2FDataGrid-640x480.flv&image=http%3A%2F%2Fmedia.weblite.ca%2Ffiles%2Fphotos%2FDataGrid-640x480.flv.jpg&showdigits=true&autostart=false" /> </nowiki> ===Screenshots=== Click on image to enlarge <nowiki> <script language="javascript" type="text/javascript" src="http://media.weblite.ca/index.php?-action=gallery&-table=files&categories=8&-cursor=0&-skip=0&-limit=30&-mode=list&-photo_max_width=640&--format=js"></script> <div style="clear:both">&nbsp;</div> </nowiki> ===Demo=== # LibrarianDB Demo: http://demo.weblite.ca/apps/librariandb/index.php?-table=books&-action=DataGrid_view , '''Log in with username "admin" and password "password"''' ===Download=== * [https://sourceforge.net/project/platformdownload.php?group_id=250381 DataGrid-0.2] * SVN Repository: http://weblite.ca/svn/dataface/modules/DataGrid ===Installation=== # Download and extract the DataGrid directory into your xataface/modules directory. # Add the following line to the [_modules] section of your application's [[conf.ini file]]:<code> modules_DataGrid=modules/DataGrid/DataGrid.php </code> # Ensure that your [[permissions]] are set up appropriately to allow your users to access the grid action (see next section). ===Setting Up Permissions=== This module defines the following [[permissions]]: * DataGrid:view_grid - Permission to view the data grid for a table. * DataGrid:create_grid - Permission to create a new data grid * DataGrid:edit_grid - Permission to edit an existing data grid * DataGrid:update - Permission to update records via the grid * DataGrid:manage_grids - Permission to access the datagrid control panel In order for a user to access/use the grid he must be granted at least the Datagrid:view_grid and DataGrid:update [[permissions]]. Both of these [[permissions]] are included in the following system roles by default: * EDIT * EDIT AND DELETE * DELETE * ADMIN * MANAGER And of course these [[permissions]] are included with the call to Dataface_PermissionsTool::ALL() . If you have assigned your own custom roles and want to enable access to the grid, you can simply add the following to your role definition in your [[permissions.ini file]]: <code> [MY ROLE] DataGrid:view_grid=1 DataGrid:update=1 </code> If you want to explicitly disable the grid for a role, you can extend the role and deny those same [[permissions]]: <code> [MY ROLE extends MY ROLE] DataGrid:view_grid=0 DataGrid:update=0 </code> ===Usage=== Once installed, log in as a user that has permission to access the grid. You should notice a new tab along with "details", "list", and "find", called "grid". Click on the "grid" tab to access the grid. You can double click on any field to edit it. Modified fields will be marked in red, and automatically saved every 5 seconds - after the changes are saved the field is no longer marked in red. ===Limitations=== Currently only fields with the following widget types are available to be edited in the grid: # text # textarea # select # date/datetime/time Other types of fields will simply not be included in the grid. ===Support/Questions=== Visit the Xataface forum at http://xataface.com/forum en 0 after_action_new 33 after_action_new ==after_action_new trigger== [[toc]] This trigger is called after the '''new''' action is successfully completed. This trigger can be defined in the table [[Delegate class methods|delegate class]] and is often used to redirect to a particular page after a new record is submitted. This should not be confused with the [[afterInsert]] trigger, which is executed after a record is inserted into the database (this can occur multiple times per request). The after_action_new trigger is only executed once after the 'new' action has been successfully completed. i.e. a maximum of once per request. ===Signature=== <code> function after_action_new($params=array()){ ... } : return void </code> ====Parameters==== This method takes a single associative array as a parameter. This array includes the following keys: * '''record''' - The [http://dataface.weblite.ca/Dataface_Record Dataface_Record] object that was just inserted. ===Examples=== ====Example 1: Redirect to the view tab for the inserted record==== <code> function after_action_new($params=array()){ $record =& $params['record']; header('Location: '.$record->getURL('-action=view').'&--msg='.urlencode('Record successfully inserted.')); exit; } </code> en 0 widget:editor 35 widget:editor ==widget:editor fields.ini directive== Return to [[fields.ini file]] [[toc]] The widget:editor directive is applicable in the [[fields.ini file]]. It specifies the type of HTML editor that should be used. This directive is only used when [[widget:type]] is set to [[widget:type htmlarea|htmlarea]]. Xataface currently supports FCKEditor, TinyMCE, and NicEdit. ===Allowed Values=== {| class="listing listing2" |- ! Value ! Description ! Version |- | fckeditor | Use [http://www.fckeditor.net/ FCKEditor]. This is the default value. | all |- | tinymce | Use [http://tinymce.moxiecode.com/ TinyMCE editor]. | 0.6 |- | nicedit | Use [http://www.nicedit.com/ NicEdit]. | 1.0.5 |} ===Examples=== ====Example 1: Using FCKEditor==== Given a field 'content' that you wish to be able to edit with FCKEditor, you would have the following section in your [[fields.ini file]]: <code> [content] widget:type=htmlarea widget:editor=fckeditor </code> Note that since FCKEditor is the default editor, the above would give the same result as: <code> [content] widget:type=htmlarea </code> ====Example 2: Using TinyMCE==== Further from example 1, if we wanted to use TinyMCE editor, we would change our directive to: <code> [content] widget:type=htmlarea widget:editor=tinymce </code> ====Example 3: Using NicEdit==== Further from example 1: <code> [content] widget:type=htmlarea widget:editor=nicedit </code> ==Enabling Image Uploads== By default image uploads are disabled in these WYSIWYG editors. ===Enabling Image Uploads in FCKEditor=== # Create a directory named ''uploads'' inside your application directory. e.g.<code> cd /path/to/myapp/uploads </code> # Make the ''uploads'' directory writable by the webserver. e.g. <code> chmod 777 /path/to/myapp/uploads </code> # Edit the ''lib/FCKeditor/editor/filemanager/connectors/php/config.php'' file inside your ''xataface'' directory so that:<code> $Config['Enabled'] = true ; $Config['UserFilesPath'] = '/url/to/myapp/uploads/' ; // The path portion of the URL to your uploads directory. // e.g. if your uploads directory is accessible at // http://example.com/myapp/uploads, then this value should // be /myapp/uploads/ $Config['UserFilesAbsolutePath'] = '/path/to/myapp/uploads/' ; // The absolute file system path to your uploads directory. // e.g. if your uploads directory is located at // /home/myhome/www/myapp/uploads, then this value should be // /home/myhome/www/myapp/uploads </code> # Now when you click on the "Add Image" link in your HTML editor, it will allow you to upload images and browse existing uploaded images. en 0 about 36 about ==About Xataface== [[toc]] Xataface is a flexible and shapable skin that sits on top of MySQL, making it accessible to every-day users. It automatically generates the appropriate forms, lists, and menus for a user to interact with the database without having to know any SQL. It is a full-featured Web application framework, and gives developers the flexibility to customize the features and behavior of their application via configuration files (using the simple INI-file syntax), templates, and plug-ins. A generic application with no customizations is completely functional, but the developer is free to customize things at his leisure. ===Who is Xataface for?=== Xataface is for web developers and database administrators who would like to build a front-end for their MySQL database. However the resulting applications are targeted at non-technical users such as secretaries. ===Requirements=== ====Xataface 1.1.x and below:==== * MySQL 3.23+ * PHP 4+ Some advanced features require MySQL version 4.1 or higher. ====Xataface 1.2 and higher==== * MySQL 3.23+ * PHP 5+ Some advanced features require MySQL version 5 or higher. ===At a Glance: Your first App=== # Create a directory for your app. # Copy the ''xataface'' directory inside your application directory. # Create a configuration file named ''conf.ini'' in your application directory with your database settings:<code> [_database] host=localhost name=mydb user=me password=mypass [_tables] ; A list of tables to include in your application's menu ; These tables must already exist in your database people=Profiles news=News Articles </code> # Create an .htaccess file in your application directory to prevent access to your ''conf.ini'' file:<code> <FilesMatch "\.ini$"> Deny from all </FilesMatch> </code> # Create a PHP script in your application directory as an access point for your app. We'll call it ''index.php'':<code style="php"> <?php // Include the Xataface API require_once 'xataface/dataface-public-api.php'; // Initialize Xataface framework df_init(__FILE__, 'xataface'); // first parameter is always the same (path to the current script) // 2nd parameter is relative URL to xataface directory (used for CSS files and javascripts) // Create a new application $app =& Dataface_Application::getInstance(); // Display the application $app->display() </code> # You're done. Your app is ready to use! This is just the beginning, though. There is no limit to the customizations you can make on your application. Read the [http://xataface.com/documentation/tutorial/getting_started Getting Started Tutorial] for more information on developing applications with Xataface. ===Product Comparison=== Xataface fits a niche that is not well covered by existing apps/frameworks. Xataface is '''NOT''': * A database administration system like PHPMyAdmin * Simply a software library/Framework like PHPCake * Simply a content management system like Drupal * A code generator Xataface is a framework, but it is not a typical framework. Most frameworks require a substantial amount of development before you get a usable application. Xataface, on the other hand, provides you with a fully-functional application with as little as 4 lines of PHP code. It doesn't generate any code so it is easy to maintain your application and expand on it later. As a development framework, Xataface most closely resembles Django, a python framework for building data-driven applications. As an application, Xataface most closely resembles Filemaker, a popular relational database that makes it easy for the end user to create layouts and manage their data. ===Features=== ====General==== * '''Out-of-the-box Database Front-end''' - With as little as 4 lines of PHP code, you can have a full-featured web application for your database. * '''Simple, Intuitive User interface''' - Default application is consistent and simple to use. There is a 'tables' menu, to select a table, and each table has "details", "list", and "find" tabs. Very easy to navigate. * '''Powerful configuration options''' - You can configure your application details (such as widget types) using simple configuration files. * '''Extendible''' - You can modify your application as you see fit using configuration files and PHP delegate classes. * '''Hooks''' - By observing simple conventions you can extend Xataface's functionality with hooks, triggers, and events. E.g. add a function that is called after a record is inserted. * '''Permissions''' - Powerful, pluggable permissions system. * '''Authentication''' - Provides login/logout ability. You just specify which table your users are stored in. * '''Relationships''' - Tell Xataface how your tables are related to one another and it will provide you with more logical functionality for managing your data. * '''Themeable''' - Xataface uses the Smarty template engine as a base, but extends it with some powerful new features such as extendable templates and theming support. * '''Modular''' - There are several add-on modules available to extend the features of Xataface even further, and a simple API for writing your own modules. ====Editing==== * '''Automatic Form Generation''' - Automatically generates appropriate web forms to add new records and edit existing records. * '''Widgets''' - Support for many different widget types including text fields, text areas, checkboxes, select lists, html editors, grids, file uploads, and more. * '''Configurable''' - Customize forms using configuration files and delegate classes. * '''Personalizable''' - Show different forms to different users depending on their permissions and preferences. * '''Add Related Records''' - Insert records and automatically track their relationships to other tables. * '''Editable Data Grid''' - Manage your data like a spreadsheet using the DataGrid module. * '''Copy''' - Copy sets of records. * '''Update Found Set''' - Update multiple records with one swipe. * '''Fine-grained Permissions''' - Assign editing permission based on table, record, or field. * '''File uploads''' - Support for file uploads with storage either in a BLOB field or on the file system. * '''Delete''' - Delete single record or delete the current found set. ====Searching==== * '''Automatic Find Form''' - The Xataface find form allows you to search a table on any field. * '''Range Searches''' - Search for records matching values in a certain range (e.g. find all people between the ages of 20 and 30). * '''Exact Matching''' - Search for exact matches. * '''Partial Matching''' - Search for fields that contain a keyword phrase. * '''Multi-field search''' - There is always a simple search field accessible which searches all fields in the current table. E.g. a search for "Tom" would match any record in the current table that contained the phrase "Tom" in any of its columns. * '''Related Record Searches''' - Find records that contain related records matching a search term. (E.g. find all people who got an 'A' in a particular course). ====Browsing==== * '''Automatic Details View''' - Each record has user-friendly details page to browse the contents of the record. * '''AJAX Record Tree''' - Provides optional AJAX record tree to browse the data in your database by relationships. * '''Expand for More''' - Quickly expand a row in list view to see the full record details. * '''Drag and Drop Reordering''' - The details view for a record can be broken up into related sections. Users can reorder these sections via drag and drop. ====Exporting==== * '''RSS''' - Support for RSS 1.0, 2.0 and Atom feeds of any found set. * '''XML''' - Export any found set as XML so that the data can be interchanged with other products (e.g. desktop publishing suites). * '''CSV''' - Export any found set to CSV (comma-separated-value) to open in a spreadsheet application like Excel. * '''JSON''' - Export any found set to JSON. This feature makes Xataface a good choice for serving the next generation of Web 2.0 AJAX applications. ====Internationalization==== * '''String Internationalization''' - Xataface fully supports internationalizing your application. It provides you with language files to provide translations of all of the strings and labels in your application. * '''Dynamic Data Translation''' - Xataface even allows you to internationalize your existing database data without having to change your database structure. * '''Templates''' - Includes a {translate} tag for Smarty templates to easily translate template text. * '''In the background''' - You can use Xataface to internationalize any PHP/MySQL website without having to make any drastic changes to your existing code. Just include Xataface as a library and use some of its useful internationalization functions to convert your application into multiple languages. * '''Translation Form''' - If multiple languages are enabled, Xataface provides a simple translation form to translate content between languages. * '''Translation Status Tracking''' - Track the status of translations to mark whether they need to be retranslated. ====Importing==== * '''Import Filter API''' - Using delegate classes, it is easy to define an import filter to import any type of data into the database. * '''User Preview''' - User can preview imported data before confirming that he wants to import it. ====History==== * '''Optional History Support''' - If history is enabled, all changes made to any data are recorded. * '''Undo/Redo Support''' - Easily revert to an earlier version of a record. * '''View Snapshot''' - Browse previous versions of records. * '''View Diffs''' - View differences/changes between versions of records, similar to a wiki. ====Caching==== * '''Output cache''' - Supports output cache that caches output of pages to improve performance dramatically for busy sites. Cache is automatically refreshed whenever changes are made to tables that are used to generate the page. * '''APC Support''' - If APC (Alternate PHP Cache) is installed, Xataface will automatically use it to cache table configuration information. This tends to increase performance by about 20%. ====Security==== * '''Fine-grained permissions''' - Define permissions to the entire application, a single table, by the record, or by the field. Each feature has an associated permission that can be allowed or disallowed on a per-user basis. * '''Cascading Permissions''' - You can very restrictive permissions to the application as a whole and then apply more permission permissions to specific tables or fields that you want uses to be able to access. Table permissions override application permissions. Field permissions override field permissions. * '''Role-based permissions''' - You can define """roles""" which are sets of permissions that can be assigned to users. * '''Extendable Permissions Model''' - You can easily define your own permissions and roles, extending existing roles, custom for your application. * '''Built-in Authentication''' - It is easy to set up login/logout features for your application. Just tell Xataface which table you store your user records in, and Xataface will do the rest. * '''Password Encryption''' - Xataface supports and is compatible with most of the standard password encryptions including MD5, SHA1, and MySQL Password. * '''Pluggable Authentication''' - Easy to create your own authentication plugins in case you want to implement your own custom authentication. * '''CAS''' - Module available for the Yale CAS (Central Authentication Service). * '''LDAP''' - LDAP authentication module available. * '''HTTP''' - Optional HTTP login support. Standard login uses a web-based login form, but you can also use HTTP headers for authentication. ====Relationships==== * '''Powerful Relationship Model''' - It is easy to define relationships between your tables using simple configuration files. Syntax is simple, but the results are powerful. * '''Add New Related Record''' - Create a new record and add it to a parent record's relationship at the same time. (E.g. create a new "course" record and add it to a teacher's list of taught courses). * '''Add Existing Related Record''' - Add an existing record to a parent record's relationship. (e.g. Add an existing course record to a teacher's list of taught courses). * '''Remove related record''' - Remove a record from a relationship. (e.g. remove a course record from a teacher's list of taught courses). ====API==== Xataface includes a powerful API to allow you to more efficiently work with your database. * '''Data Objects''' - Provides a simple API to work with database records. Searching, loading, saving, editing, and deleting records supported. ====Templates==== * '''Smarty Template Engine''' - Xataface uses the Smarty template engine as a base, one of the fastest PHP template engines available. * '''Template Inheritance''' - You can create templates that inherit from other templates, and replace the content in specified "slots" of the original template. This drastically increases template reuse and development productivity. * '''Cascading Support''' - All system templates are stored in the Dataface/templates directory. Your application can have its own templates directory where you can place templates to override system templates. All parts of the system can be overridden without modifying the original templates themselves. ====Themes==== Xataface includes a powerful themes API. You can create multiple looks for your application and switch between them with a simple configuration setting. ====REST Support==== Xataface's intelligent URL protocols make it a powerful platform for REST web services. You can specify a query directly in the URL to obtain the exact found-set that you want. This is also very useful in standard web applications because you can easily create links to desired parts of your application. Or you can use Xataface to provide missing functionality in your existing applications and link only to the parts of your Xataface app that you need. ===History=== Xataface (formerly Dataface) was originally created by Steve Hannah in 2005 to increase productivity created data-driven applications for Simon Fraser University. He came from faculty that used Filemaker extensively for their databases. As a PHP developer he preferred open technologies like MySQL as they provided fewer "road blocks", but it was hard to deny the benefits of filemaker when it came to providing users with an instant user interface for their databases. It was difficult to justify spending 3 weeks building an administration console for a MySQL application when it could have been done in 3 hours had Filemaker been used. Xataface was designed to: # Increase developer productivity to the point where MySQL applications could be created as quickly as Filemaker applications without sacrificing usability and functionality. # Add an abstraction over a database to make is accessible to non-technical users. The secretary shouldn't need to know SQL in order to interact with a database. # Test the limits of PHP and MySQL As it was built with the intention of providing an alternative for Filemaker, many implementation details and concepts have been inspired by Filemaker. For example, Xataface's implementation of relationships is very similar to Filemaker relationships; as are valuelists. In addition the method of searching follows many Filemaker conventions. The first application built with Xataface was a group content management system for the Faculty of Applied Sciences at Simon Fraser University. This system was used by faculty to manage their research profiles and their research groups. The database itself pre-existed the Xataface implementation. Xataface was used to build a new administrative interface to the system. Since then Xataface has been used to develop many systems for SFU including website content management systems, auctions, event registration systems, research databases, shopping carts, and more. ==Where to go from here== * [http://xataface.com/documentation/tutorial/getting_started Getting Started Tutorial] * [http://xataface.com/videos Watch Demonstration Videos of Xataface] * Sign up for the Xataface Maillist to receive free updates and development tips. (See sign-up form in upper left of the page). en 0 Drag_and_Drop_Reordering_of_Relationships 39 Drag_and_Drop_Reordering_of_Relationships ==Drag and Drop Reordering of Related Records in Xataface== One powerful aspect of Xataface is its abstraction of relationships between tables. Once you define a relationship users can browse related records, add new and existing related records, and delete related records to or from the relationship. For example, suppose you have a ''people'' table and a ''publications'', you could define a relationship from ''people'' to ''publications'' to identify publications that belong to a particular person. The table's might look something like: ===people table=== {| class="listing listing2" ! person_id ! person_name |- | 1 | John Smith |- | 2 | Ben Stein |- | 3 | Harley Davidson |- | 4 | Trevor Linden |} ===publications table=== {| class="listing listing2" ! publication_id ! owner_id ! pub_title |- | 1 | 2 | Introduction to widgetry |- | 2 | 2 | Intermediate Widgetry |- | 3 | 2 | Advanced Widgetry |- | 4 | 3 | How to play the violin |} See http://xataface.com/documentation/tutorial/getting_started/relationships for an introduction to relationships in Xataface, and how to define them. Our relationship definition in the ''people'' table's [[relationships.ini file]] might look something like: <code> [my_pubications] publications.owner_id="$person_id" </code> This indicates that any publication whose ''owner_id'' column matches the current ''people'' record's ''person_id'' field is considered part of the relationship. Using our example data above, this would mean that Ben Stein's ''my_publications'' relationship would contain 3 records: "Introduction to Widgetry", "Intermediate Widgetry", and "Advanced Widgetry". In our Xataface application this means that in the "Details" tab for the "Ben Stein" record, we would see a sub-tab ''My Publications'' which would contain a list of Ben Stein's publications. ===Adding Publication Order=== Now that we have our relationship, what if Ben Stein wants his publications to appear in a particular order whenever they are displayed to the user. Xataface allows us to specify an "order" column for our relationship, which will cause the related records to be orderable by drag and drop (if the user has appropriate permissions). # Add a field to the ''publications'' table named "pub_order" # Change the relationship definition in the people table's [[relationships.ini file]] to tell Xataface to use the pub_order field for sorting:<code> [my_pubications] publications.owner_id="$person_id" metafields:order="pub_order" </code> Now load up your application and navigate to the "My Publications" tab for the "Ben Stein" record. Now you're able to drag and drop rows in your application to reorder them. ===Permission to Reorder Records=== Only users who have been assigned the ''reorder_related_records'' permission for a record's relationship are allowed to reorder records of that relationship. By default the ''EDIT'' role contains this permission, as does any role that permits the user to edit the parent record of the relationship. The ''READ ONLY'' role does not contain this permission. If you want to explicitly deny this permission for all relationships in a record, you can simply set this permission to 0 in the associated role within your application's [[permissions.ini file]]: <code> [MY ROLE] reorder_related_records=0 </code> For more information about permssions see: * [[permissions.ini file|The Permissions.ini file reference]] * [http://xataface.com/documentation/tutorial/getting_started/permissions Introduction to Permissions] ===Loading Related Records using the Xataface API=== The ordering that is set via this drag and drop method is also honoured by the Xataface API when fetching related records. You can load related records using the [http://dataface.weblite.ca/getRelatedRecordObjects getRelatedRecordObjects] method of the [http://dataface.weblite.ca/Dataface_Record Dataface_Record] class. E.g. <code> $benStein = df_get_record('people', array('person_id'=>2)); $pubs = $benStein->getRelatedRecordObjects('my_publications'); foreach ($pubs as $pub){ echo $pub->val('pub_title').'<br/>'; } </code> This will list up to the first 30 publications of Ben stein in the order prescribed by our drag and drop ordering scheme. en 0 getFeedItem 41 getFeedItem ==getFeedItem() Delegate Class Method== [[toc]] ===Synopsis:=== The getFeedItem() method of a table [[Delegate class methods|delegate class]] returns an associative array of parameters for a record as it should appear as part of an [[Introduction_to_RSS_Feeds_in_Xataface|RSS feed]]. An RSS feed item consists of the following components: # '''title''' - The title of the record as it appears in the RSS feed. # '''description''' - The description of the record for the RSS feed. This is really the body of the RSS feed item. # '''link''' - The linkback URL if users want to know more about the record. # '''date''' - The date that the record was posted/modified. # '''author''' - The name of the person who posted this record. # '''source''' - URL to the site where record originated from. ===Parameters=== # '''Dataface_Record''' &$record - The record that is being represented in an RSS feed. ===Return Value=== The getFeedItem() method returns an associative array with the components of the RSS feed. This array does not need to contain all possible keys, or even any keys. Any keys that are omitted will simply use default values in the RSS feed. The array may contain the following keys: {| class="listing listing2" ! Name ! Description ! Version |- | title | The record title as it appears in RSS feeds. If this is omitted, the RSS feed will simply use the output of [http://dataface.weblite.ca/Dataface_Record Dataface_Record's] [http://dataface.weblite.ca/getTitle getTitle()] method. | 1.0 |- | description | The record description. This is used in the main body of the RSS feed. If this is omitted, the RSS feed will use an HTML table that shows all of the field data in the record. This value can also be overridden using the [[getRSSDescription]] method of the delegate class. | 1.0 |- | link | The URL to this record. If this is omitted it just points to the ''view'' tab for this record. However you can direct it anywhere you like. When the user clicks on the "More Info" link in his RSS reader it will direct him to this link. | 1.0 |- | date | The date that this record was posted or last modified. This is the date that an RSS reader will use to decide if it has already loaded the record yet. If this is omitted it will try the [http://dataface.weblite.ca/Dataface_Record Dataface_Record's] [http://dataface.weblite.ca/getLastModified getLastModified()] method to obtain the last modified date of the record. Failing that, it will use [http://dataface.weblite.ca/Dataface_Record Dataface_Record's] [http://dataface.weblite.ca/getCreated getCreated()] method to try to obtain the creation date of the record. This date should be a unix timestamp. | 1.0 |- | author | The name of the user who posted this record. If this is omitted, then it will try to use [http://dataface.weblite.ca/Dataface_Record Dataface_Record's] [http://dataface.weblite.ca/getCreator getCreator()] method. Failing that, it will use the value of the ''default_author'' parameter in the ''[_feed]'' section of the [[conf.ini file]]. If that is not defined, then it simply uses the string "Site Administrator". | 1.0 |- | source | The source URL where the feed is to have originated. If none is specified, then it will use the value of the ''source'' parameter in the ''[_feed]'' section of the [[conf.ini file]]. Failing that, it will simply use the URL to the application. Note that you can alternatively define this value using the [[getFeedSource]] method. | 1.0 |} ===Example=== <code> function getFeedItem(&$record){ return array( 'title' => "News Item: ".$record->getTitle(), 'description' => $record->display('News Body'), 'link' => $record->getPublicLink(), 'date' => strtotime($record->val('last_modified')), 'author' => $record->val('posted_by'), 'source' => 'http://www.example.com' ); } </code> '''Note that RSS feeds will work perfectly well without defining this method. This just allows you to customize one or more parameters of the RSS feed'''. ===See Also:=== * '''[[getFeed]]''' - A delegate class method available to both the [[Application Delegate Class]] and the [[Delegate class methods|table delegate classes]] to configure the RSS feed as a whole (not just for an individual item in the RSS feed. * '''[[getRelatedFeed]]''' - A [[Delegate class methods|delegate class method]] available to both the [[Application Delegate Class|application delegate class]] and the [[Delegate class methods|table delegate classes]] to configure the [[Introduction to RSS Feeds in Xataface|RSS feed]] for a related records list. * '''[[getRSSDescription]]''' - A delegate class method to override the description that appears for a particular record in an RSS feed. (The same as the ''description'' parameter of the [[getFeedItem]] method. * '''[[Introduction to RSS Feeds in Xataface]]''' - An overview of Xataface's RSS feed support. en 0 getFeed 42 getFeed ==getFeed() Delegate Class Method== [[toc]] ===Synopsis:=== The getFeed() method of a table [[Delegate class methods|delegate class]] or [[Application Delegate Class|application delegate class]] returns an associative array of parameters to configure the [[Introduction_to_RSS_Feeds_in_Xataface|RSS feed]] for a particular table . An RSS feed consists of the following components: # '''title''' - The title of the RSS feed as it should appear in the subscribers' feed list. # '''description''' - Describes the RSS feed. # '''link''' - A link to the RSS feed # '''syndicationURL''' - The URL to this RSS feed's site. ===Parameters=== # '''array''' $query - The HTTP query. Contains information like the current table, current action, and search parameters. This allows you to customize your RSS feed depending on the user's query parameters. ===Return Value=== The getFeed() method returns an associative array with the components of the RSS feed. This array does not need to contain all possible keys, or even any keys. Any keys that are omitted will simply use default values in the RSS feed. The array may contain the following keys: {| class="listing listing2" ! Name ! Description ! Version |- | title | The title for the RSS feed. If this omitted, it will try to use the ''title'' directive of the ''[_feed]'' section of the [[conf.ini file]]. Failing that, it will try to generate an appropriate title for the feed depending on the current query. | 1.0 |- | description | A Description for this RSS feed. If this is omitted, it will try to use the ''description'' directive of the ''[_feed]'' section of the [[conf.ini file]]. | 1.0 |- | link | A link to the source page of the RSS feed. If this is omitted, it will try to use the ''link'' directive of the ''[_feed]'' section of the [[conf.ini file]]. | 1.0 |- | syndicationURL | A link to the source page of the RSS feed. If this is omitted, it will try to use the ''syndicationURL'' directive of the ''[_feed]'' section of the [[conf.ini file]]. | 1.0 |} ===Example=== <code> function getFeed(&$query){ return array( 'title' => "RSS feed for the ".$query['-table']." table.", 'description' => "News and updates for automobiles", 'link' => df_absolute_url(DATAFACE_SITE_HREF), 'syndicationURL' => df_absolute_url(DATAFACE_SITE_HREF) ); } </code> '''Note that RSS feeds will work perfectly well without defining this method. This just allows you to customize one or more parameters of the RSS feed'''. ===See Also:=== * '''[[getFeedItem]]''' - A delegate class method available to both the [[Delegate class methods|table delegate classes]] to configure parameters for the particular items of the RSS feed. * '''[[getRelatedFeed]]''' - A [[Delegate class methods|delegate class method]] available to both the [[Application Delegate Class|application delegate class]] and the [[Delegate class methods|table delegate classes]] to configure the [[Introduction to RSS Feeds in Xataface|RSS feed]] for a related records list. * '''[[getRSSDescription]]''' - A delegate class method to override the description that appears for a particular record in an RSS feed. (The same as the ''description'' parameter of the [[getFeedItem]] method. * '''[[Introduction to RSS Feeds in Xataface]]''' - An overview of Xataface's RSS feed support. en 0 Calendar_Action 43 Calendar_Action ==Calendar Action== [[toc]] Xataface 1.0 includes a built-in calendar action that is disabled by default. If enabled, it allows you to view the records in any found set as a calendar of events, as follows: <nowiki> <div style="text-align:center;border: 1px solid #ccc; padding: 10px"> <img src="http://media.weblite.ca/files/photos/Picture -4.png?max_width=500" onmouseover="this.src='http://media.weblite.ca/files/photos/Picture -4.png';" onmouseout="this.src='http://media.weblite.ca/files/photos/Picture -4.png?max_width=500';"/> </div> </nowiki> ===Features=== * Monthly display * Hourly schedule for any day by clicking on it. * Show record details instantly by clicking on it in the calendar. * Recognizes dates, start and end times for records when interpreted as calendar events. * Respects searches (i.e. you can filter the records and the calendar will only show those records in the found set). ===Requirements=== Your table records should contain at least dates in order for them to be interpreted as events that can be placed in a calendar. ===Setting up the Calendar=== Suppose I have a table called ''Lessons'' that stores information about scheduled music lessons. If I want to add the calendar to this table, then I would add an ''[[actions.ini file]]'' to the ''tables/Lessons'' directory with the following contents:<code> [calendar > calendar] condition="true" </code> This overrides the calendar action which is disabled by default, and enables it for the ''Lessons'' table. Next I need to inform Xataface which fields store the event dates and times so that the records can be laid out in the calendar appropriately. (Note that if you skip this step, Xataface will make a best guess based on column types and names - but it is better to specify these explicitly). In the ''Lessons'' table I have the following fields that are relevant here: * ''lesson_date'' - A date field containing the date and start time of the event. * ''start_time'' - A time field with the start time of the lesson. We can tell Xataface to treat these fields accordingly by adding the following directives to the appropriate field sections of the [[fields.ini file]] for the ''Lessons'' table: * ''event.date=1'' - Specifies that the field stores the date of the event. * ''event.start=1'' - Specifies that the field stores the start time of the event. So in our case we'll modify the [[fields.ini file]] as follows: <code> [lesson_date] event.date=1 [start_time] event.start=1 </code> Now if we load up our application, we should now see a ''calendar'' tab along side ''list'', ''details'', and ''find'' for the ''Lessons'' table. Click on this tab to see your records displayed in a calendar. ===Using a datetime field to store both date and start time=== You can also use a single field to store both the date and start time for an event. In this case you just provide the ''event.date'' and ''event.start'' directives for the same field. For example if the ''lesson_date'' was a datetime field that marked the date and time of the lesson, we would modify our [[fields.ini]] file as follows: <code> [lesson_date] event.date=1 event.start=1 </code> ===Available Fields=== The Calendar action will look for the following pieces of information in your records: {| class="listing listing2" ! Name ! Description ! Version |- | event.date | Indicates that the field contains the date of the event. | 1.0 |- | event.start | Indicates that the field contains the start time of the event. | 1.0 |- | event.end | Indicates that the field contains the end time of the event. | 1.0 |- | event.location | Indicates that the field contains the location of the event. | 1.0 |- | event.category | Indicates that the field contains the category of the event. | 1.0 |} en 0 widget:atts 46 widget:atts ==widget:atts Directive Reference== The widget:atts directive in the fields.ini file allows any arbitrary HTML attributes to be added to any of the fields. It may also be used to specify javascript event handler functions that the widget should call upon the specified event. In particular, here are some examples of possible widget:atts directives: ===Available Widget Event Handlers=== {| class="listing listing2" |- ! name ! description ! version |- | [[field_size|widget:atts:size]] | This directive sets the length of the input area a text box field, but it does not limit the number of characters that can be entered. For example: <nowiki><br/>widget:atts:size = 50</nowiki> | ? |- | [[field_maxlength|widget:atts:maxlength]] | This directive limits the maximum number of characters that can be entered into a text box field. For example: <nowiki><br/>widget:atts:maxlength = 25</nowiki> | ? |- | [[field_style|widget:atts:style]] | This directive specifies the style (font-size, font-family, etc.) for the field. For example: <nowiki><br/>widget:atts:style = "font-size: 24pt; font-family: Apple Chancery"</nowiki> | ? |- | [[field_rows|widget:atts:rows]] | This directive specifies the number of rows for a text area field to display. For example: <nowiki><br/>widget:atts:rows = 10</nowiki> | ? |- | [[field_cols|widget:atts:cols]] | This directive specifies the number of columns for a text area input field (1 character = 1 column). For example: <nowiki><br/>widget:atts:cols = 10</nowiki> | ? |- | [[field_javascript_onchange|widget:atts:onchange]] | This directive will cause the specified javascript function to be called with the value of the field whenever its value is changed (i.e. when you change the field and tab out of it). For example: <nowiki><br/>widget:atts:onchange = "doJsFunction();"</nowiki> | ? |- | [[field_javascript_onclick|widget:atts:onclick]] | This directive will cause the specified javascript function to be called with the value of the field whenever it is clicked. For example: <nowiki><br/>widget:atts:onclick = "doJsFunction();"</nowiki> | ? |} ===Helpful tutorials=== See the bottom of this page in the Getting Started tutorial for more details on the basic directives above: [http://xataface.com/documentation/tutorial/getting_started/customizing Customizing Field labels, descriptions, and widgets] This tutorial talks about how to use the javascript directives: [http://xataface.com/documentation/how-to/custom_javascripts] en 0 visibility:fieldName 47 visibility:fieldName ==Example== <code>visibility:ConferenceID = hidden</code> This will make the ConferenceID in the relationship list view disappear. en 0