advmultiselect 183 en column:legend 182 en widget:type_textarea 60 widget:type_textarea en 0 struct 56 struct en 0 blob 55 blob en 0 Internet_Media_Manager 8 Internet Media Manager '''Manage your videos and photos all in one place''' [[toc]] ===Watch the Guided Tour (6 minutes)=== <nowiki> <embed src="http://media.weblite.ca/lib/flvplayer.swf" width="640" height="448" bgcolor="#FFFFFF" type="application/x-shockwave-flash" pluginspage="http://www.macromedia.com/go/getflashplayer" flashvars="file=http%3A%2F%2Fs3.amazonaws.com%2Fweblite_media%2Fintro_video.flv&image=http%3A%2F%2Fmedia.weblite.ca%2Ffiles%2Fphotos%2Fintro_video.flv.AbpY0Y.jpg&showdigits=true&autostart=false" /> </nowiki> ===Introduction=== The Internet Media Manager is a web-based database application that allows webmasters to centrally store their images and videos to be served on their website(s). It provides a Youtube-like interface whereby users can simply copy and paste code snippets to embed images and videos into their web pages. It also provides a photo gallery component that allows users to easily embed a gallery of images into their web pages by simply copying and pasting a snippet of javascript code. ===Purpose=== I created this application because: # I didn't want to have to resize images in Photoshop anymore before uploading them to the web. # I wanted to be able to embed videos, images, and photo galleries into my web pages without having to muck around with HTML code. IMM (Internet Media Manager) allows you to resize your photos to any size you want, and embed these resized images in your web pages by copying and pasting a snippet of HTML. Similarly it makes embedding videos and photo galleries into your website a snap. ===Features=== * Add/Edit/Delete/Categorize images and videos in a searchable database. * Import multiple images or videos at once by uploading a ZIP file. * Large file imports via FTP/SSH. * Embed video and images directly into other web pages by copying and pasting HTML snippets (like Youtube). * Resize images and videos. * FLV video support (like Youtube). * Search media by content type, category, keyword, etc.. * Includes javascript photo gallery component that can be embedded into any web page. * Amazon Simple Storage Service (S3) integration. ===Requirements=== * [http://www.php.net|PHP] 5.2+ * [http://www.mysql.com|MySQL] 4.1+ * [http://ca.php.net/gd|GD_Image_Processing_Library] * [http://ffmpeg.mplayerhq.hu/|FFMPEG] (optional - if you want to automatically generate poster images for videos). ===Download=== * [https://sourceforge.net/projects/immgr/files/|Internet Media Manager 0.3] ===Installation=== # Download the latest version from Sourceforge. # Extract the files and copy to your web server. # Point your web browser to the install.php and follow the instructions. ===Screenshots=== <nowiki> <script language="javascript" type="text/javascript" src="http://media.weblite.ca/index.php?-action=gallery&-table=files&categories=3&-cursor=0&-skip=0&-limit=30&-mode=list&-photo_max_width=500&--format=js"></script> <div style="clear:both"></div> </nowiki> ===Screencasts=== How to import multiple images at once in a ZIP archive. <nowiki><iframe title="YouTube video player" width="640" height="510" src="http://www.youtube.com/embed/0gfRJ5HkRsI" frameborder="0" allowfullscreen></iframe></nowiki> ===Support=== Visit the [http://xataface.com/forum/viewforum.php?f=12|Support_forum]. Internet Media Manager,resize photos,image gallery,photo gallery,video gallery en 0 How_to_build_a_PHP_MySQL_Application_with_4_lines_of_code 38 How to build a PHP MySQL Application with 4 lines of code '''The [http://xataface.com Xataface Application Framework] allows you to convert your existing MySQL database into a full-fledged with as little as 4 lines of code. And it's Not a code generator.''' [[toc]] This article is intended to spark interest in the [http://xataface.com Xataface Application Framework] amongst PHP developers by showing how easy it is to set up a full-featured front-end for your MySQL database. If you are a PHP developer, surly you can identify with the situation where you've built a snazzy website with PHP and MySQL but you need to create some way the website users to administer it. I.e., you need to make an administrative back-end for your users. You need to do this because PHP admin is too technical for your users, and it is an aweful lot of tedious work to create all of the necessary forms and lists for your users to edit the data themselves. ===Features for our Application=== * Create, edit and delete records using simple web forms. * Browse through database and find records without any SQL. * Lots of great widgets for editing records including html editors, select lists, grids, checkboxes, calendars and more. * Sort records. * Export result sets as CSV or XML. * Fully configurable and extendable by you to implement more [[about|features]]. ===Creating the Application=== Here are 6 steps to a full-featured front-end for your database: # Create a directory for your application on your webserver. Call it ''myapp''. # Download the latest version of [http://xataface.com Xataface] and copy it into your application directory that we just created. (i.e. ''myapp/xataface''. # Create a configuration file named ''conf.ini'' inside your application directory (i.e. ''myapp/conf.ini'') to store your database connection info:<code> [_database] host=localhost name=mydb user=username password=mypass [_tables] ;; This section lists the tables to include in your application menu table1=Label for table 1 table2=Label for table 2 </code> # Create an .htaccess (i.e. ''myapp/.htaccess'') file to prevent Apache from serving your ''conf.ini'' file:<code> <FilesMatch "\.ini$"> Deny from all </FilesMatch> </code> '''Note: If you are not using Apache as your web server you'll need to block access to the .ini files using a different mechanism. E.g. On IIS you can create a Web.config file to block this access and place it inside your application's directory.''' Download a sample Web.config file [http://weblite.ca/svn/dataface/core/trunk/site_skeleton/Web.config here]. # Create an index.php file (i.e. ''myapp/index.php'') to serve as an access point for your application:<code> <?php // Include the Xataface API require_once 'xataface/dataface-public-api.php'; // Initialize Xataface framework df_init(__FILE__, 'xataface')->display(); // 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) </code> # Create a ''templates_c'' directory to store cached smarty templates or your application (i.e. ''myapp/templates_c'', and make sure that it is writable by the webserver: $ mkdir templates_c $ chmod 777 templates_c That's all there is to it! Point your web browser to the index.php file we just made, and check out your new app! ===Screenshots of Our App=== ====Find Form==== [[Image:http://media.weblite.ca/files/photos/people-find.png?max_width=400]] ====New Record Form==== [[Image:http://media.weblite.ca/files/photos/people-new-record.png?max_width=400]] ====List View==== [[Image:http://media.weblite.ca/files/photos/people-list.png?max_width=400]] ===Where to go now=== # Sign up for the Xataface mailing list to receive exclusive development tips (see the left column for a signup form). # Check out the [[about|About Xataface]] page for more information about features and requirements. # Use the [http://xataface.com/documentation/getting_started Getting Started Tutorial] to get started making your own application. # [http://xataface.com/videos Watch screencasts] showing Xataface in action. tutorial, getting started, installation, first app, 4 lines of code en 0 _output_cache 45 The Xataface Output Cache <nowiki><div class="portalMessage">Note: There was a bug in the output cache affecting Xataface version 1.0 to 1.3rc1. If you are using a version of Xataface older than 1.3rc2 then you should either disable the output cache, or replace the Dataface/OutputCache.php file with one from a newer version.</div></nowiki> [[toc]] 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. ===Features=== * Improve speed of application dramatically - especially for seldom updated sites. * Supports multiple languages. * Supports multiple users (each user has own cache). * Provides GZIP compression for improved performance. ===How it works?=== When you receive a request, Xataface will return a cached version of the page if the page has been accessed before. If the page doesn't yet exist in the cache it generates the page, saves it to the cache and outputs it to the user transparently. The cache is completely transparent to your users. ===Where is the cache stored?=== Xataface creates a table called ''__output_cache'' that stores all of the cached content for your application. This table stores both a GZIPed and regular version of each page. If the user's browser supports GZIP compression, Xataface will automatically return the GZIP version. This results in further performance improvements. ===What if I make changes to the database?=== Xataface records which tables were in use when a page is cached. If any of those tables are modified after the page is cached, Xataface will mark that cached page as ''out of date'' and regenerate it the next time that it is requested. ===What if I make changes to my configuration files and templates?=== The output cache will have to be manually cleared if you make any changes to your source files (e.g. PHP, templates, and INI files). Clearing the cache is as easy as deleting or emptying the ''__output_cache'' table. ===How do I enable the Cache?=== Add the following to your [[conf.ini file]]: <code> [_output_cache] enabled=1 </code> ===How do I disable the Cache?=== Simply comment out or remove the ''[_output_cache]'' section of your [[conf.ini file]]. E.g. <code> ;[_output_cache] ; enabled=1 </code> ===Configuration Options=== The following directives can be added to the ''[_output_cache]'' section of your [[conf.ini file]] to customize how your output cache works. {| class="listing listing2" |- ! Name ! Description ! Version |- | lifeTime | Number of seconds before cached page is considered ''out of date''. | 0.7 |- | tableName | The name of the table to store the cached pages. Default '__output_cache'. | 0.7 |- | ignoredTables | A comma-delimited list of tables that don't affect the output cache (i.e. these tables can be changed without causing the output cache to be refreshed. | 0.7 |- | observedTables | A comma-delimited list of tables that should affect the status of the output cache for every page (whether the table is explicitly used by the page or not). This is a useful way to tell Xataface to refresh your cache. | 0.7 |- | exemptActions | A comma-delimited list of actions that are exempt from the output cache (and thus should not be cached). | 0.7 |} output cache en 0 setSecurityFilters 91 setSecurityFilter() method == Example == In the delegate class for the users table: <code> <?php class tables_users { function init(&$table){ if ( !isAdmin() ){ $table->setSecurityFilter(array('group_id'=>10)); } } } </code> This will only set the filter on non-admin users (assuming that you have defined a function isAdmin() to tell you if the current user is an admin user. en init 140 init() Delegate Class Method == Synopsis == This method is called once, just after the table is loaded for the first time. It allows you to specify initialization details, such as [[setSecurityFilters|security filters]]. Note that it takes a single parameter: a Dataface_Table object of the table that is being initialized. == Example == <code> function init(&$table){ .... } </code> en 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 http://xataface.com/documentation/how-to/site_with_backoffice_How_to_build_a_site_with_a_backoffice_ 84 A site with a backoffice ==A site with a backoffice== To create a site with a backoffice for the administrator, so that the visitors do not have to log in to read the pages, you add this code in the ApplicationDelegate.php file in the conf directory : <code> function getPermissions(&$record){ if ( isAdmin() ) return Dataface_PermissionsTool::ALL(); else return Dataface_PermissionsTool::READ_ONLY(); } </code> en 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 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 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 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 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 Cached_permissions 179 Cached Permissions ==Cached Permissions== ===Introduction=== When you insert a SQL query in your getPermissions function, this will slow down the app dramatically because this function is called by each query. To resolve this problem, it is better to use cached permissions in your /conf/ApplicationDelegate.php or table/table.php. ===Procedure=== Here is an example : <code> class tables_mytable { private $cachedPerms = null; private function _getCachedPerms($param1, $param2, ..., $paramN){ if ( !isset($this->cachedPerms) ) { $this->cachedPerms = array(); // do some stuff $res = mysql_query("select * from foo where bar=1 and param2='".addslashes($param2)."'"); while ( $row = mysql_fetch_assoc($res) ) $this->cachedPerms[$row['fooid']] = $row; } return $this->cachedPerms; } function getPermissions($record){ // do some stuff $perms = $this->getCachedPerms($param1, $param2, ..., $paramN); return $perms; } }</code> Here, getPermissions() will run a db query on its first request, but subsequent requests will just load the cached value. permissions, cache, quick, query en 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 Clean_the_html_for_the_export 178 Clean the HTML to export data ==Clean HTML tags and entities to export your data== #Override the display() of the field to strip the tags... but this would affect all parts of the application where the HTML fields are displayed. #Create a grafted field, then override its display to show the stripped contents of the HTML area field. e.g. in the fields.ini: <code> __sql__ = "select t.*, null as stripped_field from mytable t" [original_field] widget:type=htmlarea visibility:csv=hidden [stripped_field] visibility:csv = visible visibility:list=hidden visibility:browse=hidden visibility:find=hidden </code> Then in the delegate class: <code> function stripped_field__display($record){ return html_entity_decode(strip_tags($record->val('original_field')), ENT_QUOTES, 'UTF-8'); } </code> en 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 Selected_Records_Actions 58 Selected_Records_Actions ==Creating a Custom ''Selected Records'' Action== [[toc]] If you view the ''list'' tab in any of your Xataface applications, you'll notice that there is a checkbox next to each row of the list, and there are a number of actions listed at the bottom of the list that you can perform on the selected records. Xataface comes pre-built with only a few of these actions: # Delete selected # Update selected # Copy selected However it is quite easy to add your own actions here that are performed on selected records. This article describes exactly how to do this. ===What is a ''Selected Record'' action?=== A ''Selected Record'' action is no different than any other action in Xataface, except that it is meant to act on the records that have been selected in the list tab. ==Example Action: Approve Records== Consider a news site where news stories are automatically imported into the database en masse, but each news story has a field ''approved'' to indicate whether the store has been approved to appear on the site yet. The usage pattern of this application involves a lot of looking through lists of news stories and approving them. Therefore it would be convenient if the user could just select the rows that he wants to approve and click a button to approve them all. Out of the box Xataface would allow the user to select the records, click ''update selected records'', then update them all via the ''update selected records'' form. But avoiding this extra step will improve usability greatly. ===Step 1: Design the Action=== First we need to specifically decide how our action will work. In this case, the flow goes as follows: # User selects the news items they want to approve. # User clicks the ''Approve Selected'' button. (to be created) # Our action approves the selected records. # User is automatically redirected back to the list tab with a message stating how many records were successfully approved, and whether there were any errors. ===Step 2: Gather Our Tools=== Before we actually create the action, let's look at a few tools that we'll be using from the Xataface framework to make this happen. # In the [[actions.ini file]], the ''[[selected_result_actions]]'' category is reserved for actions that act on selected records of the list tab. E.g.<code> [delete_selected] ... category=selected_result_actions ... </code> # The [http://dataface.weblite.ca/df_get_selected_records df_get_selected_records()] function returns an array of [http://dataface.weblite.ca/Dataface_Record Dataface_Record] objects that represent the rows that were selected to initiate the action. E.g.<code> $app =& Dataface_Application::getInstance(); $query =& $app->getQuery(); $records = df_get_selected_records($query); foreach ($records as $record){ ... } </code> # The [http://dataface.weblite.ca/checkPermission Dataface_Record::checkPermission()] method allows us to see if the current user has access to a specific permission on the given record. We'll use this method to ensure that the user has permission to approve the news record. E.g.<code> if ( !$record->checkPermission('edit', array('field'=>'approved')) ){ return PEAR::raiseError("You don't have permission to edit the approved field for this record."); } </code> # The Xataface will pass the redirect URL where your action should send the user upon completion of the action as the ''--redirect'' attribute of the ''POST'' variables. This value is base64_encoded so you'll need to decode it before redirecting. E.g.:<code> if ( @$_POST['--redirect'] ) $url = base64_decode($_POST['--redirect']); $url .= '&--msg='.urlencode($updated.' records were deleted.'); header('Location: '.$url); exit; </code> ===Step 3: Create the Action=== We will call our action ''approve_news'' so we'll place it in the ''actions/approve_news.php'' file of our application: <code> <?php class actions_approve_news { function handle(&$params){ // First get the selected records $app =& Dataface_Application::getInstance(); $query =& $app->getQuery(); $records =& df_get_selected_records($query); $updated = 0; // Count the number of records we update $errs = array(); // Log the errors we encounter foreach ($records as $rec){ if ( !$rec->checkPermission('edit'), array('field'=>'approved')) ){ $errs[] = Dataface_Error::permissionDenied( "You do not have permission to approve '". $rec->getTitle(). "' because you do not have the 'edit' permission."); continue; } $rec->setValue('approved', 1); $res = $rec->save(true /*secure*/); if ( PEAR::isError($res) ) $errs[] = $res->getMessage(); else $updated++; } if ( $errs ){ // Errors occurred. Let's let the user know. // The $_SESSION['--msg'] content will be displayed to the user as a message // in the next page request. $_SESSION['--msg'] = 'Errors Occurred:<br/> '.implode('<br/> ', $errs); } else { $_SESSION['--msg'] = "No errors occurred"; } $url = $app->url('-action=list'); // A default URL in case no redirect was supplied if ( @$_POST['--redirect'] ) $url = base64_decode($_POST['--redirect']); $url .= '&--msg='.urlencode($updated.' records were deleted.'); // Redirect back to the previous page header('Location: '.$url); exit; } } </code> ===Step 4: Add the action to your actions.ini file=== The actions.ini file allows us to specify how and where this action is used, and by whom. We can specify permissions that are required to perform the action, conditions that are required to display the action, confirmation messages that are to be displayed to the user when they are about to perform the action, and more. Our [[actions.ini file]] entry looks like: <code> [approve_news] label="Approve" description="Approve selected records" permission = edit category=selected_result_actions confirm="Are you sure you want to approve the selected records?" icon="${dataface_site_url}/images/approve.gif" condition="$query['-table'] == 'news'" </code> This should be fairly straight forward. The only special items here are the ''category'' and ''confirm'' directives. The ''condition'' directive tells Xataface that this action should only be shown for the ''news'' table. The ''confirm'' directive defines a confirmation message that should be displayed to the user when they attempt to approve records. The ''icon'' directive allows you to specify the path to an icon to display for the action. In our case we have an icon located in the images directory of our application. ===Step 5: Trying it out=== Now when we go to the ''list'' tab of the ''news'' table there is an ''Approve'' button along the bottom where it says "With Selected". You we can click on this button to approve any of the selected rows. en 0 Creating_a_Dashboard 57 Creating_a_Dashboard ==Creating a Dashboard for your Users== [[toc]] Xataface allows you to build powerful data-driven applications quickly, but these applications may be daunting to your users if they don't know what they can do with the application. Most applications provide some sort of dashboard or control panel with some introductory instructions and links to commonly used actions in the application. This makes the application more intuitive for users so that they can start using it right away, even without instruction from the developer. ===Characteristics of a Dashboard=== # Should be the default page when someone visits the application. # Should be customized to show menus and content that are relevant to the current user. (i.e. different users may see different links and content on their dashboard). # Should contain at least some basic instructions so that the user understands what the application does when he visits the dashboard for the first time. # Should contain links to frequently used actions. ===Strategies: 8 ways to skin the cat=== There are many viable strategies for adding a dashboard to your Xataface application. This article presents only one. It has been chosen because it satisfies all of the desired characteristics of a dashboard listed above, and it is easy to implement. This strategy involves the following components: # Create a dummy ''dashboard'' table. # Create a dashboard action and associated template. # Make sure our dashboard action is the default action for our application (more complex than just using the [[default_action]] directive in the [[conf.ini file]]. ==Our Sample Application== Consider our sample application, a publications management system for professors and research groups at a university. It allows users to manage their publications using either BibTex format or a web-based form, and embed those publications into their webpage in a slick sortable format. Currently, when the user accesses the application for the first time, they are shown the ''list'' tab of the ''bibliographies'' table. This isn't all that informative and it may not be obvious to the user that their first step should be to create a new bibliography via the ''new record'' button. Ideally we would like the user to go directly to a dashboard page with options to: # Add New Bibliography # Edit an Existing Bibliography # Embed a Bibliography into their Webpage And we want some basic instructions so that the user knows what to do when they first access the page. ==The Steps== To create this dashboard we will follow the steps listed below (and mentioned above in the ''strategies'' section. ===Step 1: Create a dummy ''dashboard'' table=== This may seem unorthodox but it just happens to make our lives easier in the long run. By creating a dummy table we are able to cause that table to be listed first in the ''_tables'' section of the [[conf.ini file]] and thus be the default table when users visit our application. <code> CREATE TABLE dashboard ( dashboard_id int(11) not null auto_increment primary key ); INSERT INTO dashboard values (1); </code> ===Step 2: Make ''dashboard'' table default=== We now modify the conf.ini file to list the ''dashboard'' table first: <code> [_tables] dashboard=Dashboard bibliographies=Bibliographies </code> ===Step 3: Create a Dashboard action and associated template=== This is the step where we actually create our dashboard action. There are three parts to this story: ====Creating Action PHP Class==== The actual action will be located in the ''actions/dashboard.php'' file of our application, and looks like: <code> <?php class actions_dashboard { function handle(&$params){ $bibs = df_get_records_array('bibliographies', array()); df_display(array('bibliographies'=>$bibs), 'dashboard.html'); } } </code> All this does is loads the ''bibliographies'' records owned by the current user. Elsewhere we are using security filters so that the user can only see ''his'' bibliographies, which is why we don't need to specify any query here in the ''df_get_records_array'' function. It then passes those bibliographies to the ''dashboard.html'' template that we create next. ====Creating the Action's Template==== The template for our action is located in the ''templates/dashboard.html'' file: <code> {use_macro file="Dataface_Main_Template.html"} {fill_slot name="main_column"} <h1>Welcome to the BibTeX Publication Management System (BPMS)</h1> <p>This system allows you to manage your publications and publish them on the web. Some common actions you may perform with this system include: <ul> <li><img src="{$ENV.DATAFACE_URL}/images/add_icon.gif"/> <a href="{$ENV.DATAFACE_SITE_HREF}?-table=bibliographies&-action=new"> Create New Bibliography</a> </li> <li><img src="{$ENV.DATAFACE_URL}/images/edit.gif"/> Edit existing bibliography: <select onchange="window.location.href=this.options[this.selectedIndex].value"> <option value="">Select ...</option> {foreach from=$bibliographies item=bibliography} <option value="{$bibliography->getURL('-action=edit')}"> {$bibliography->getTitle()} </option> {/foreach} </select> </li> <li><img src="{$ENV.DATAFACE_URL}/images/file.gif"/> Embed your bibliography in a webpage: <select onchange="window.location.href=this.options[this.selectedIndex].value"> <option value="">Select ...</option> {foreach from=$bibliographies item=bibliography} <option value="{$bibliography->getURL('-action=view')}#embed"> {$bibliography->getTitle()} </option> {/foreach} </select> </li> </ul> {/fill_slot} {/use_macro} </code> A few key things to notice in this template: # It extends the ''Dataface_Main_Template.html'' template placing its content in the ''main_column'' slot. This allows our action to still display within the header and footer of our application. # It makes use of the {$ENV.DATAFACE_SITE_URL} and {$ENV.DATAFACE_SITE_HREF} variables to refer to the site's base url and create links to the desired common actions. # It provides a direct link to the ''new bibliography record'' form. # It uses some slick javascript combined with select lists to allow the user to select any of his current bibliogaphies and edit them, or embed them into a webpage. ====Adding entry to the actions.ini file==== Currently our dashboard action has no permissions attached to it so users can see it whether they are logged in or not. In this particular application we want to require users to log in, and we have set permissions for all logged in users to NO_ACCESS(). Unfortunately this permission setting is only helpful if our action requires a particular permission to access it. We'll require the 'view' permission for this action, by adding the following to the actions.ini file: <code> [dashboard] permission=view </code> ===Step 4: Specify permissions=== We still want to specify permissions for our ''dashboard'' table to ensure that only logged in users can access the dashboard. So we create a delegate class for the ''dashboard'' table at ''tables/dashboard/dashboard.php'' with the following contents: <code> <?php class tables_dashboard { function getPermissions(&$record){ if ( getUser() ){ return Dataface_PermissionsTool::ALL(); } return null; } } </code> '''Note that we have defined the getUser() function elsewhere as a means of obtaining the current user and checking if a user is indeed logged in.''' Notice that this [[getPermissions]] method returns all permissions only if the user is logged in. Otherwise it returns null, which means that it should use the same permissions as the rest of the application as defined in the [[Application Delegate Class]]. ===Step 6: Make ''dashboard'' the default action for the ''dashboard'' table=== Now we just have one more detail that needs to be taken care of. We want the ''dashboard'' action to be the default action for the ''dashboard'' table only. By default we would see the ''list'' action which isn't helpful at all, so we will want to add a rule in our application delegate class to ensure that the user only sees our custom ''dashboard'' action if they access the ''dashboard'' table. We define a beforeHandleRequest() method in our conf/ApplicationDelegate.php (the application delegate class) file for this purpose: <code> <?php class conf_ApplicationDelegate { ... function beforeHandleRequest(){ ... $app =& Dataface_Application::getInstance(); $query =& $app->getQuery(); if ( $query['-table'] == 'dashboard' and ($query['-action'] == 'browse' or $query['-action'] == 'list') ){ $query['-action'] = 'dashboard'; } } ... } </code> This simply checks to see if the table is ''dashboard'' and changes the current action to ''dashboard'' if so. ===Step 7: Try it out=== At this point, we are ready to try out our new dashboard to see how it works. When we load our application it should now go to the dashboard action that we created. We should also see ''Dashboard'' listed as the first table in the tables menu. This dashboard presents a major improvement to our application as it is now much more user friendly. <nowiki> <img src="http://media.weblite.ca/files/photos/pub-dashboard.png?max_width=640"/> </nowiki> dashboard en 0 Creating_Printable_Reports 82 Creating a Custom Printable Report ==Creating a Printable Report== [[toc]] It is often useful to provide your users with a printable report that is generated from your database. Although Xataface doesn't include an explicit reporting module to allow the end users to create their own reports, you (the developer) can still quite easily produce a report by creating a custom action. This report will be subject to the user's sorting and searching preferences. E.g. if the user searches for only books about "frogs", then when he clicks on your printable report it will only display those records that match the query (i.e. only books about frogs). ===Requirements for our report=== # Report will be run against the "products" table (using the WebAuction application). # Report should be accessible by clicking an icon in the top right of the list view (i.e. the resultlist actions). # Report should display the product ID, product name, photo, and description. One product per page. ===Adding the Icon to our Application=== We'll start out by finding an appropriate icon to use for our action. There are loads of free icons that you can download (please observe and respect the license agreement of any icon library that you use). Two good free icon libraries include: # [http://www.famfamfam.com/lab/icons/silk/ FamFamFam Silk Icons] # [http://tango.freedesktop.org/Tango_Icon_Library Tango Icon Library] Once you have found the icon you want to use, just upload it somewhere inside your application's directory. It might be a good idea to create a directory to store your images if you haven't already. An appropriate name might by ''images''. For this example, we'll use the [[Image:http://dev.weblite.ca/phpimageserver/photos/icons/printer.png]] icon from the FamFamFam icon library. So we upload this icon to %APPLICATION_PATH%/images/printer.png Next we need to create an entry in our application's [[actions.ini file]] so that Xataface knows about our action, and where we want its icon to be displayed. We'll start out with a basic definition that just specifies the icon for the action, and the ''category'' of the action. <code> [printable_report] icon="{$site_url}/images/printer.png" category=result_list_actions description="See this product list in a printable format" </code> The ''result_list_actions'' category setting means that the icon for our action will be included along with the result list actions, which are located in the top right corner in the list tab. Now if we reload our application and look at the "list" tab, you'll see that the icon group in the top right now includes our icon: [[Image:http://media.weblite.ca/files/photos/Picture%20-5.png?max_width=640]] If you don't see this icon, but see the text "printable_report" instead, then you have entered an incorrect path to the icon in the ''icon'' directive. If you don't see an icon at all or any text, then your ''category'' directive may be incorrect. Check that it is exactly "result_list_actions". If you mouse over your icon you'll see the text that you specified as your ''description'' directive for the action: [[Image:http://media.weblite.ca/files/photos/Picture%20-6.png?max_width=640]] You'll notice, if you try to click on your icon, that nothing happens. This is because we haven't yet specified a URL for your action. We'll wait to specify our URL, until we've built the back-end of our action (i.e. the actual report). ===Creating the Actual Report=== Most reports involve the following pieces: # Fetch the found set of records from the database. # Loop through the found set and output some information about each record. # Optionally use a template to integrate the report into your application's look and feel. All reports will be placed in the framework of a custom Xataface action. In our case we add a file to our application ''actions'' directory named after our action: %APPLICATION_PATH%/actions/printable_report.php with the following contents: <code> <?php class actions_printable_report { function handle(&$params){ echo "Hello world!!!"; } } </code> Please note the following about this snippet: # The action was placed in a file ''actions/printable_report.php'' because the action is named ''printable_report'' (referring to our definition in the ''[[actions.ini file]]''. If the action was named ''foo'', then we would place our action in file ''actions/foo.php''. # The ''printable_report.php'' file contains a single class named ''actions_printable_report'' after the name of the action. # The action class contains a single method ''handle'' which handles the request for the action (i.e. outputs the report the way we like). This method must exist and me named exactly ''handle''. # The ''handle'' method takes a single ''&$params'' parameter which contains some parameters that may be passed to the action. We won't be dealing with these in this example. Before proceeding, let's try accessing our action just to make sure that we're on the right track. Point your browser to http://example.com/yourapplication/index.php?-action=printable_report Note that you don't point our web browser directly to your action php file (in the ''actions'' directory. Rather you point it to your application's entry point (index.php file), and specify the action via the ''-action'' GET parameter. Your web browser should display something like: [[Image:http://media.weblite.ca/files/photos/Picture%204.png?max_width=640]] If you get a blank white screen, then you should check your error log to see where the error is occuring. See [[Troubleshooting]] for general Xataface troubleshooting strategies in this case. Now that we have all of the formalities out of the way, we can proceed to meat of our report. ====Retrieving the Found Set==== Let's build onto our action now. First we will load the found set of records as follows: <code> <?php class actions_printable_report { function handle(&$params){ $app =& Dataface_Application::getInstance(); $query =& $app->getQuery(); if ( $query['-table'] != 'products' ){ return PEAR::raiseError('This action can only be called on the Products table.'); } $products = df_get_records_array('products', $query); } } </code> Things to note in this snippet: # We start be loading a reference to the ''Dataface_Application'' object. # We then use the ''Dataface_Application'' object to load the current query. This is essentially an associative array of all of the GET parameters, but with some guaranteed attributes such as ''-table'' and ''-action''. # In our particular action we are designing it to only work for the ''products'' table so we do a check on the query parameters to make sure that this is the case. If someone tries to run this action from outside the products table (e.g. if -action=foo) then an error will be displayed. # We use the df_get_records_array() function to return all matching records on the products table. It returns an array of [[Dataface_Record]] objects. ====Overriding -skip and -limit==== Xataface allows the user to specify the number of records to display and the position in the found set to start from by adding the ''-skip'' and ''-limit'' GET parameters to a request. If these are omitted, then default values of 0 and 30 are used respectively. You may notice that if you click "Next" in list view, you see '-skip' and '-limit' parameters automatically added to the URL. ''df_get_records_array'' respects the -limit and -skip parameters that are specified in the query. I.e. if -skip and -limit are omitted it will return only the first 30 records from the found set. If -skip=1 and -limit=10 then it will return 10 records starting from the 2nd record (2nd becuase -skip=0 would point to the first record). This may be desired behavior for your report, but in some reports you may want to print off the entire found set. If this is the case, you will want to explicitly set the -skip and -limit parameters in the ''$query'' array before passing it to ''df_get_records_array''. E.g.: <code> $query =& $app->getQuery(); $query['-skip'] = 0; $query['-limit'] = 10000; $products = df_get_records_array('products', $query); </code> ====Looping through and Printing Product Info==== Now comes the fun part. We're just going to loop through our found set and print off the product information: <code> foreach ($products as $p){ echo '<table>' .'<tr><th>Product ID</th><td>'.$p->htmlValue('product_id').'</td></tr>' .'<tr><th>Product Name</th><td>'.$p->htmlValue('product_name').'</td></tr>' .'<tr><th>Description</th><td>'.$p->htmlValue('product_description').'</td></tr>' .'<tr><th>Photo</th><td>'.$p->htmlValue('product_image').'</td></tr>' .'</table>'; } </code> The entire action at this point will look like: <code> <?php class actions_printable_report { function handle(&$params){ $app =& Dataface_Application::getInstance(); $query =& $app->getQuery(); $query['-skip'] = 0; $query['-limit'] = 10000; if ( $query['-table'] != 'products' ){ return PEAR::raiseError('This action can only be called on the Products table.'); } $products = df_get_records_array('products', $query); foreach ($products as $p){ echo '<table>' .'<tr><th>Product ID</th><td>'.$p->htmlValue('product_id').'</td></tr>' .'<tr><th>Product Name</th><td>'.$p->htmlValue('product_name').'</td></tr>' .'<tr><th>Description</th><td>'.$p->htmlValue('product_description').'</td></tr>' .'<tr><th>Photo</th><td>'.$p->htmlValue('product_image').'</td></tr>' .'</table>'; } } } </code> Now we refresh our action in the web browser, or point the browser again to: http://example.com/yourapplication/index.php?-action=printable_report&-table=products It should display something like: [[Image:http://media.weblite.ca/files/photos/Picture%205.png?max_width=640]] If you get a blank white screen, please check out the [[Troubleshooting]] section for general Xataface troubleshooting strategies. ====Adding a Little Style==== It is a good idea to at least provide the proper HTML HEAD and BODY tags for your report. And to help make things a little nicer looking we're going to add some CSS styles to: # Make the table field labels vertically aligned to the top. # Change the font to helvetica. This is easy to do with simple echo statements: <code> echo '<html><head>' .'<title>Printable Report</title>' .'<style type="text/css">' .' th { vertical-align: top}' .'</style>' .'</head>' .'<body>'; //... </code> So our finished action looks like: <code> <?php class actions_printable_report { function handle(&$params){ $app =& Dataface_Application::getInstance(); $query =& $app->getQuery(); $query['-skip'] = 0; $query['-limit'] = 10000; if ( $query['-table'] != 'products' ){ return PEAR::raiseError('This action can only be called on the Products table.'); } $products = df_get_records_array('products', $query); echo '<html><head>' .'<title>Printable Report</title>' .'<style type="text/css">' .' th { vertical-align: top}' .'</style>' .'</head>' .'<body>'; foreach ($products as $p){ echo '<table>' .'<tr><th>Product ID</th><td>'.$p->htmlValue('product_id').'</td></tr>' .'<tr><th>Product Name</th><td>'.$p->htmlValue('product_name').'</td></tr>' .'<tr><th>Description</th><td>'.$p->htmlValue('product_description').'</td></tr>' .'<tr><th>Photo</th><td>'.$p->htmlValue('product_image').'</td></tr>' .'</table>'; } echo '</body></html>'; } } </code> ===Connecting the Icon to the Action=== FInally it is time to connect our Icon to our Action. We do this by adding a ''url'' directive for the action in the ''[[actions.ini file]]'': <code> [printable_report] icon="{$site_url}/images/printer.png" category=result_list_actions description="See this product list in a printable format" url="{$app->url('-action=printable_report')}" </code> Explanation of the ''url'' directive in this snippet: * The ''url'' method of the ''[[Dataface_Application]]'' object is used to generate a URL with the user's current query settings, but with the ''-action'' parameter set to ''printable_report''. Now if we reload our application, go to the list tab of the ''products'' table and click on our icon, it should take us to our action: [[Image:http://media.weblite.ca/files/photos/Picture%207.png?max_width=640]] ===Trying out the action on different found sets with different sort orders=== One of the cool things about this action is that it is tied directly into the Xataface find settings so that th user is able to search for a subset of products and run our report on only those products that were found. The user can also perform a sort on any column and this sort will be respected by our report. ===Hiding Icon from Other Tables=== Since our action is only intended to operate on the ''products'' table it probably isn't a good idea to make the icon visible for every other table. For example, if you go to the list view of the ''users'' table, you'll see the printer icon in the top right just like it appears for the ''products'' table. Clicking on it should display our error: [[Image:http://media.weblite.ca/files/photos/Picture%206.png?max_width=640]] We will use a ''condition'' directive for our action to hide it from tables other than the ''products'' table as follows: condition="$query['-table'] == 'products'" So our action will now look like: <code> [printable_report] icon="{$site_url}/images/printer.png" category=result_list_actions description="See this product list in a printable format" url="{$app->url('-action=printable_report')}" condition="$query['-table'] == 'products'" </code> Now if you reload the list for the ''users'' table you'll notice that the printer icon is now gone. But returning to the ''products'' table shows our action still alive and well. ===Locking Down our Action with Permissions=== In our case we don't want our action to be accessible to all users. Only administrators. Xataface permissions and all its possibilities are beyond the scope of this tutorial, but we still want to demonstrate how to lock down this action. The WebAuction application into which this action is being installed defines a permission called ''reports'' which only administrators have. We will use this permission to limit access to this action as follows in the actions.ini file: permission=reports So the actions.ini file will now look like: <code> [printable_report] icon="{$site_url}/images/printer.png" category=result_list_actions description="See this product list in a printable format" url="{$app->url('-action=printable_report')}" condition="$query['-table'] == 'products'" permission=reports </code> Now only administrators will see our icon, and if non-administrators attempt to access out action by typing in its URL directly, they will receive an "Access Denied" message. en GettingStarted:first_application 74 Creating your First Application ==Creating Your First Application== Build a simple Xataface application. For our first Xataface application we will try to build a web site for Faculty of Widgetry (From the example in the "Why Use Xataface" page). The web site needs to store information about programs and courses. An entity-relationship diagram (ERD) for this website is included below: [[Image:http://xataface.com/documentation/tutorial/getting_started/er-diagram.png]] As the ERD shows, our database will need 2 tables (Course and Program). Our next step is to build this database. You can use any MySQL database administration tool to builld the database. My personal tool of choice is PHPMyAdmin. ===Step 1: Creating the database using PHPMyAdmin=== The following steps describe the procedure for creating this database using PHPMyAdmin. # At the main menu of PHPMyAdmin, type 'FacultyOfWidgetry' into the 'Create new database field' as follows: <nowiki><br/></nowiki>[[Image:http://xataface.com/documentation/tutorial/getting_started/new_database.gif]] <nowiki><br/></nowiki>Then click 'Create'. # First we will create the 'Course' table to hold course information. In the 'FacultyOfWidgetry' page, fill in the 'Create new table text field as follows: <nowiki><br/></nowiki>[[Image:http://xataface.com/documentation/tutorial/getting_started/create_table.gif]] <nowiki><br/></nowiki> Then click 'Go'. # This should bring up a form to specify the fields for the course table: <nowiki><br/></nowiki>[[Image:http://xataface.com/documentation/tutorial/getting_started/course-table-def-small.gif]] <nowiki><br/></nowiki> Then click "Save". The resulting SQL to create the Course table is as follows:<code> CREATE TABLE `Course` ( `CourseID` int(11) NOT NULL auto_increment, `ProgramID` int(11), `CourseTitle` varchar(64) NOT NULL default '', `CourseDescription` text NOT NULL, `HTMLOutline` text NOT NULL, `PDFOutline` longblob NOT NULL, `PDFOutline_mimetype` varchar(64), `Subject` varchar(128) NOT NULL default '', `CourseNumber` varchar(10) NOT NULL default '', `Credits` int(5) NOT NULL default '0', `LastModified` timestamp NOT NULL default CURRENT_TIMESTAMP, PRIMARY KEY (`CourseID`) ) ENGINE=MyISAM DEFAULT CHARSET=latin1 COMMENT='Store courses' AUTO_INCREMENT=1 ; </code> #In a similar fashion, create the Program table. The resulting SQL for this table is:<code> CREATE TABLE `Program` ( `ProgramID` int(11) NOT NULL auto_increment, `ProgramName` varchar(64) NOT NULL default '', `ProgramDescription` text NOT NULL, `HTMLOutline` text NOT NULL, `PDFOutline` longblob NOT NULL, `PDFOutline_mimetype` varchar(32), `AdmissionDeadline` date NOT NULL default '0000-00-00', `LastModified` timestamp NOT NULL default CURRENT_TIMESTAMP, PRIMARY KEY (`ProgramID`) ) ENGINE=MyISAM DEFAULT CHARSET=latin1 COMMENT='Academic Program' AUTO_INCREMENT=1 ; </code> # The database has been created with 2 tables: Program and Course. We can now move on to building the Xataface application. ===Step 2: Create Xataface Application=== Our Xataface application will provide a user-friendly front-end to our database. A basic application consists of a directory with a configuration file and an entry page (PHP file). Xataface comes with a PHP setup script (called makesite) to create the skeleton for your application. Alternatively you can set up the application manually. Note: For the following instructions and examples, my Daface installation is located at /Users/shannah/Sites/dataface and the URL for the installation is http://localhost/~shannah/dataface. ====Method 1: Setting up application with the 'makesite' script==== # From the command prompt, navigate to the dataface directory. (in my case ''/Users/shannah/Sites/dataface''). # This directory contains a file named 'makesite'. It is a PHP script that can be used to build a website powered by Xataface. To find out the usage options for this script you can simply call the script with no parameters. E.g.,<code> stevepbook:~/Sites/dataface shannah$ ./makesite </code> # This will give you usage instructions for the script as follows:<code> makesite: invalid options entered. Usage: makesite <site_path> <db_user>:<db_pass>@<db_host>/<db_name> <dataface_url> or php makesite <site_path> <db_user>:<db_pass>@<db_host>/<db_name> <dataface_url> where <site_path> = The path (absolute or relative) to your application directory. <db_user> = The MySQL username to connect to the database <db_pass> = The User's password to connect to the database <db_host> = The MySQL host name. <db_name> = The name of the mysql database for the application. <dataface_url> = The URL to the Xataface installation Examples: makesite ../FacultyOfWidgetry root:password@localhost/FacultyOfWidgetry /dataface The above command would create a site at ../FacultyOfWidgetry (i.e., the Faculty of Widgetry directory in the parent directory. The database used for this site is located at localhost, and the database name is FacultyOfWidgetry. The username to connect to the database is root and his password is password. </code> # We create our FacultyOfWidgetry site using the following command:<code> ./makesite ../FacultyOfWidgetry \ root@localhost/FacultyOfWidgetry \ http://localhost/~shannah/dataface </code> # This will create our application in the FacultyOfWidgetry folder if everything worked ok. The contents of the folder will look like: <nowiki><br/></nowiki>[[Image:http://xataface.com/documentation/tutorial/getting_started/directory-structure-1.gif]] You may be wondering what these files. Here is the short version (Read the next section "Creating applications manually" for more detailed information about the contents of these files. The index.php file is the entry point for your application (i.e., you point the web browser at this file to use the application. The conf.ini file contains database connection settings and some other minor settings, like what should appear in the navigation menu. The tables/Program (tables/Course) directory can contain configuration files specific to the Program (Course) table. More on that later. # Point your web browser to the FacultyOfWidgetry directory to see the application: <nowiki><br/></nowiki>[[Image:http://xataface.com/documentation/tutorial/getting_started/basic-application-1.gif]] #Your application is now created. It will enable you to add, edit, delete, and find records in either the Course table or the Program table. There will be more on the basics of using this application in the next section. ====Method 2: Setting up application manually==== Using the makesite script as described above is the recommended way to set up an application because it saves time. However, it is very easy to set up the application manually. Just follow these steps: # Create a directory for the application somewhere in your web site (preferably outside your xataface directory). We will call our directory 'FacultyOfWidgetry'. ):<code> mkdir FacultyOfWidgetry </code> # Create a PHP file to serve as the access point for the application. Generally we will name this file 'index.php', but you can name it anything. Place the following contents in the index.php file:<code> <? require_once '/path/to/dataface/dataface-public-api.php'; df_init(__FILE__, 'http://yourdomain.com/dataface'); $app =& Dataface_Application::getInstance(); $app->display(); </code><nowiki><p>OK, I guess some explanations are in order.</p><p> The first line imports the all of the public functions for dataface from the dataface-public-api.php file.</p><p> The second line initializes the application for the current directory and specifies the URL to the dataface installation.</p><p> The third line obtains an instance to the Application object - the core of your Dataface application.</p><p> The fourth line simply displays the application.</p></nowiki> # Create a file named 'conf.ini' to contain database connection information. Its contents should be:<code> [_database] host = "localhost" user = "dbuser" password = "secret" name = "FacultyOfWidgetry" [_tables] Course = "Course" Program = "Program" </code><nowiki><p><b>Explanations:</b></p><p>There are 2 sections in this INI file: '_database', and '_tables'.</p><p> The '_database' section specifies the database connection information for the MySQL database.</p><p> The '_tables' section specifies which tables will be included in the navigation menu for the application.</p></nowiki> # At this point, the application is functional. However there is one more thing that should be done for security reasons. The conf.ini file contains sensitive password information and should not be served to the web. We will create an .htaccess file to tell Apache NOT to serve this (or any) .ini file. The .htaccess file should contain:<code> <FilesMatch "\.ini$"> Deny from all </FilesMatch></code> # The directory structure of your application will now look like: <nowiki><br/></nowiki>[[Image:http://xataface.com/documentation/tutorial/getting_started/basic-app-dir-structure-manual-1.gif]]<nowiki><p> Note, however, that there is also an .htaccess file that is hidden from this image.</p><p>You may be wondering why there is no 'tables' directory like the directory structure that was generated by the makesite script. The 'tables' directory is not required for the application to be functional. It will be required later on when we start to decorate the database.</p></nowiki> # The application is now ready to go. Point your web browser to the index.php file that you created. It will look like:<nowiki><br/></nowiki>[[Image:http://xataface.com/documentation/tutorial/getting_started/basic-application-1.gif]] ===Download source files=== [[File:http://xataface.com/documentation/tutorial/getting_started/facultyofwidgetry-4-tar.gz|Download the source files]] for this application at a tar.gz archive. These files reflect the state of the application at this point of the tutorial. As later sections make changes to the application you will be able to download those versions also. htaccess first application installation en GettingStarted:customizing 76 Customizing Field labels, descriptions, and widgets ==Customizing Field labels, descriptions, and widgets== Using simple INI configuration files, you can customize the look and feel of your application. You can change widgets, labels, field descriptions, and more. In the previous 2 sections we learned how to create a simple application by desiging a database and then installing the basic directory structure to make our application operational. Now it is time to "decorate" the application a little bit. Decoration occurs by way of simple configuration files that are placed in strategic locations in the application. We can customize such things as: * Widget types (e.g., use a select list for a field rather than a text field) * Labels (e.g., The ProgramName field's label can say "Program Name" instead of just "ProgramName") * Field Descriptions . You can add descriptions to fields to help explain their meaning and how to use the application. * HTML attributes. (e.g., Make a text field 50 characters wide) ===Table Configuration Directories=== You will recall, that when we used the 'makesite' script to generate the directory structure for our web application, it created a directory named 'tables', with subdirectories named after each of the tables in our database. The directory structure of the application looked like: [[Image:http://xataface.com/documentation/tutorial/getting_started/directory-structure-1.gif]] The 'tables/Program' and 'tables/Course' are refered to as "table configuration directories" . All of the configuration files a table in a Xataface application are stored in its associated table configuration directory. For example all configuration files for the 'Program' table are located in the 'tables/Program' directory. There are 4 main files that are generally contained in a table's configuration directory: * '''fields.ini''' - Contains configuration for the fields of the table (e.g., field labels, descriptions, widget types, etc...) * ''valuelists.ini''' - Contains value lists (vocabularies) that can be used in the table to limit input into certain fields like select lists. * '''relationships.ini''' - Defines the relationships between this table and other tables in the application. * '''<TableName>.php''' (where <TableName> is the name of the table. - A delegate PHP class that allows you to further customize the behavior of the application with respect to this table. May contain custom fields, importing/exporting functionality, permissions information, and more... ===Customizing Labels and Descriptions=== We will start off by adding custom labels and descriptions to the 'Program' table of our 'FacultyOfWidgetry' application. This sort of customization settings are placed in a file named 'fields.ini' inside the table's configuration directory. # Create the 'fields.ini' file in the Program table configuration directory (i.e., tables/Programs/fields.ini). # Add the following to this file:<code> [ProgramName] widget:label = "Program Name" widget:description = "Enter the name of the program" </code><nowiki><br></nowiki>Now look at the "Edit Record" form in the Xataface application: [[Image:http://xataface.com/documentation/tutorial/getting_started/program-name-label-1.gif]] Notice how the label for the "ProgramName" now says "Program Name" (note the space between "Program" and "Name"). And its description matches the description specified in the fields.ini file. The widget:label and widget:description attributes can be defined for any field in any table of the application. ===Using different widgets=== If no widgets are defined in the fields.ini file, a Xataface application will make a best guess at the type of widget that should be used to edit the value in a field. In general, the widgets used by default are as follows: * VARCHAR, CHAR, INT : html text field * DATE, DATETIME fields: calendar widget * TEXT fields : html text area * BLOB fields : html file upload field * INT Fields with "AUTO INCREMENT" : html hidden field * VARCHAR or CHAR fields with "Password" or "password" as part of the name : html password field * ENUM fields : html select list * SET fields : html checkbox group (not yet supported as of this writing). You can change the widget that is used to edit a field by specifying a "widget:type" attribute for the field in the fields.ini file. For more information about the available widgets, see [[widget:type]]. ====Example: Using HTML Editor to edit the HTMLOutline field==== Clearly the HTMLOutline field in the Program table is intended to store HTML content. By default our application only provides a text area to do the editing so the user is expected to enter the HTML markup by hand. It would be much better to provide the user with a WYSIWYG (What you see is what you get) HTML editor widget. That is exactly what we are going to do. We will add a section to the fields.ini file so that it now looks like: <code> [ProgramName] widget:label = "Program Name" widget:description = "Enter the name of the program" [HTMLOutline] widget:type = "htmlarea" </code> Now refresh the Xataface application in your web browser and look at the edit form for a record of the Program table: [[Image:http://xataface.com/documentation/tutorial/getting_started/htmlarea-1.gif]] As you can see, the HTMLOutline field now has an HTML Editor widget for editing. Most users will find this much nicer to work with than a normal text area. Xataface uses FCKEditor for its html editor widget. There are a number of widgets that can be specified in the [[widget:type]] parameter: * '''[[checkbox]]''' - An HTML checkbox (or checkbox group depending on context). * '''[[date]]''' - Month/Day/Year select lists for selecting dates. * '''[[calendar]]''' - A text field with a button that opens a small calendar widget when clicked. * '''[[group]]''' - A complex widget type for editing multiple values as a group (useful for XML fields) * '''[[hidden]]''' - a hidden field * '''[[password]]''' - An HTML password widget * '''[[select]]''' - An HTML select list (requires the 'vocabulary' attribute) * '''[[static]]''' - an uneditable field * '''[[table]]''' - A complex widget type for editing multiple values in a tabular format (Useful for XML fields) * '''[[text]]''' - an html text field * '''[[textarea]]''' - an html text area ===Changing HTML attributes of widgets=== Sometimes you may want even finer grained control of your widgets' appearance than to just specify the type, label, and desription. Perhaps you want to make a text field 50 characters wide, or to set the CSS class of the html element. This can be done using the 'widget:atts:' parameter for a field. A short example is the easiest way to explain how this works. Modify the fields.ini for the Program table so it looks like:<code> [ProgramName] widget:label = "Program Name" widget:description = "Enter the name of the program" widget:atts:size = 50 widget:atts:style = "font-size: 24pt; font-family: Apple Chancery" [HTMLOutline] widget:type = htmlarea </code> We have added 2 lines:<code> widget:atts:size = 50 widget:atts:style = "font-size: 24pt; font-family: Apple Chancery" </code> What this does is add the html attributes size="50" and style="font-size: 24pt; font-family: Apple Chancery" to the html text field that is used to edit the ProgramName field. Look at the results: [[Image:http://xataface.com/documentation/tutorial/getting_started/widget-atts-1.gif]] The HTML tag for the text field now looks like:<code> <input class="default" id="ProgramName" name="ProgramName" type="text" size="50" style="font-size: 24pt; font-family: Apple Chancery" value="Basic Widgetry" /> </code> In fact you can add arbitrary attributes to any of the fields using the same convention. Some useful examples are: * '''[[widget:atts:rows]]''' for text areas to set the number of rows of text they should display. * '''[[widget:atts:cols]]''' for text areas to set the number of columns (1 character = 1 column) You can even use javascript calls in here if you like: * '''[[widget:atts:onclick]]''' = "doJsFunction();" ===Download source files=== [http://xataface.com/documentation/tutorial/getting_started/facultyofwidgetry-6-tar.gz Download the source files] for this application as a tar.gz archive These source files reflect the state of the application at the current point of the tutorial. As changes are made to the application in later sections, downloads of those versions are made available for download also. ===Summary=== In this section we learned how to change the labels, descriptions, and widgets for fields. We also learned how to add HTML attributes to the widgets to achieve very fine-grained control over the display of our forms. widget labels descriptions onclick handlers en Delegate_class_methods 7 Delegate_class_methods ==Delegate Class Reference== [[toc]] A delegate class is a PHP class that complements a particular table with custom bahaviors. Basic table metadata can be supplied using the [[fields.ini file]], however some things are better customized using PHP. ===Delegate Class Location=== The delegate class should be located in a file named TABLENAME.php (where TABLENAME is the name of the table with which the delegate class is associated) inside the table's [[table configuration directory|configuration directory]]. E.g. given a table named "people", you would place the delegate class in the file "tables/people/people.php" ===Basic Delegate Class=== <code> <?php class tables_people {} ?> </code> ===Available Methods=== ====Table Settings==== {| class="listing listing2" ! Name ! Description ! Version |- | [[sql delegate method|__sql__]] | Defines the SQL query that can be used to fetch records of this table. This is identical to the [[fields.ini file]] [[__sql__]] directive, except that by defining it in the delegate class you have more flexibility. | 1.0 |} ====Permissions==== {| class="listing listing2" ! Name ! Description ! Version |- | [[getPermissions]] | Returns the permissions available for a given record. | 0.6 |- | getRoles | Returns the roles allowed for a given record. | 1.0 |- | [[__field__permissions]] | Returns the default permissions for a field of a given record. | 1.0 |- | __field__roles | Returns the default roles for a field of a given record. | 1.0 |- | [[fieldname__permissions]] | Returns the permissions that are allowed for the field "fieldname" on a given record. | 0.7 |- | fieldname__roles | Returns the roles that are allowed for the field "fieldname" on a given record. | 1.0 |- | rel_relationshipname__permissions | Returns the permissions pertaining to the relationship ''relationshipname'' on a given record. | 1.0 |- | rel_relationshipname__roles | Returns the role or roles pertaining to the relationship ''relationshipname'' on a given record. | 1.0 |} ====Triggers==== {| class="listing listing2" ! Name ! Description ! Version |- | [[after_action_edit]] | Trigger called after the edit action is succesfully completed. | 0.7 |- | [[after_action_new]] | Trigger called after the new action is successfully completed. | 0.7 |- | [[after_action_delete]] | Trigger called after the delete action is successfully completed. | 0.7 |- | [[afterAddExistingRelatedRecord]] | Trigger called after an existing related record is added. | 0.5 |- | [[aftereAddNewRelatedRecord]] | Trigger called after a new related record is added. | 0.5 |- | [[afterCopy]] | Trigger called after a record is copied. | 1.3 |- | [[afterDelete]] | Trigger called after a record is deleted. |0.5 |- | [[afterAddRelatedRecord]] | Trigger called after a related record of this table is added (either an existing record or a new record). | 0.5 |- | [[afterRemoveRelatedRecord]] | Trigger called after a related record is removed from a relationship. | 1.1.6 |- | [[afterInsert]] | Trigger called after a given record is inserted. | 0.5 |- | [[afterSave]] | Trigger called after a given record is saved (insert or update). | 0.5 |- | [[afterUpdate]] | Trigger called after a given record is updated. | 0.5 |- | [[beforeAddExistingRelatedRecord]] | Trigger called before an existing related record is added. | 0.5 |- | [[beforeAddNewRelatedRecord]] | Trigger called before a new related record is added. | 0.5 |- | [[beforeAddRelatedRecord]] | Trigger called before a related record of this table is added (either an existing record or a new record). | 0.5 |- | [[beforeCopy]] | Trigger called before a record is copied. | 1.3 |- | [[beforeDelete]] | Trigger called before a record is deleted. | 0.5 |- | [[beforeRemoveRelatedRecord]] | Trigger called before a related record is removed. | 1.1.6 |- | [[beforeSave]] | Trigger called before a given record is saved (insert or update). | 0.5 |- | [[beforeInsert]] | Trigger called before a given record is inserted. | 0.5 |- | [[beforeUpdate]] | Trigger called before a given record is updated. | 0.5 |- | [[init]] | This method is called the first time the table is loaded. It allows you to specify initialization details. | 0.8 |} ====Field Filters==== {| class="listing listing2" ! Name ! Description ! Version |- | fieldname__htmlValue | Returns the value of the field "fieldname" for a given record as HTML. | 0.5 |- | fieldname__display | Returns the value of the field "fieldname" appropriate for displaying. | 0.5 |- | [[fieldname__default]] | Returns the default value for the field ''fieldname''. New record forms will be prepopulated with this value. | 0.7 |- | [[fieldname__validate]] | Validates the input for the field ''fieldname''. | 0.6 |- | fieldname__parse | Parses the input value for the field ''fieldname''. This is called by Xataface inside the setValue() method or each record to normalize input values before they are stored in the object (not the database). | 0.5 |- | fieldname__toString | Converts the value of the field ''fieldname'' to a string. This string representation is used as the basis for most higher level data retrieval methods (such as serialize and display). This could be treated as an inverse to the [[fieldname__parse]] method. | 0.5 |- | fieldname__serialize | Converts a value of the field ''fieldname'' to be saved in the database. This should return a string representation of the value that is suitable for database storage. | 0.5 |- | fieldname__link | A link that appears beside the field ''fieldname'' on the edit form. | 0.6 |- | [[field__pushValue]] | Converts form input for field ''fieldname'' to be ready to store in a Dataface_Record. | 0.6 |- | [[field__pullValue]] | Converts a value for field ''fieldname'' in a Dataface_Record object to be ready to be inserted as a value on an HTML form. | 0.6 |- | [[field__fieldname]] | Effectively creates a calculated field named "fieldname" available on the given record. | 0.6 |- | [[no_access_text]] | Replace the default NO ACCESS permission text with another text. | 1.1.6 |- | [[no_access_link]] | Replace the default link of the NO ACCESS permission link with another link. | 1.1.6 |} ====Template Customization==== {| class="listing listing2" ! Name ! Description ! Version |- | [[block__blockname]] | Outputs content that is meant to override a slot or a block named "blockname". | 0.6 |} ====List Tab Customization==== {| class="listing listing2" ! Name ! Description ! Version |- | css__tableHeaderCellClass | Returns a custom CSS class for a table header cell (th tag) in the list view. Takes the name of a table column as a parameter. | 2.0alpha2 |- | css__tableRowClass | Returns a custom CSS class for a table row (tr tag) in list view. Takes a Dataface record as a parameter. | 1.2 |- | fieldname__renderCell | Overrides the table cell content for the "fieldname" field in list view with custom HTML. | 1.0 |- | renderRow | Overrides the the html used for a row in list view for the given record. | 0.7 |- | renderRowHeader | Overrides the header for the table in list view. | 0.7 |- | renderRelatedRow | Overrides the html used for a row in a related record list for a given related record. | 1.0 beta 4 |- | renderRelatedRowHeader | Overrides the html used for the header in a related list. | 1.0 beta 4 |} ====Record Metadata==== {| class="listing listing2" ! Name ! Description ! Version |- | [[getBreadCrumbs]] | Returns the bread crumbs (i.e. you are here) for a given record as an associative array of path parts. | 0.6 |- | [[getChildren]] | Returns a list of Dataface_Record objects that are to be considered children of the given record. | 0.8 |- | [[getCreated]] | Returns a unix timestamp marking the date that a record was created. | 0.9 |- | getDescription | Returns a string description summary of this record. This is used for indexing, RSS feeds, and anywhere that a brief summary of a record is appropriate. | 0.7 |- | getPublicLink | Returns the public URL of this record (in case it is different than the standard URL). | 0.8 |- | getTitle | Returns the title for a given record. The title is used in various parts of the application to represent the record. | 0.5 |- | [[getURL]] | Overrides the getURL() method for a record. Returns the URL that should be used to display the given record. | 0.6 |- | titleColumn | Returns a string SQL select expression that is used to describe the title of records. | 0.5 |} ====View Tab Customization==== {| class="listing listing2" ! Name ! Description ! Version |- | [[How_to_Add_Custom_Sections_to_View_Tab|section__sectionname]] | Defines a section to be displayed in the view tab for the given record. | 0.7 |} ====Search Setup==== {| class="listing listing2" ! Name ! Description ! Version |- | getSearchableText | If [[_index|Indexing]] is turned on, then this returns the text that should be stored in the index for this record for searchability. | 1.0 |} ====RSS Feed Customization==== {| class="listing listing2" ! Name ! Description ! Version |- | [[getFeedItem]] | For RSS Feeds, overrides the defaults and returns an associative array with feed elements for a particular record | 1.0 |- | [[getFeed]] | For RSS feeds, overrides the default feed for a query, returning an array of feed items. | 1.0 |- | getFeedSource | Overrides the default feed source parameter for an RSS feed. | 1.0 |- | [[getRelatedFeed]] | For RSS feeds, overrides the default feed for a related feed. | 1.0 |- | getRSSDescription | Overrides the default generated RSS description for a record. | 1.0 |} ===XML Output Customization=== {| class="listing listing2" ! Name ! Description ! Version |- | [[toXML]] | Overrides the default XML produced for a record in the [[export xml]] action. Returns an XML string. | 1.2.7 |- | [[getXMLHead]] | Returns a string to be included at the beginning of XML output for a particular record. (just inside the opening tag). | 1.2.7 |- | [[xmlTail]] | Returns a string to be included at the end of XML output for a particular record. (just inside the closing tag). | 1.2.7 |} ====Valuelist Customization==== {| class="listing listing2" ! Name ! Description ! Version |- | [[valuelist__valuelistname]] | Defines a valuelist named ''valuelistname''. | 0.7 |} ====Importing Records==== {| class="listing listing2" ! Name ! Description ! Version |- | [[__import__filtername]] | Defines an import filter to named ''filtername'' which is used to import records into the table. | 0.7 |} RSS,Feeds,delegate classes, triggers en 0 GettingStarted:delegate_classes 80 Delegate Classes ==Delegate Classes== Use Delegate classes to add permissions, custom serialization, display filters, calculated fields, import/export functionality, and other custom functionality to your application. For many applications, the configuration files provide sufficient to make them fit the requirements. However, in some cases you may feel the need to "extend" or "bend" your application even more. For these situations, there are delegate classes. ===What is a delegate class?=== A delegate class is a PHP class that defines custom behavior, functions, and fields for a table in a Xataface application. A table may have only 1 delegate class. What kinds of things can a delegate class do? * Define permission rules for tables, records, and relationships. * Define calculated fields. * Define custom serialization/deserialization of fields (useful for XML storage) * Define custom event handlers (actions to be performed when certain events take place) * Define import / export filters. * Define custom titles for records * more ... ===How to create a delegate class=== I will describe the creation process with an example. Referring back to our FacultyOfWidgetry application, let's add a delegate class for the 'Program' table. This is done as follows: # Create a file named 'Program.php' in the Program table configuration directory (i.e., 'tables/Program/Program.php). Your application directory structure should now look like:<nowiki><br/></nowiki>[[Image:http://framework.weblite.ca/documentation/tutorial/getting_started/delegate-class-fs-1.gif]] # Add the following contents to your newly created 'Program.php' file:<code><? class tables_Program {} </code><nowiki><p> In other words, you are creating a class named 'tables_Program'. The above delegate class doesn't do anything yet, but it is a start. The fun part doesn't start until you start defining methods in your delegate class. There are prescribed interfaces that you will need to implement to make this work.</p></nowiki> ===Example 1: Creating a custom title for records=== The "Title" of a record is a string that represents the record. It is used by Xataface in the navigation controller (forward and back buttons) and in the "Jump" menu as well as various places around the interface for referring to that record. As an example, take a look at this partial screen shot of the 'details' tab in a Xataface application. [[Image:http://framework.weblite.ca/documentation/tutorial/getting_started/getTitle-1.gif]] I have circled the parts of the interface that use a record's title in some way. (1), (2), and (4) show the title of the current record and (3) shows the title of the next record in the found set. You will notice that the title is just the value of the first field in the Program record. In fact, the way that Xataface generates titles is by selecting the first VARCHAR or CHAR field in the table to be the Title for records of that table. In the above example this seems like a good choice, but it may not always be what you want. We can use our delegate class to customize the way that these titles are generated. By defining a method named getTitle(), we can customize the way that titles are generated. Let's add such a method to our delegate class as follows: <code> <? class tables_Program { function getTitle(&$record){ return $record->val('ProgramName').' Program'; } } </code> OK, you are probably wondering what this $record object is. The $record object is a Dataface_Record object that represents a record of the 'Program' table (if you want to take a look at the source code for this class it can be found in the 'Dataface/Record.php' file). This object allows you to access all of the information about the record so that you can generate a title for the record. The 'val' method simply returns the value of a field in the record. In the above example, we are telling Xataface that the title of all records of the 'Program' table is the value of the ProgramName field with the string 'Program' appended to it. For example, if the ProgramName of a record was 'Foo', then its title woud be 'Foo Program'. Lets take a look at our application now to see the changes that we have made. [[Image:http://framework.weblite.ca/documentation/tutorial/getting_started/getTitle-2.gif]] Notice that the (1) now has 'Program' appended to the end of the title, but (2) and (3) do not. This is because (2) and (3) are part of the result controller (for navigating through results in the table) and it needs to be able to load hundreds of record titles at a time, but the getTitle() method requires that the entire record be loaded into memory for it to work which would be unfeasible when we need the title of hundreds of records. The result controller titles can also be customized, however, using the titleColumn() method, which simply returns the name of the column that should be used as the title. It can also return MySQL clauses that are equivalent to a column name (e.g., CONCAT('FirstName', ' ', 'LastName') would be valid). Okay, let's add a titleColumn() method to our delegate class so that we can customize the way our records are represented in the result controller: <code> <? class tables_Program { function getTitle(&$record){ return $record->val('ProgramName').' Program'; } function titleColumn(){ return 'AdmissionDeadline'; } } </code> All that the titleColumn method does is return the name of a column to be used as the title for records of the 'Program' table. In this case, we making the 'AdmissionDeadline' field the title column which results in the result controller looking like this: [[Image:http://framework.weblite.ca/documentation/tutorial/getting_started/titleColumn-1.gif]] This was a simple example, but it is possible to do more with the titleColumn() method than just specify the name of a column. Any valid MySQL calculation that can be placed in a SELECT list can be returned here. For example, we can make use of the MySQL 'CONCAT' function to append the string 'Program' to the 'ProgramName' field and achieve the same results as our previous getTitle() method: <code> <? class tables_Program { function getTitle(&$record){ return $record->val('ProgramName').' Program'; } function titleColumn(){ return "CONCAT(ProgramName, ' Program')"; } } </code> And now we can see the changes in our application: [[Image:http://framework.weblite.ca/documentation/tutorial/getting_started/titleColumn-2.gif]] It may seem a little bit inconvenient to have to define 2 methods to effectively customize the title of a record. Future versions may attempt to address this issue so that one or the other can be implemented, but for now, both methods must be implemented to effectively customize the title. In addition, future versions will likely add the 'titleColumn' functionality to an INI file since it is more or less static. ===Summary=== In this section we learned how to add a delegate class to our tables to customize the behavior of our applications. Delegate class become more important when you need very fine-grained customizations to your application, as you will see in later sections. One important feature of delegate classes is the ability to add security permissions to tables and records to limit who can view, edit, and delete certain records. This will be covered in the next section. delegate classes,getTitle,getPermissions en 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 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