preferences 10 preferences ==Xataface Preferences== [[toc]] Xataface preferences can be defined in 3 ways: # In the ''[_prefs]'' section of rhe [[conf.ini file]] for global static preferences. # Implementing the [[getPreferences]] method in the [[Application Delegate Class]] # In the [[__prefs__]] section of the fields.ini file for a table for static preferences on that table. (Limited to only certain preferences). ===Example [_prefs] section=== In the conf.ini <code> [_prefs] hide_updated=1 hide_posted_by=1 </code> ===Example [[getPreferences]] method=== In the [[Application Delegate Class]]: <code> function getPreferences(){ return array('hide_update'=>1, 'hide_posted_by'=>1); } </code> ===Available Preferences=== {| class="listing listing2" ! Name ! Description ! Default ! Version |- | show_result_stats | Show the result statistics (e.g. found x of y records in table z) | 1 | 0.6 |- | show_jump_menu | Show he drop-down menu that allows you to "jump" to any record in the found set. | 1 | 0.6 |- | show_result_controller | Show Next, previous, page number .. links... | 1 | 0.6 |- | show_table_tabs | Show Details, List, Find, etc... tabs. | 1 | 0.6 |- | show_actions_menu | Show New record, Show all, delete, etc.. | 1 | 0.6 |- | show_logo | Show logo at top of app | 1 | 0.6 |- | show_tables_menu | Show the tabs to select a table. | 1 | 0.6 |- | show_search | Show search field in upper right. | 1 | 0.6 |- | show_record_actions | Show actions related to particular record | 1 | 0.6 |- | show_bread_crumbs | Show bread crumbs at top of page to show where you are. | 1 | 0.6 |- | show_record_tabs | View, Edit, Translate, History, etc... | 1 | 0.6 |- | show_record_tree | Show tree to navigate the relationships of this record. | 1 | 0.6 |- | list_view_scroll_horizontal | Whether to scroll list horizontal if it exceeds page width | 1 | 0.6 |- | list_view_scroll_vertical | Whether to scroll list vertical if it exceeds page height. | 1 | 0.6 |- | hide_posted_by | Whether to hide the ''posted by'' text in glance lists (e.g. in the view tab, the related records are shown in the left column. This hides the ''posted by'' text next to each related record. | 0 | 1.0b4 |- | hide_updated | Whether to hide the ''updated'' text in the glance lists (e.g. in the view tab, the related records are shown in the left column. This hides the ''updated'' text next to each related record. | 0 | 1.0b4 |- | SummaryList_logo_width | The width of the logo to be used as the preview image in summary lists. | null | 0.7 |- | SummaryList_hideSort | Hides the sort control for a summary list (the box that allows users to sort by column). | 0 | 0.7 |- | hide_user_status | Hides the user's status (e.g. "You are logged in as ..." | 0 | 0.7 |- | hide_personal_tools | Hides the personal tool links in upper right. This includes likes such as "Control Panel" and "My Profile" | 0 | 0.7 |- | hide_resultlist_controller | Hides the controller for a result list (E.g. next/back/results per page etc...). | 0 | 0.7 |- | hide_related_sections | Hides the sections of the view tab that show the related records. These are the sortable section boxes. Not the related tabs. | 0 | 1.3 |- | hide_record_search | Hides the record search form that appears in the view tab. Not to be confused with the find tab. | 0 | 1.3 |- | show_resultlist_controller_only_when_needed | Sets the resultlist controller (e.g. back/next/results per page/etc...) to only show up if paging is required (i.e. if there are more records than can be shown on one page (according to the '-limit' parameter). | 0 | 1.0 |- | hide_record_view_logo | Hides the logo for a record that appears in the upper left of the view tab for each record. | 0 | 0.7 |- | horizontal_tables_menu | Whether to force the tables menu to appear as tabs along the top of the page (alternative is as a menu on the left). If there are 10 or fewer allowed tables, then the default is 1, otherwise the default is set to 0. | 1 | 0.6 |- | hide_result_filters | In list view, setting this value to 1 will cause the column filters to be hidden (the select lists to filter the results). | 0 | 0.7 |- | disable_select_rows | A value of 1 causes the checkboxes in each row of the list view to be hidden. | 0 | 0.7 |- | result_list_use_geturl | Use the getURL() method to link to records in the list view rather than the default (which uses the -cursor parameter). | 0 | 0.7 |- | disable_ajax_record_details | Whether to disable the ajax record details (the '+' sign beside each record in list view that expands to show the record details. | 1 | 0.7 |- | use_old_resultlist_controller | As of Xataface 1.1, a new style result list controller is used that resembles facebook. It is more slimmed down and is easier to manage. If you prefer the old controller, set this preference to 1. | 0 | 1.1 |} ===Inverse Preferences=== The following preferences perform the inverse of some of the options above. When these options are set to 1, their respective option is set to 0. {| class="listing listing2" ! Name ! Inverse |- | hide_nav_menu | show_tables_menu |- | hide_view_tabs | show_table_tabs |- | hide_result_controller | show_result_controller |- | hide_table_result_stats | show_result_stats |- | hide_search | show_search |} preferences, prefs, getPreferences en 0 Authenticating_Against_the_PHPBB_Users_table 92 Authenticating Against the PHPBB Users Table Return to [[authentication]] [[toc]] Xataface is able to use the PHPBB users table to authenticate against so that, you can allow your users to log into your Xataface application using the same credentials as they use to access your PHPBB message forum. Achieving this level of integration requires 2 simple steps: # Set up the [[_auth]] section of your [[conf.ini file]] to reference the PHPBB users table and the correct username and password columns. # Specify the correct encryption on the password column. This step will be different for different versions of PHPBB. ==PHPBB 2== PHPBB version 2 and lower simply use MD5 encryption on the password column, which Xataface supports natively via the [[encryption]] directive of the [[fields.ini file]]. Therefore we can set up our Xataface application to authenticate against our PHPBB2 database ('''assuming that our PHPBB is set up in the same database as our Xataface app''') by doing the following: # Set up the [_auth] section of the [[conf.ini file]] as follows:<code> [_auth] users_table = phpbb_users username_column = username password_column = user_password </code> # Set up the user_password field to use md5 encryption in the ''tables/phpbb_users/fields.ini'' file <code> [user_password] encryption=md5 </code> That's it! Now you should be able to log into your Xataface application using the username/password from PHPBB. ==PHPBB 3== PHPBB version 3 and higher uses a custom encryption function for the password column so it is a little more complicated (but not that much). Step one (the [[conf.ini file]]) is the same as for PHPBB version 2 listed above. The 2nd part, however, requires us to implement a custom serialization for the user_password field. So the steps are below: # Set up the [_auth] section of the [[conf.ini file]] as follows:<code> [_auth] users_table = phpbb_users username_column = username password_column = user_password </code> # Implement the user_password__serialize() method in your phpbb_users delegate class (i.e. the ''tables/phpbb_users/phpbb_users.php'' file):<code> <?php class tables_phpbb_users { function user_password__serialize($password){ $itoa64 = './0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz'; $sql = "select user_password from phpbb_users where username='".addslashes($_POST['UserName'])."'"; $res = mysql_query($sql, df_db()); if ( !$res ) throw new Exception(mysql_error(df_db())); $row = mysql_fetch_assoc($res); mysql_free_result($res); $hash = $this->_hash_crypt_private($password, $row['user_password'], $itoa64); return $hash; } /** * The crypt function/replacement */ function _hash_crypt_private($password, $setting, &$itoa64) { $output = '*'; // Check for correct hash if (substr($setting, 0, 3) != '$H$') { return $output; } $count_log2 = strpos($itoa64, $setting[3]); if ($count_log2 < 7 || $count_log2 > 30) { return $output; } $count = 1 << $count_log2; $salt = substr($setting, 4, 8); if (strlen($salt) != 8) { return $output; } /** * We're kind of forced to use MD5 here since it's the only * cryptographic primitive available in all versions of PHP * currently in use. To implement our own low-level crypto * in PHP would result in much worse performance and * consequently in lower iteration counts and hashes that are * quicker to crack (by non-PHP code). */ if (PHP_VERSION >= 5) { $hash = md5($salt . $password, true); do { $hash = md5($hash . $password, true); } while (--$count); } else { $hash = pack('H*', md5($salt . $password)); do { $hash = pack('H*', md5($hash . $password)); } while (--$count); } $output = substr($setting, 0, 12); $output .= $this->_hash_encode64($hash, 16, $itoa64); return $output; } /** * Encode hash */ function _hash_encode64($input, $count, &$itoa64) { $output = ''; $i = 0; do { $value = ord($input[$i++]); $output .= $itoa64[$value & 0x3f]; if ($i < $count) { $value |= ord($input[$i]) << 8; } $output .= $itoa64[($value >> 6) & 0x3f]; if ($i++ >= $count) { break; } if ($i < $count) { $value |= ord($input[$i]) << 16; } $output .= $itoa64[($value >> 12) & 0x3f]; if ($i++ >= $count) { break; } $output .= $itoa64[($value >> 18) & 0x3f]; } while ($i < $count); return $output; } } </code> PHPBB, authentication, security, authentication modules en permissions.ini_file 26 permissions.ini_file ==The permissions.ini File== [[toc]] The permissions.ini file stores custom permissions and roles that can be used by an application. It is an optional file that should be placed in the application root directory (i.e. the same directory where your conf.ini, and index.php files are located). The permissions.ini file allows you to define two things: # Permissions # Roles (i.e. sets of permissions). Permissions and roles are used throughout Xataface to limit access to actions, records, fields, and relationships. For example, each action in your application can specify a permission that is necessary to perform the action. Your delegate classes may include getPermissions() methods to define what permissions a user gets when interacting with different records. This file (permissions.ini) simply defines the permissions that can be used by your application. It doesn't actually assign those permissions. Assigning permissions is the job of the getPermissions() (or getRoles()) method. ===Defining Permissions=== Permissions are defined by standalone properties in the beginning of the permissions.ini file. For example, if you were desiging a proof-reading application, you might need permissions for "submit_for_proof", or "approve_text" to correspond with the submitting a document to be proof-read, and approving a document's proof. In this case we would have the following at the beginning of our permissions.ini file: <code> submit_for_proof = Submit a document to be proofread approve_text = "Approve this document's proof" </code> The left side of the equals sign is the name of the permission. The right side contains a human readable description of the permission and what it is for. ===Limiting Access to Actions based on Permissions=== At this point these permissions don't do anything. In order to be useful we need reference these permissions from an action or a section. For example, let's create an action called "submit_for_proof" which displays a form for a user to submit a document record to be proofread. Our actions.ini file entry might look something like: <code> [submit_for_proof] url="{$this->url('-action=submit_for_proof')}" label="Submit document for proof" category=record_actions permission=submit_for_proof template=submit_for_proof.html </code> And for completeness, since this make-believe action specifies th "submit_for_proof.html" template, we'll create the "submit_for_proof.html" template in the templates directory: <code> <html><body>You have permission to perform this action.</body></html> </code> ===Defining Who Get's Which Permissions=== Finally, in order to benefit from permissions, your application has to decide that it is going to use permissions (unless you define a getPermissions() method, users are granted ALL permissions by default. Hence if you try to access our submit_for_proof action, we'll see it without any problem. Regardless of who we are. So let's create a simple, but restrictive getPermissions() method in our application delegate class: <code> <?php class conf_ApplicationDelegate { function getPermissions(&$record){ return Dataface_PermissionsTool::READ_ONLY(); } } </code> Now if we try to access our submit_for_proof action it will give us a "Permission Denied" message, because we are only granted READ ONLY permissions (which is a role that includes the view permission and some others - but not our custom "submit_for_proof" permission. Now we'll make a small modification to our getPermissions() method to provide us with our submit_for_proof permission: <code> <?php class conf_ApplicationDelegate { function getPermissions(&$record){ $perms = Dataface_PermissionsTool::READ_ONLY(); $perms['submit_for_proof'] = 1; return $perms; } } </code> Now if we try to access our submit_for_proof action, it will show us our template with no error messages (hopefully). ===Roles=== Roles are sets of permissions. They are defined in the permissions.ini file as sections with lists of included permissions. It might be handy to create roles such as EDITOR or MANAGER which contain sets of permissions that are meant to be assigned to users of those types. For example an EDITOR may have the view and edit permissions, but not the delete permission. A MANAGER might have the view, edit, and delete permissions. You can define these two roles in the permissions.ini file as follows: <code> [EDITOR] view=1 edit=1 [MANAGER] view=1 edit=1 delete=1 </code> Then we could assign these roles to users using the Dataface_PermissionsTool::getRolePermissions() method: <code> function getPermissions(&$record){ $user =& Dataface_AuthenticationTool::getInstance()->getLoggedInUser(); if ( $user and $user->val('role') == 'EDITOR' ){ return Dataface_PermissionsTool::getRolePermissions('EDITOR'); } else if ( $user and $user->val('role') == 'MANAGER' ){ return Dataface_PermissionsTool::getRolePermissions('MANAGER'); } return Dataface_PermissionsTool::READ_ONLY(); } </code> Or equivalently we could use the getRoles() method of our delegate class instead of getPermissions(): <code> function getRoles(&$record){ $user =& Dataface_AuthenticationTool::getInstance()->getLoggedInUser(); if ( $user and $user->val('role') == 'EDITOR' ){ return 'EDITOR'; } else if ( $user and $user->val('role') == 'MANAGER' ){ return 'MANAGER' } return 'READ ONLY'; } </code> ===Xataface Core Permissions & Roles=== Xataface is distributed with its own permissions.ini file that defines some core permissions and roles. You can look at this permissions.ini file (located in the Xataface directory) to see what the format should look like. Any settings you place in your application's permissions.ini file will augment or override settings in Xataface's file. Some core permissions include: {| class="listing listing2" |- ! Name ! Description ! Version |- | view | Permission to view a record or field. This permission is required to access the view tab, and several other details tabs. | 0.6 |- | list | Permission to access the list tab. | 0.6 |- | calendar | Permission to access the calendar tab. | 0.6 |- | edit | Permission to edit a record or field. This also gives access to the edit tab. | 0.6 |- | new | Permission to edit a record or field for the purpose of creating a new record. This permission is required to access the new record form. | 0.6 |- | select_rows | Permission to select rows in list view to perform actions on them. | 0.6 |- | post | Permission to post a record using HTTP POST | 0.6 |- | copy | Permission to copy a record. | 0.6 |- | update_set | Permission to perform an update on a result set (i.e. access the update set action). | 0.8 |- | add new related record | Permission to add a new record to a relationship. See [[Relationship Permissions]] | 0.6 |- | add existing related record | Permission to add an existing record to a relationship. See [[Relationship Permissions]] | 0.6 |- | view related records | Permission to view the records in a relationship. See [[Relationship Permissions]] | 1.0 |- | delete | Permission to delete a record. | 0.6 |- | delete found | Permission to access the delete found set action (to delete multiple records at a time). | 0.6 |- | show all | Permission to access show all records action. | 0.6 |- | remove related record | Permission to remove a record from a relationship. See [[Relationship Permissions]] | 0.6 |- | delete related record | Permission to delete a record in a relationship. This is stronger than the remove related record permission in that it allows the user to delete the record from the database. See [[Relationship permissions]] | 0.6 |- | find | Permission to perform the find action. | 0.6 |- | import | Permission to perform the import action (to import records into the database). | 0.6 |- | export_csv | Permission to perform the Export CSV action (to export the result set in comma-separated-value format). | 0.6 |- | export_xml | Permission to perform the Export XML action (to export the result set as XML). | 0.8 |- | translate | Permission to translate a record into another language. This permission provides access to the "translate" tab. | 0.8 |- | history | Permission to view history information for a record (e.g. the history tab). This requires that history be enabled. | 0.8 |- | edit_history | Permission to edit history information such as undo/redo support for a record. | 0.8 |- | navigate | Permission to navigate through records of a table. | 0.6 |- | reorder_related_records | Permission to reorder the records of a relationship (this is different than just sorting). It sets a default order for the records. Requires the metafields:order directive to be set for the relationship. | 0.6 |- | ajax_save | Permission to save a record through AJAX. | 0.8 |- | ajax_load | Permission to load a record through AJAX. | 0.8 |- | ajax_form | Permission to access the inline editing ajax form for a record. | 0.8 |- | find_list | Permission to search current table. | 0.6 |- | find_multi_table | Permission to perform a site-wide search. | 0.8 |- | register | Permission to register for an account. | 0.8 |- | xml_view | Permission to view a result set as xml. | 0.8 |- | view_xml | View the XML for an individual record. | 0.8 |- | manage_output_cache | Management permission to clear the output cache. | 0.8 |- | manage_migrate | Permission to access the migration tool to migrate between versions. | 0.8 |- | manage | Permission to access the management control panel. | 0.8 |- | manage_build_index | Permission to rebuild the search index. | 0.8 |- | expandable | Whether the record can be expanded in the left nav menu | N/A |} Some core roles include: {| class="listing listing2" |- ! Name ! Permissions Included ! Version |- | READ ONLY | view, list, calendar, view xml, show all, find, navigate, ajax_load, find_list, find_multi_table, rss, export_csv, export_xml, and export_json | 0.6 |- | EDIT | All permissions in READ ONLY, and edit, add new related record, add existing related record, add new record, remove related record, reorder_related_records, import, translate, new, ajax_save, ajax_form, history, edit_history, copy, update_set, and select_rows | 0.6 |- | DELETE | All permissions in EDIT, and delete and delete found. | 0.6 |- | OWNER | All permissions in DELETE except navigate, new, and delete found. | 0.6 |- | REVIEWER | All permissions in READ ONLY, and edit and translate. | 0.6 |- | USER | All permissions in READ ONLY, and add new related record. | 0.6 |- | ADMIN | All permissions in DELETE and xml_view | 0.6 |- | MANAGER | All permissions in ADMIN and manage, manage_output_cache, manage_migrate, manage_build_index, and install. | 0.6 |} ===Extending and Overriding Roles=== The cleanest and easiest way to define a new role is to extend an existing role. Xataface allows you to extend roles via the '''extends''' keyword. For example, if you wanted to create a role '''TEST ROLE''' that contained all of the same permissions as the READ ONLY role, you could define it as follows in your application's permissions.ini file: <code> [TEST ROLE extends READ ONLY] </code> If we wanted it to contain the same permissions as READ ONLY but to also allow the edit permission we would define it as: <code> [TEST ROLE extends READ ONLY] edit=1 </code> If we wanted to disallow the list permission, we would do something like: <code> [TEST ROLE extends READ ONLY] edit=1 list=0 </code> ===Overriding Existing Roles=== You can also redefine existing roles: <code> [READ ONLY extends READ ONLY] my_permission=1 </code> This is handy if you have added your own custom permissions that you feel should be included in a core role. Note that there are some caveats regarding the order of how these roles are defined. Please refer to this forum post for more details: [http://www.xataface.com/forum/viewtopic.php?t=6187 Overriding Roles / Permissions] ==See Also== * [[Relationship Permissions]] * [[getPermissions]] - The getPermissionsMethod * [[Delegate class methods]] - Delegate class methods. * [http://xataface.com/documentation/tutorial/getting_started/permissions Getting started with Xataface permissions] permissions.ini, getPermissions, permissions en 0 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 _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 modules 30 Xataface Modules [[toc]] Xataface provides a number of hooks that allow developers to create modules to extend its functionality. This page lists a handful of the currently available modules. * [[ShoppingCart|Shopping Cart]] - Converts your application into a shopping cart. * [[Filemaker]] - Export record sets as Filemaker XML. * [[DataGrid|Data Grid]] - Editable Datagrid. * [[Email]] - Convert your database into a email list. Send email to any found set. * [[reCAPTCHA module]] - A reCAPTCHA module to add CAPTCHA support to your Xataface forms. * [[XataJax]] - Platform for building Web 2.0 AJAX applications with Xataface. Will be a standard component for Xataface starting with version 1.3. ==Module Installation== You can add modules in either: # DATAFACE_PATH/modules directory (since 1.0) # DATAFACE_SITE_PATH/modules directory (since 1.3) Modules in the DATAFACE_SITE_PATH directory will supersede modules in the DATAFACE_PATH/modules directory (since 1.3). To activate a module for your application you also need to add an entry to the [[_modules]] section of your [[conf.ini file]]. Each module will come with its own installation instructions. ==Authentication Modules== Modules to add alternative authentication methods are added to the modules/Auth directory. ==Developing Your Own Modules== See [[Module Developers Guide]]. modules, captcha en 0 Module_Developers_Guide 112 Module Developers Guide [[toc]] ==Why Write a Xataface Module?== Xataface modules are components that can be used to extend Xataface's functionality in a generic way so that it can be used on multiple applications. If you find yourself trying to add the same functionality in multiple applications, you might consider writing a Xataface module so that you can share the functionality more easily. ==What can you do with a Xataface Module== * Create custom authentication handlers. * Provide custom actions and templates. * Implement blocks and slots for existing templates. * Respond to certain application triggers. ==Where do I place a Xataface Module?== Xataface modules can be placed in the xataface/modules directory (i.e. DATAFACE_PATH/modules). As of Xataface 1.3 they can also be placed directly in your application's modules directory (i.e. DATAFACE_SITE_PATH/modules). ==Your first module== For our first module, we're going to create a simple module that adds "hello world" at the beginning of every page. ===Step 1: Create the Module Class=== In your modules directory, create a directory called "Hello". And in this directory, create a file named "Hello.php", with the following contents: <code> <?php class modules_Hello { } </code> (So this file would be located at DATAFACE_PATH/modules/Hello/Hello.php) ===Step 2: Implement the block__before_body method=== We are going to add the phrase "hello world" before every page of our application. The easy way to do this is to fill the [[before_body]] slot of the [[Dataface_Main_Template.html]] template. We do this by implementing the ''block__before_body'' method in your module (just as we would if we were trying to fill this slot from the [[Application Delegate Class]]. <code> <?php class modules_Hello { function block__before_body(){ echo "hello world"; return true; } } </code> ===Step 3: Activate the Module=== Xataface only loads the modules that have been enabled in the conf.ini. We can enable our module by adding the following section to the [[conf.ini file]]: <code> [_modules] modules_Hello=modules/Hello.php </code> All this does is tell Xataface that the module class modules_Hello can be loaded from the location modules/Hello.php. Now if you start up your application, you should see the phrase "hello world" written at the top of each page. ==Example 2: Adding a Custom Action== Our first module shows an example of filling blocks and slots using a module. Let's now extends that to include a custom action that displays Hello World on its own page. Complete the following steps: # Add an ''actions'' directory inside our new module directory. i.e. modules/Hello/actions # Add a file named hello.php inside the ''actions'' directory with the following contents:<code> <?php class actions_hello { function handle($params){ echo "Hello World"; } } </code> # Go to index.php?-action=hello To see the results of your action. It should say "Hello World" on a blank page. From here on you can improve this action just as you would if you defined the action inside the application's actions directory. You can go on to restrict access to this action using permissions, or you could decide to use a template to display the action. ===Defining a Custom "hello" permission for our action=== Perhaps we want to create a special permission for our action so that regular users won't have access to this action unless they are specifically granted this permission. Let's create a "hello" permission with which to limit access to our action. # Create a file named "permissions.ini" inside your modules/Hello directory with the following contents:<code> hello = Permission to access the hello action </code> Now if you try to access your action (and you haven't been assigned ALL() permissions) you should receive either a login prompt or a permission denied message. If you want users to be able to access your action, you will need to explicitly add this permission to one of the user's assigned roles or return it as part of the list of authorized permissions in the getPermissions() method. ===Granting the "hello" permission to the "READ ONLY" role=== If we want the default READ ONLY role to have access to the "hello" permission we can actually modify the READ ONLY role inside the [[permissions.ini file]] that we created inside the Hello module: <code> hello = Permission to access hello action [READ ONLY extends READ ONLY] hello=1 </code> ==Example 3: Using Module Templates== Xataface, by default, stores its templates in the DATAFACE_SITE_PATH/templates and DATAFACE_PATH/templates directories. However if you are writing a module you probably want to keep templates that are used by the module inside the module directory so that you don't break dependencies when you use the module in different applications. You can use the [http://dataface.weblite.ca/df_register_skin df_register_skin] method to register additional directories for Xataface to look for templates in. This will allow you to add a ''templates'' directory inside your module directory for use by your module's templates. It is probably best to register this directory on demand (i.e. as part of individual actions) rather than register it globally. ===Using a Template from the hello action=== Let's modify our hello action to use a template that we are going to store and distribute with our module. # Create a directory named "templates" in the modules/Hello directory. # Create a file named "hello.html" inside the templates directory with the following contents:<code> {use_macro file="Dataface_Main_Template.html"} {fill_slot name="main_section"} Hello World {/fill_slot} {/use_macro} </code> Notice that we are extending the Dataface_Main_Template.html template (which is located in the main Xataface install) so that our hello action can now take on the look and feel of the rest of the application. # Modify the modules/Hello/actions/hello.php file to look like this:<code><?php class actions_hello { function handle($params){ df_register_skin('hello theme', dirname(__FILE__).'../templates'); df_display(array(), 'hello.html'); } } </code> Notice that we call the df_register_skin function to register the templates directory that we created in the previous step. Then we call df_display() to display the template. ==See Also=== * [[modules]] - A list of existing Xataface modules that you can download and install. * [[block__blockname]] - A list of some of the available blocks that can be filled in the default Xataface templates. * [http://xataface.com/documentation/tutorial/customizing-the-dataface-look-and-feel Customizing Xataface's Look and Feel with Templates] - A tutorial on how to use Xataface's built-in smarty template engine. It has some sections on using delegate classes to override blocks and slots. * [http://xataface.com/documentation/tutorial/getting_started/changing-look-and-feel Changing Xataface's Look and Feel] - Part of the Getting Started tutorial that shows how to use slots and blocks to customize the Xataface look and feel. modules en lookup 61 The Lookup Widget Return to [[widget:type]] page to see list of all widget types. Back to [[fields.ini file]] to see other fields.ini directives. [[toc]] ===Synopsis=== The lookup widget allows users to look a record from another table to insert into the field. It is like a select widget except that it doesn't use a vocabulary. Instead you just specify a table on which it should search using the widget:table directive. In order to use the lookup widget to edit a field, you should set the [[widget:type]] directive of the [[fields.ini file]] for the field to '''lookup''. I.e. <code> [fieldname] widget:type=lookup widget:table=mytable </code> '''Note that the lookup widget requires the [[widget:table]] directive to be set to the target table of the lookup or it will not work properly.''' ===Required Directives=== The following [[fields.ini file]] directives are required to accompany the field definition if a lookup widget is used: {| class="listing listing2" |- ! Name ! Description ! Version |- | widget:table | The name of the table in which the lookup widget should look up related records. | 1.0 |} ===Optional Directives=== The following additional optional directives may be used to customize the behaviour of the lookup widget: {| class="listing listing2" |- ! Name ! Description ! Version |- | widget:filters:-limit | Sets the number of records that are shown by default in the lookup widget. Default is 30 if this is omitted. E.g.<code>widget:filters:-limit=100</code> to show 100 records at a time. | 1.0 |- | widget:filters:-sort | Specifies the columns to sort the results on. E.g. <code>widget:filters:-sort=category_name asc, year desc</code> | 1.0 |- | widget:filters:* | Any valid Xataface directive can be used to filter the results by specifying widget:filters:param (where "param" is a valid Xataface GET parameter, which could include a column name to filter results on, or other filter directives). <code>widget:filters:country=Canada</code> To only show results with Country=Canada. | 1.0 |- | widget:filters:*=$* | Dynamic filters. Causes the options in the record browser to be filtered on the value of another field in the form. e.g. <code>widget:filters:country_id="$country_id"</code> would show only results with records having country_id matching the value of the 'country_id' field in the current form. | 1.3.1 |} See [[URL Conventions]] for an overview of the types of GET parameters Xataface can take. Any GET parameters that manipulate a query can be used with the widget:filters:* directive to modify the query results that are shown in the lookup widget. ===Example=== In this example we have a field named appointee that is supposed to reference the contacts table. So in the [[fields.ini file]] we would have: <pre> [appointee] widget:type=lookup widget:table=contacts </pre> Initially we just have a little find icon next to the field. If the user clicks it, a dialog pops up enabling them to search for the contact that they want: [[Image:http://media.weblite.ca/files/photos/Picture%2023.png?max_width=640]] ===Additional Tips=== Although the lookup widget does not use a vocabulary as indicated in the Synopsis above, it is still useful to define a vocabulary in the fields.ini file for this field. The reason is because the lookup widget is only used with the edit action, where you are inserting or editing data into the field. However, it is not used to the display the data in the view or list actions. Therefore, you must still have a vocabulary defined to properly display these values. In order to customize the display of the lookup widget's select list, you must edit the delegate class for the table which is referenced by the widget:table directive. There are two important points to note: # The items in the selection list are formatted based on the getTitle(&$record) delegate class function if it is defined. However, ... # The Search box will search on text in VARCHAR and TEXT fields. If you need to search for data in numeric fields, you can create a grafted field using a function such as CONCAT() to display numbers as text. Links: * [http://xataface.com/forum/viewtopic.php?f=4&t=6723 Lookup widget on view with compound primary key] lookup widget, widget:filters, widget:-filters:limit, widget:table en 0 loginFailed 184 loginFailed() Application Delegate Trigger [[toc]] The loginFailed() method of the Application Delegate class is executed after a failed login attempt. '''Available since 2.0.1''' ==Example== <code> function loginFailed($username, $userIp, $time){ error_log("Failed login for username: $username at IP $userIp at time $time"); } </code> login permissions failed password en LDAP_or_Active_Directory 65 How to authenticate users with LDAP or Active Directory [[toc]] It is often easier to use the existing LDAP or Active Directory to authenticate users in Xataface than to create a new password for every user in the table users. ===In the conf.ini=== In the conf.ini file, in the [auth] part, you need to add your LDAP or AD configuration data : <code>[_auth] auth_type=ldap users_table = xata_users username_column = id ldap_host = "xxx.xxx.xxx.xxx" ldap_port = "389" ldap_base = "OU=blabla,DC=blablabla"</code> Here in the table users, you need the login but the password can be just ''PASS'', because the password will be fetched into the LDAP base. You need to add the [http://weblite.ca/svn/dataface/modules/Auth/ldap/trunk/ auth module] in the conf/modules directory. ===See Also=== * [[authentication]] - Overview of Authenthentication features in Xataface LDAP,Active Directory,Authentication en 0 Key 83 fields.ini Directive: Key The '''Key''' directive is used only when the table is a view and you need to explicitly define which columns are part of the primary key. For example, if we created a view on the books table to only show books in a given year as follows: <code> create view books_2000 as select * from books where year='2000' </code> And we wanted to use this view as a table in our Xataface application we would need to tell it that the primary key of this view is the book_id field. So in the fields.ini file we would add: <code> [book_id] Key=PRI </code> Note that this is case sensitive. key=PRI will not work. ===Compound Primary Keys=== For primary keys comprising multiple columns we would add this directive for each field in the key. E.g. if our books_2000 view had 2 fields in the primary key, say author_id and book_index, we would have in the books_2000 fields.ini file: <code> [author_id] Key=PRI [book_index] Key=PRI </code> Links: * [http://xataface.com/forum/viewtopic.php?f=4&t=6723 Lookup widget on view with compound primary key] Return to [[fields.ini file]] Key, Views, MySQL Views, Create View, PRI, Primary Keys en Authenticating_Against_the_Joomla!_Users_Table 93 Xataface is able to use the joomla users table to authenticate against so that, you can allow your users to log into your Xataface application using the same credentials as they use to access your joomla website. Achieving this level of integration requires 2 simple steps : 1 - Set up the [_auth] section of your conf.ini file to reference the joomla users table and the correct username and password columns. 2 - Create a delegate class for the joomla users table to be able to decrypt the password set in the table. ==Configure the conf.ini file== Joomla users table is named jos_users. So you have to declare this table in the conf.ini file. <code>[_auth] users_table = jos_users username_column = username password_column = password</code> Note that username_column and password_column are very simple... ==Create a delegate class for your users table== Now we have to create a delegate class for the users table to decrypt the passwords set in joomla. Joomla uses a custom md5 encryption. ===Joomla encryption=== When a user is setting a password in joomla, the system does several things : 1 - generate a random key containing alphanumeric characters example : <code>8NdiRqLRKLHaNwudJ3InJknsew9sc7pL</code> 2 - concate the clear entered password with the random key example : <code>password8NdiRqLRKLHaNwudJ3InJknsew9sc7pL</code> 3 - doing a md5 encryption on the result string example : <code>md5(password8NdiRqLRKLHaNwudJ3InJknsew9sc7pL = f2b1fb3996442db549c1ed1a1eebbfe1</code> 4 - concate the md5 string with the random key separated by ":" example : <code>f2b1fb3996442db549c1ed1a1eebbfe1:8NdiRqLRKLHaNwudJ3InJknsew9sc7pL</code> So it's a great encryption but xataface doesn't know how to do that. Here is the utility of the delegate class. We will define a function inside which could compare the entered password in xataface with the joomla stored password. ===Creating the delegate class=== 1 - Add a jos_users directory in your directory table 2 - Create a jos_users.php file inside this new directory ===Creating the decrypt password function=== Before posting this code, I would like to thank fantomasdm who created this function. So here is the code of the function to paste directly in the jos_users delegate class : <code><? class tables_jos_users { function password__serialize($password){ $app =& Dataface_Application::getInstance(); $query = "SELECT id, gid, block, password, usertype FROM jos_users where username='".$_POST['UserName']."'"; $result = mysql_query($query,$app->db()) or die("Query failed" . mysql_error() ); $line = mysql_fetch_array($result, MYSQL_ASSOC); mysql_free_result($result); $arraypass=explode(":", $linea['password']); $key=$arraypass[1]; $ret = md5(trim($password).$key).":".$key; return $ret; } } ?></code> Save your file and test the result. Enjoy ! ;-) joomla authentication md5 en Customizing_Theme_Based_on_IP_Address 103 Customizing Theme Based on IP Address This article deals with the following topics: # Using [[field__pullValue]]/[[field__pushValue]] methods to customize how a field is edited and stored in the database. # Using [[beforeHandleRequest]] to modify the application settings based on the user's IP address # Storing ranges of IP addresses in the database. Last week I set up a site that needed to have slightly different behavior depending on the IP address of the remote user. E.g. If a user is connecting from an IP address between 192.168.0.0 to 192.168.0.255 we would use a different theme than if they were connecting from a different block. In addition to different themes, we also to use different types of authentication depending on which IP block the user is visiting from. This requirement is actually common for systems that are syndicated by different organizations and should behave slightly differently depending on which organization the user belongs to (assuming they are connecting from that organization's network). To implement this behavior we need to solve one issue. '''How do we store a range of IP addresses in the database so that they can be queried easily to match if the user's IP address falls in that range.''' It turns out that this is quite easy to do, since IP addresses are actually just a 4 digit number (base 256). So we can easily convert this number to base 10 and store it as a regular unsigned integer in the database. In addition, both PHP and MySQL provide functions to convert from an IP address to an integer and back. The PHP functions are called [http://ca3.php.net/long2ip long2ip] and [http://ca3.php.net/ip2long ip2long] respectively. So we have stored a start IP address and an end IP address as integers, we could simply query the database to see if a given IP address falls in that range as follows: <code> $intIP = ip2long($_SERVER['REMOTE_ADDR']); $sql = sprintf('select * from ip_blocks where start_ip<=%u and end_ip>=%u', $intIP, $intIP); ... etc.... </code> '''It is important to note that you need to use the sprintf() function for converting $intIP into a string because PHP will convert it to an integer which could overflow if you leave it to do a default conversion.''' For the above query, we assuming a table with a definition like: <code> create table ip_blocks ( ip_block_id int(11) not null primary key, start_ip unsigned int(11) not null end_ip unsigned int(11), key (start_ip), key (end_ip) ) </code> Now if we attach some information to the IP block, like the theme that should be used, we can check the user IP address against the available IP blocks at the beginning of each request to set the theme for that request. We will use the [[beforeHandleRequest]] method of the [[Application Delegate Class]] to house this because it allows us to set things like the theme or change the user's action. e.g. <code> class conf_ApplicationDelegate { function beforeHandleRequest(){ $app = Dataface_Application::getInstance(); // Get a reference to the current query so we can // alter it if necessary. $query =& $app->getQuery(); // Get the user's IP address and covert it to a long int. $intIP = ip2long($_SERVER['REMOTE_ADDR']); $sql = sprintf('select `theme` from ip_blocks where start_ip<=%u and end_ip>=%u', $intIP, $intIP); $res = mysql_query($sql, df_db()); if ( !$res ) throw new Exception(mysql_error(df_db())); $row = mysql_fetch_row($res); // If we didn't find any valid IP ranges, let's redirect the // user to a different action to let them know that // they're not welcome here. if ( !$row ){ $query['-action'] = 'not_welcome'; // This assumes that we have defined an action // called "not_welcome" return; } $theme = $row[0]; $themePath = 'themes/'.basename($theme); // Check that the theme exists. if ( $theme and file_exists($themePath) ){ df_register_skin($theme, $themePath); } } } </code> The above snippet makes use of the [[df_register_skin]] method that registers a theme to be used dynamically. The first parameter is the theme name, and the second parameter is the path to the theme. This code works great if we already have IP addresses stored properly as integers in our database, but how do we make it so users can work with the IP addresses as IP addresses and not integers? We need to be able to transform from integer to IP address to display in the edit record form, and then convert the resulting IP address back to an integer for storage in the database. Xataface provides two delegate class methods precisely for this purpose: # [[field__pullValue]] - Transforms a value as stored in the database to a format that is preferred in the edit form. # [[field__pushValue]] - Transforms a value entered into the edit form into a format that is preferred by the database. So, in our delegate class we would have: <code> <?php class tables_ip_blocks { /** * @param Dataface_Record $record The record we are pushing the value * into * @param HTML_QuickForm_element $el The QuickForm widget that we are * retrieving the value from. */ function start_ip__pushValue($record, $el){ $val = ip2long($el->getValue()); if ( $val !== false ){ return sprintf('%u', $val ); } return null; } function start_ip__pullValue($record, $el){ $val = $record->val('start_ip'); if ( $val ) return long2ip($val); return $val; } function end_ip__pushValue($record, $el){ $val = ip2long($el->getValue()); if ( $val !== false ){ return sprintf('%u', $val ); } return null; } function end_ip__pullValue($record, $el){ $val = $record->val('end_ip'); if ($val){ return long2ip($val); } return $val; } } </code> The [[field__pullValue]] and [[field__pushValue]] method should be inverses of each other. '''Note that support for [[field__pullValue]] and [[field__pushValue]] are supported by Xataface since version 0.6, however support for them with the grid widget was not added until Xataface version 1.3.''' Now, on the edit form, users can enter and edit IP addresses in the normal format, but they will be converted to unsigned integers for storage in the database. There is only one thing remaining, though. In the list view still shows the integer version of the IP addresses. We want them to show them as regular IP addresses. So we add [[field__display]] methods to our delegate class: <code> function start_ip__display($record){ $val = $record->val('start_ip'); if ( $val ) return long2ip($val); return $val; } function end_ip__display($record){ $val = $record->val('end_ip'); if ($val){ return long2ip($val); } return $val; } </code> ==References== * [http://xataface.com/documentation/how-to/how-to-define-custom-serialization-for-fields How to define custom serialization for fields] ip address, pullValue, pushValue, beforeHandleRequest en GettingStarted:Introduction 71 Introduction Web Lite is a simple framework for building data-driven web applications in PHP and MySQL. This section introduces some of the concepts and applications of Dataface. To fully understand what Xataface is, we must first define a few key terms: '''Framework''' - A set of software routines that provide a foundation structure for an application. Frameworks take the tedium out of writing an application from scratch. (From Answers.com) '''Data-driven design'''- Designing an application around the data that it will store. Xataface is a ''Framework'' in the sense that it is a set of classes and libraries that take the tedium out of writing web applications. It provides a simple web interface to a MySQL database enabling users to update, delete, and find data in the underlying database. The interface is targeted at secretaries and end-users as opposed to database administrators. Xataface enables ''data-driven design'' because it allows developers to develop web sites by first designing the database that will be used to store the data on the website, and then design the pages used to display the data. The developer can focus on the data because he or she does not have to worry about having to build forms to update the data. If the requirements of the application change, the developer can simply add a field to the database table and all associated web forms will be updated automatically (because they are all dynamically generated using the database schema). ===Requirements=== * [http://php.net PHP] >= 4.3 * [http://mysql.com MySQL] >= 3.2.3 ===Key Technologies=== * [http://pear.php.net PEAR class libraries] (HTML_QuickForm, etc...) * [http://smarty.net Smarty Templating Engine] * [http://plone.org Plone] Javascript and CSS style sheets ===Development Procedures=== # Identify the data that will need to be stored for a web site. ##[[Image:http://xataface.com/documentation/tutorial/getting_started/er-diagram.png]] # Design the database using your favorite database administration program (e.g., PHPMyAdmin) ##[[Image:http://xataface.com/documentation/tutorial/getting_started/phpMyAdmin-1-small.gif]] # Tell Xataface some DB connection info, and voila! You have an application: ##[[Image:http://xataface.com/documentation/tutorial/getting_started/new-record-form-1-small.gif]] ===Where to go from here=== This tutorial will teach you the basics of Xataface and how to construct a simple application using the Xataface. After reading this tutorial you will be ready to tackle some medium to large web sites with the help of the Xataface reference documentation. You are also encouraged to mail the [http://xataface.com/forum Xataface forum] if you have questions. introduction requirements getting started en GettingStarted:Why_Use_Xataface 72 Why Use Xataface ==Why Use Xataface?== Some simple examples similar to those that are frequently encountered by web developers, and how dataface can be used to acheive a solution. As a web services developer in the Faculty of Applied Sciences at Simon Fraser University, I am frequently getting requests to build websites that are manageable by the site owner. Most of these requests also specify certain types of content that must be stored on the website, and much of this content needs to be n-ary (i.e., there will be multiple instances of each type of content). Let me give you an example. ===Example 1: Website for Faculty of Widgetry=== The Faculty of Widgetry needs a website to publish information about its undergraduate programs. It is important for them to be able to publish admission requirements, and program overviews for each program. It is also important to have course outlines and timetables for each course. The Faculty of Widgetry has 12 undergraduate programs and over 100 courses offered. ====Solution 1: Static HTML==== To build this web site using only static HTML pages using Dreamweaver or some other HTML editor would require at least 112 pages to be created (one for each course and program). However, once we recognize that there are only 2 types of pages required (one for courses and one for programs), we can reduce the task down to creating 2 templates and filling in the main content for each program and course individually. Most HTML editors have some templating ability so you can make changes to the template and have the changes propogated to all pages that use that template with the click of a button. This works great, but courses are added frequently, and outlines are changed. Do you really want to receive requests to update all of these pages every time there are changes to make? (If your answer is 'yes', then you probably won't be interested in reading the rest of this tutorial). Whether the Dean of the faculty knows it or not, it is very important for the program assistants to be able to update these web pages on their own. To acheive these goals you can: * Install Dreamweaver on the Program Assistants' computers, teach them how to use it, and allow them to perform updates. * Install Contribute, which is a scaled down version of Dreamweaver to make it easier for the Program Assistants to edit the content. * Use another solution that is equivalent to one of the above 2 solutions. Installing Dreamweaver for each Program Assistant is a little overkill, and since it has the ability to do much more than just update content. In addition, Dreamweaver is really a developer's tool - not a secretary's tool, so it can be difficult to learn at first. The best reason NOT to install Dreamweaver on the Program Assistant's computer, however, is that it enables him/her to muck things up by accident (believe me, I has happened to me more times than I care to count). Admittedly, Contribute is a viable option as it controls access to only certain portions of web pages to be edited, and it is targetted at secretaries (not developers) so it is easier to use. In fact, given the requirements for this web site (as stated above), this is a perfectly good solution. However you better hope that none of the following requirements are added: * Each program web page should contain an up-to-date list of all of the courses required for the program, along with a link to the course outline for that course. * Course outlines should be available in PDF format as well as HTML format. * An index page showing all of the courses available should be added. This page must allow courses to be organized by program, course subject, or course number. * Any other requirement that would have information formatted in more than one way. If any of these requirements are likely to be added (EVER) then you would be well-advised to look into solutions that use a database back-end. ====Solution 2: Use a Content Management System (CMS)==== There are hundreds of content management systems available that will allow you to store and update content through the web (TTW). Some of them even have an assortment of add-ons that will allow you to store more specific types of information. Some good CMS's include Plone, Drupal, and Xoops. Suppose we want to develop the Faculty of Widgetry website using one of these CMS's. Any good CMS will allow you to create and edit HTML documents easily (without having to write any custom products). However, it is often the case that our documents require the content to be structured. For example, each program has some common data associated with it: Program Name, Admission Deadline, Program Description, Outline, Courses, etc... If we want to properly separate data from presentation, we would need to build a special content-type to store our programs. Most CMS's allow you to develop custom content-types using the underlying programming language and an API (Application Programming Interface). Some API's are easier to use than others and some are documented better than others. The common element is that each has its own proprietary interface for writing these add-ons. If you are using a CMS and you are proficient in the creation of add-on content-types, then you will be able to build the Faculty of Widgetry website without great difficulty. However there are a number of reasons why you may choose NOT to use a CMS: * Steep learning curve: Depending on the CMS it can be very time consuming and difficult to learn how to use and modify the CMS to suit you purposes. * It is over-kill: Most CMS's are filled with features and modules that you will never need. In fact it can even be a pain to turn them off if you don't want them. * You can get tied into the CMS: When you are using a CMS, you will start developing for the CMS. With all of your content in the CMS it may be difficult to migrate to a different solution later on. (The truth of this statement will vary for different CMS's). Choose your CMS carefully. ====Solution 3: Use an existing Application==== OK, OK, let's not get too carried away with trying to develop the website until we have checked the market to see if someone else has already done it better. Maybe there is already a PHP application that makes websites for Faculties easy. I mean, I can't be the first person that needed to build a website for a Faculty. In fact if you do a search or go to Hotscripts.com, you will probably find a handful of applications or scripts that almost do what you need. If you're lucky, maybe you can find an application that does exactly what you need (but frankly, I've never been that lucky). If you find one, maybe it's worth taking it for a test drive. But beware. Using a system that almost does what you need but is difficult to modify to your needs can be worse than building it by scratch. Make sure that you are able to modify the application to suit your needs exactly. ====Solution 4: Use PHP and MySQL==== If all we want to do is separate the data from the presentation and allow the Program Assistants to update data on the website, why not just design a MySQL database with the appropriate tables and fields to store the required data. In our case we will need 2 tables: '''Programs''': * Fields: ** ProgramID : int ** ProgramName : varchar ** ProgramDescription: text ** AdmissionDeadline: date ** Outline_HTML : text ** Outline_PDF : blob '''Courses''': * Fields: ** CourseID : int ** CourseSubject : varchar ** CourseTitle : varchar ** CourseNumber : int ** ProgramID : int ** CourseDescription : text ** Outline_HTML : text ** Outline_PDF : blob Now it's easy to create a few web pages that extract data from the database and displays it as HTML. In fact if there is an existing page template that you can use for the header and footer, you can develop the entire Faculty website in under an hour (you just have to create 3 pages). '''Question''': How will the Program Assistants update the information in the database? '''Answer''': OK, let's assume that you're not going to teach them SQL and that a DB Admin tool will also be too difficult to learn. Then you have to create HTML forms to update records in the database. Ouch! What was easy just became hard. Making HTML forms is a real pain, because you have to validate the input, deal with file uploads, and also make sure that everything is stored to the database OK without losing any information. Such a basic task, but it can be very difficult. This is when it is time to use Xataface. ====Solution 5: Use Xataface==== OK, this isn't really its own solution. It is more like "Solution 4 Part II", because Xataface is intended to complement your custom application you built with solution 4, by providing an easy-to-use, configurable user interface that is targeted at secretaries and normal users (as opposed to database administrators). A Xataface application takes only seconds to set up and it will provide you with a full user interface for your users to edit information in the database. introduction motivation why en 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 GettingStarted:Installation 73 Installation ==Installation== Download and installation instructions for the Web Lite framework. Xataface is a 100% PHP Framework that comes with all dependencies as part of the installation. The framework itself lives inside a single directory that should be placed inside the document root of your web server so that it can be accessed from the web. You can install a single copy of Xataface to be used by multiple applications on your web server. Each application just "requires" the key files from the Web Lite framework. ===Downloading=== # Go to the Xataface Sourceforge project file releases page # Download the latest file release. ===Installing=== # Unpack the gzipped tar archive that you downloaded somewhere in your web server's document root (i.e., make sure that the 'dataface' directory is in a web-accessible location). # Make the dataface/Dataface/templates_c directory writable by the web server. An unsafe way to do this is to chmod 777 Dataface/templates_c But it would be better to just give write access to the web server user. # Confirm that the installation worked by pointing the web browser to http://yourdomain.com/path/to/dataface/dataface_info.php . If it worked OK, you should receive a web page that says "Dataface is installed correctly", along with some basic instructions for creating a Xataface Application. (Note: Sometimes this page will give you a false positive. i.e., it may say the installation worked but then your Xataface application receives errors. Check the troubleshooting section below to deal with these issues). ===Troubleshooting=== If your installation is not going as planned, don't panic. There is a possiblity that your system has a slightly different configuration and you have to make some small adjustments to make the installation work. The general procedure for troubleshooting the installation is as follows: # Check the [[Troubleshooting]] page. # Look through the [http://xataface.com/forum forum] to see if others have experienced the same thing. # Post your question in the forum if you can't find the answer already. installation troubleshooting downloading 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 relationship 68 The relationship fields.ini directive [[fields.ini file|Return to fields.ini file directives]] [[toc]] ===Synopsis=== Certain types of widgets (e.g. grid (v1.0) and checkbox (v1.2)) support the relationship directive which allows them to effectively add/remove records from a specified relationship. This directive only works with transient fields. ===Example 1: Checkboxes to add/remove categories=== (Note: This example requires Xataface 1.2 or higher to work) Suppose we have a database that keeps track of courses and the branch of research that they belong to. A course can be part of multiple branches. We want to be able to select the branches that a particular course belongs to on the edit form for that course using checkboxes. Table Structure: <code> courses: course_id : int (primary key) course_title : varchar branches: branch_id : int (primary key) branch_name : varchar branch_description: text course_branches: course_id : int branch_id : int </code> Relationship definition: (from the tables/courses/[[relationships.ini file]]): <code> [branches] course_branches.course_id="$course_id" course_branches.branch_id=branches.branch_id </code> Field definitions: (from tables/courses/[[fields.ini file]]): <code> [branches] transient=1 relationship=branches widget:type=checkbox </code> Things to notice: # This is a many-to-many relationship (hence the need for the course_branches join table. # The [branches] field is a transient field. # The relationship directive from the [[fields.ini file]] references our branches relationship that was defined in the [[relationships.ini file]]. # You can call the field anything that you like. There is no need for it to have the same name as the relationship. It just turned out that way in this example. ===Example 2: Using a grid widget=== Let's modify example 1 slightly to use a grid widget instead of checkboxes. The grid widget will allow us edit the records in a relationship using dynamic table. It automatically uses the correct widget for each column of the table according to the definition in the target table's [[fields.ini file]]. Most of the definition can remain the same. We only change the [[fields.ini file]] directive: <code> [branches] transient=1 relationship=branches widget:type=grid widget:columns="branch_name,branch_description" </code> In this case we are able to edit the branch name and description in each row of the grid. ===See Also=== * [[grid|The grid widget]] * [[checkbox|The checkbox widget]] * [[relationships.ini file|The relationships.ini file]] * [[fields.ini file|The fields.ini file]] grid widget, relationship, checkbox en 0 Grafted_fields 158 Grafted fields ==Grafted Fields== ===Introduction=== When there are numerous tables, it is difficult for the user to see get an information that will help one to enter the right data in the right field. So instead of navigating in the relative tables and lose some time, it is more convenient to add a grafted field from that relative table in the table. To be able to sort a column by the content displayed when this content is extracted form a relative table, a grafted field is necessary because the real content is just an id, not the most convenient to sort in human-readable way. ===Procedure=== Two ways to add a grafted filed * The first one is to add a __sql__ statement at the beginning of fields.ini, including the grafted field through a join. <code>__sql__ = "select p.*, d.total from programmation p left join dev d on p.id_programmation=d.id_programmation" </code> * The second one is to create the function __sql__ in the delegate class <code>function __sql__(){ return "select p.*, d.total from programmation p left join dev d on p.id_programmation=d.id_programmation"; } </code> ===Sorting order based on relationship=== The solution is to hide the field with the id and to add the grafted field with the name in the fields.ini <code>[name_programmation] order=10 [id_programmation] visibility:list=hidden </code> ===Debugging=== A couple of things to check for: *1. If you have set blanket default permissions for your fields using the __field__permissions() method you could be disallowing access to the field. *2. If you have set default field visibility in the fields.ini file via the [__global__] section.... *3. Check to make sure that your __sql__ directive is at the beginning of the file and that it is __sql__ and not _sql_ *4. Try to enter an obviously invalid SQL query for the __sql__ directive to see if you get an error (to confirm that it is picking up the __sql__ directive at all). grafted fields, grafted, sorting columns, sort, relative records, relative tables en getNavItem 125 getNavItem Application Delegate Class Method Return to [[Application Delegate Class]] [[toc]] ===Synopsis=== The getNavItem() method of the application delegate class can be used to override the items that appear in the navigation menu (i.e. the menu that allows users to select the table via either tabs along the top or items along the side). It should return an associative array with characteristics of the navigation item including the href (i.e. link), label, and selected status. Using this method it is now possible to have non-table navigation items as well. You would just add these items to the \[_tables\] section of the [[conf.ini file]] then override the item using this method. '''Since 1.3''' ====How the Nav Menu Is Built==== Xataface builds the navigation menu by looping through each item in the [_tables] section of the conf.ini file, passing it to the getNavItem() method, and adding the resulting navigation item to the menu. If getNavItem() returns null, then that item will be skipped. If getNavItem throws an exception, then the default rendering for the menu item will take place. ===Signature=== <code> function mixed getNavItem( string $key, string $label ) throws Exception </code> ===Parameters=== * '''$key''' - The key of the nav item. In the case of a table, this would be the table name. * '''$label''' - The label of the nav item (may be overridden). ===Returns=== This method should return either: # An associative array with the properties of the nav item. # null to indicate that this nav item should be omitted altogether. (e.g. if the user shouldn't have permission for it). If returning an associative array, it should contain the following keys: * '''href''' - (String) The URL where this nav item should point. * '''label''' - (String) The label of this nav item. * '''selected''' - (Boolean) True if the nav item is currently selected. False otherwise. ===Throws=== If you want to signal Xataface to just use default rendering for the current navigation item you can just throw an exception. The default rendering will link to the table named ''$key'', and the item's label will be the same as ''$label''. ==Examples== Given the following conf.ini file: <code> ... [_tables] people=People books=Books accounts=Accounts reports=Reports ... </code> Suppose we want the navigation menu to only show the ''people'' and ''books'' options for regular users. Admin users can see all options. In addition, the 'reports' option doesn't correspond with a table of the database. Instead we are just going to link it to a custom action named 'reports'. Our getNavItem() method will look something like this: <code> function getNavItem($key, $label){ if (!isAdmin() ){ switch ($key){ case 'people': case 'books': // non-admin users can see these throw new Exception("Use default rendering"); } // Non-admin users can't see any other table. return null; } else { //Admin users can see everything.. $query =& Dataface_Application::getInstance()->getQuery(); switch ($key){ case 'reports': // reports is not a table so we need to return custom properties. return array( 'href' => DATAFACE_SITE_HREF.'?-action=reports', 'label' => $label, 'selected' => ($query['-action'] == 'reports') ); } // For other actions we need to make sure that they aren't selected // if the current action is reports because we want the 'reports' // tab to be selected only in that case. return array( 'selected' => ($query['-table'] == $key and $query['-action'] != 'reports') ); } } </code> ===See Also=== * [[isNavItemSelected]] - Overrides default behavior of whether a navigation item is currently selected. getNavItem, navigation menu en getChildren 126 getChildren Delegate Class Method Return to [[Delegate class methods]] [[toc]] The getChildren() method can be implemented in a table's delegate class to specify the logical "child" records of a given record which can be used when creating hierarchical applications. This method will effectively override the output of the Dataface_Record::getChildren() method for records of this table. ===Signature=== <code> function getChildren( Dataface_Record $record) : Dataface_Record[] </code> ===Parameters=== # '''$record''' - The Dataface_Record that is the subject of the query ===Returns=== This method should return an array of Dataface_Record objects that are considered to be children of the subject record. ===Examples=== <code> function getChildren($record){ return df_get_records('webpages', array( 'parent_id'=>'='.$record->val('webpage_id') ) ); } </code> ==See Also== * '''[[getParent]]''' - A Delegate class method to return the logical parent of a given record. getChildren Delegate class method en GettingStarted:validation 79 Form Validation ==Form Validation== Xataface allows you to add validation rules to fields using the fields.ini file A common requirement for forms is to have some validation rules. Here are some example validation rules: * The Username field is required. * The Username must be between 6 and 16 characters long. * The password must have at least one letter and one digit. * The Email field must contain a valid email address. There is no end to the types of things that you will need to validate. Xataface takes care of most of this for you with both client-side (javascript) and server-side validation. All you have to do is define some validation rules in the fields.ini file. ===Example 1: Make 'Username' a required field=== <code> [Username] validators:required = true validators:required:message = "Username is required" </code> Placing the above inside the fields.ini file will cause the Username field to be a required field. ===Example 2: Username must be between 6 and 16 characters long=== For this rule we will use a regular expression. <code> [Username] validators:regex = "/^.{6,16}$/" validators:regex:message = "Username must be between 6 and 16 characters long" </code> ===Example 3: Email field must contain a valid email address=== <code> [Email] validators:email = true validators:regex:message = "Email must contain a valid email address" </code> ===Available validation rules=== Xataface uses the PEAR library HTML_Quickform for validation, so any of the validators available in this package will be available in Xataface. Some of the available validation rules include: * required * maxlength * rangelength * regex * email * emailorblank * lettersonly * alphanumeric * numeric * nopunctuation * nonzero ===Default validation rules=== There are certain validation rules that are automatically applied to fields of with certain characteristics. For example, any field designated NOT NULL in the SQL table definition will automatically be a 'required' field. At the time of this writing, that is the only 'default' validation rule applied, but more may be added in the future if their addition makes sense. form validation,required field,validation rules en getPasswordChangedEmailInfo 121 getPasswordChangedEmailInfo Application Delegate Class Method Return to [[Application Delegate Class]] [[toc]] ===Synopsis=== Optional method to define the settings for the email that is sent to the user upon successful resetting of their password using the password reset function. Introduced in Xataface 1.3. Exists in 1.3 or higher. ===Signature=== <code> function getPasswordChangedEmailInfo(Dataface_Record $user, string $password){} </code> ===Parameters=== * '''$user''' - The Dataface_Record of the user whose password has been changed. * '''$password''' - The new temporary password that has been assigned to the user. ===Returns=== This method should return an associative array with 0 or more of the following keys: * '''subject''' - The subject line of the email. * '''message''' - The message content of the email. * '''headers''' - The Email headers (as a string). * '''parameters''' - Extra parameters for the mail function. ==See Also== * [[getResetPasswordEmailInfo]] - A delegate class method to define the email that is sent to the user when they request a password reset. This is the step that immediately precedes the Password Changed email step. forgot password, reset password en getResetPasswordEmailInfo 122 getResetPasswordEmailInfo Application Delegate Class Method Return to [[Application Delegate Class]] [[toc]] ===Synopsis=== Optional method to define the settings for the email that is sent to the user when they request to reset their password. Introduced in Xataface 1.3. Exists in 1.3 or higher. ===Signature=== <code> function getResetPasswordEmailInfo(Dataface_Record $user, string $reset_url){} </code> ===Parameters=== * '''$user''' - The Dataface_Record of the user whose password has been changed. * '''$reset_url''' - The URL where the user should go to reset their password. When they visit this URL they will receive a message saying that their password has been changed and the new password has been emailed to them. That subsequent email can be customized using the [[getPasswordChangedEmailInfo]] method. ===Returns=== This method should return an associative array with 0 or more of the following keys: * '''subject''' - The subject line of the email. * '''message''' - The message content of the email. * '''headers''' - The Email headers (as a string). * '''parameters''' - Extra parameters for the mail function. ==See Also== * [[getPasswordChangedEmailInfo]] - A delegate class method to define the email that is sent to the user once their password has been reset to a temporary password. It informs the user of their new temporary password and should include instructions on how to change their password to their own choice. This step immediately follows the reset password step. forgot password, reset password en fields.ini_file 3 fields.ini_file ==fields.ini File Reference== [[toc]] ===Overview=== The fields.ini file is a configuration file which is associated with a single table of a database application. It provides metadata about the table's fields to help Xataface dictate how they should be included in the application. This includes metadata such as * [[widget:type|Widget type]] - To specify the type of widget that should be used to edit content in the field (e.g. text, select, checkbox). * [[widget:label|Label]] - The labels that can be used in column headers and on forms. * [[widget:description|Help text]] - for forms to inform the user how data should be entered. * [[group|Field Groupings]] * [[widget:atts|widget:atts]] - To use javascripts in event handlers * and more Although a table doesn't need to have an associated fields.ini file in order for the application to work, each table can have one; and it is always located in the [[table configuration directory]]. For example, the fields.ini file for the [[people]] table would be located at [[Site Root]]/tables/people/fields.ini file. ===Syntax=== The fields.ini file uses [[standard INI syntax]] (just like the php.ini file), where each section corresponds to a column in the table. For example, consider a table "people" with columns "first_name", "last_name", and "age". The fields.ini file for the people table could then contain sections for each of its columns as follows: <code> [first_name] [last_name] [age] </code> In this example the sections are empty (i.e. they have no directives, but we could easily add some directives: <code> [first_name] widget:description="Please enter your first name" widget:label="Given Name" ...etc... </code> Here we have told Xataface that the first name field should include some help text (using the [[widget:description]] directive) on its edit form. ===Example fields.ini file=== <code> ;; Global directives applied to every field (requires Xataface 1.2.6) [__global__] visibility:list=hidden [isbn] widget:label = ISBN visibility:list=visible [copyright_year] widget:label = "Year" widget:atts:size=4 visibility:list=visible [categories] widget:type=checkbox vocabulary = book_categories [media] widget:type=checkbox vocabulary = book_media [borrower_id] widget:type=select vocabulary=users [due_date] widget:description = "The date that the book is due to be returned to the library" visibility:list=visible [cover_art_url_small] visibility:browse=hidden [cover_art_url_medium] ;visibility:browse=hidden [cover_art_url_large] visibility:browse=hidden visibility:find=hidden [amazon_description] widget:label = Description [amazon_reviews] [amazon_url] [amazon_refresh_timestamp] widget:type=static [date_created] timestamp=insert widget:type = static [date_modified] timestamp=update widget:type=static [created_by] widget:type=static [modified_by] widget:type=static [notes] </code> This is an example from the [http://apps.weblite.ca/index.php?-action=view&-table=packages&package_id=%3D2 Library DB] application for the books table. ===Field Directives=== The following directives may be added to a field's section of the fields.ini file to customize the field's behavior. Some directives are not applicable to all fields. {| class="listing listing2" |- ! Name ! Description ! Version |- | [[column:label]] | Specifies a custom label to use in list view for the column. If this is not specified, then the value of [[widget:label]] will be used. | 1.3 |- | [[column:legend]] | Adds a small amount of help text to the column header for this field in list view. Default is blank. E.g. <nowiki><br/><img src="http://media.weblite.ca/files/photos/Screen%20shot%202011-02-08%20at%205.05.55%20PM.png?max_width=640"/><br/></nowiki>In this photo it shows the text "*Paper Uploaded" set as the [[column:legend]] for "field 1". | 1.3 |- | [[date_format]] | Specifies how the field should be formatted when displayed. Takes same parameters as PHP [http://php.net/strftime strftime] function. | 2.0 |- | [[display]] | Specifies the layout of the field on the edit form. Most fields have an implicit value of "inline" meaning the widget and its label appear on the same line. Textareas and htmlareas have an implicit value of "block" meaning that the label and widget appear in separate rows (label above the widget). You can set this value explicitly also to override the layout of a field. | 0.8 |- | [[display_format]] | A pattern that can be used to define the display format of the field. This takes the same parameters as the PHP [http://php.net/sprintf sprintf] function. | 2.0 |- | [[encryption]] | Primarily used with password fields, indicates the type of encryption that should be used to save the field. Supports "md5", "sha1", "encrypt", and "password". | 0.6 |- | event.date | For use by the [[Calendar Action]]. Indicates that the field stores the date of the record when interpreted as an event. Possible values "0" or "1". | 1.0 |- | event.start | For use by the [[Calendar Action]]. Indicates that the field stores the start time of the record when interpreted as an event. Possible values "0" or "1". | 1.0 |- | event.end | For use by the [[Calendar Action]]. Indicates that the field stores the end time of the record when interpreted as an event. Possible values "0" or "1". | 1.0 |- | event.location | For use by the [[Calendar Action]]. Indicates that the field stores the location of a record when interpreted as an event. Possible values "0" or "1". | 1.0 |- | [[filter]] | Boolean value (0 or 1) indicating whether this field should be [[filterable]] in [[list view]]. | 0.8 |- | [[frozen_description]] | The field description shown when the widget is frozen (i.e. uneditable). If this is not specified, no field description is shown in this case. | 1.2 |- | [[group]] | The name of the field group that this field belongs to. Fields with the same "group" value will be rendered in the same field group on the form. | 0.5 |- | [[Key]] | If you are using a View for the table you need to explicitly mark the fields that comprise the primary key. E.g. Key=PRI | 0.6 |- | [[label_link]] | An optional URL for the field label to link to. This would usually be some "help" page that explains what the field is for. The link will be a link in both the view and edit tabs. | 1.1.3 |- | [[ignore]] | Boolean value (0 or 1) indicating whether this field should be ignored on the edit form. This is handy if the field is going to be constantly updated in the background (via a cron job perhaps) and you don't want the edit form to interfere. | 1.0 |- | [[logo]] | Boolean value (0 or 1) to indicate if this field should be treated as a logo field. Logo fields are displayed in the upper left of the [[view tab]] for a record, and are assumed to contain an image. If no logo field is explicitly specified, Xataface will make a best guess as to which field should be used. | 0.7 |- | [[money_format]] | For fields containing monetary amounts, this specifies the format. Takes same parameters as PHP [http://php.net/money_format money_format] function. | 2.0 |- | [[noLinkFromListView]] | Boolean value (0 or 1) to indicate if this field should be linked when in list view (or in a related list). Default value is 0 to indicate that the field IS linked. It is common to use this directive when using a custom xxx__renderCell() method that contains its own links. | 1.1 |- | [[not_findable]] | A flag to indicate that this field can not be used as part of a query. This is helpful if you want a field to remain completely confidential to prevent people from finding records based on the value of this field. This flag is even necessary if the permissions for the field don't permit viewing the value of the field. | 1.1 |- | [[number_format]] | For numeric fields, this indicates the number of decimal places to display when displaying this field. E.g. 2 | 2.0 |- | [[order]] | The order of the field when laid out on forms and lists. Can contain any floating point number or integer (e.g. 0, 10, -10, 235.4) | 0.6 |- | [[relationship]] | Used only with complex fields that involve editing related records (e.g. [[grid]]). This is the name of the relationship that the field should be edited. | 0.8 |- | [[repeat]] | Boolean value (0 or 1) used in conjunction with a select widget to indicate whether to enable a multi-select. | ? |- | [[section]] | The name of the section that this field should belong to in the [[view tab]]. | 0.7 |- | [[secure]] | A boolean flag for use with [[container fields]] to indicate that it should use secure URLs for the file downloads (i.e. it will obey the application permissions). Without this directives, uploaded files are served directly by apache and don't obey the Xataface permissions defined per record. | 1.3 |- | [[struct]] | A boolean (0 or 1) value indicating whether this field is considered a structure. A value of 1 indicates that this field is a structure and should not be truncated under any circumstances. Normally fields are truncated at 255 chars in list view. This is useful if the field contains XML or other structured data so that attempts to truncate it would destroy integrity. | 1.1.2 |- | [[tab]] | If tabbed forms are enabled, then this specifies the name of the tab that this field belongs to on the edit form. | 0.8 |- | [[timestamp]] | Indicates when a timestamp should be set in the field (only applicable for date and time fields). Possible values are "insert" and "update" | 0.7 |} {| class="listing listing2" |- ! Name ! Description ! Version |- | [[title]] | Boolean value (0 or 1) indicating whether this field should be treated as a title field. | 0.7 |- | [[transient]] | Boolean value (0 or 1) indicating whether this field is a transient field or not. A transient field is a field that is defined in the fields.ini file but not in the database. Hence the values that are input into this field on the edit form are not saved to the database. | 0.8 |- | [[Type]] | The data type of the field (note the capital "T" as Xataface is case sensitive). This value is only overridden for [[container]] fields, however its value can be accessed programmatically for any field. | 0.5 |- | [[validators|validators:VALIDATOR_NAME]] | A prefix for a validation type on the current field. (Replace "VALIDATOR_NAME" with the name of the validator to be used. e.g. required). There are many validators available to be used. | 0.5 |- | [[validators:VALIDATOR_NAME:message]] | The message the should be displayed if the form fails to validator due to the "VALIDATION_NAME" validation rule. | 0.5 |- | [[viewgroup]] | The name of the field grouping that this field will belong to in the view tab. If this is not present, then it will be grouped according to the [[group]] directive. | 1.0 |- | [[visibility:browse]] | Indicates whether the field should be visible in browse mode (i.e. in the "view" tab). Possible values are "visible" and "hidden". | 0.6 |- | [[visibility:csv]] | Indicates whether the field should be included in CSV exports. Possible values are "visible" and "hidden". (1.0 beta 4) | 1.0b4 |- | [[visibility:find]] | Indicates whether the field should be visible in find mode. Possible values are "visible" and "hidden" | 1.0 |- | [[visibility:list]] | Indicates whether the field should be visible in list view. Possible values are "visible" and "hidden". | 0.6 |- | [[visibility:update]] | Indicates whether the field should be included in update and copy/replace forms. Possible values are "visible" and "hidden". | 1.3 |- | [[vocabulary]] | The [[valuelist]] that should be used as the options to select. This is only applicable for fields that have options to select like a select list or a checkbox group. | 0.5 |- | [[widget:atts]] | A namespace for attributes that should be added to the HTML widget. This allows you to specify things like javascript events, styles, widget size, etc.. | 0.5 |- | [[widget:columns]] | For checkbox groups, this specifies the number of columns to use for laying out the checkboxes. | 1.0 |- | [[widget:description]] | Help text to give the user a hint about how to edit the field's content. | 0.1 |- | [[widget:editor]] | The type of HTML editor that should be used. This is used only when [[widget:type]] is set to [[widget:type htmlarea|htmlarea]] Acceptable values include: * [http://www.fckeditor.net/ fckeditor] (default) * [http://tinymce.moxiecode.com/ tinymce] (version 0.6 or higher) * [http://www.nicedit.com/ nicedit] (version 1.0 or higher) | all |- | [[widget:editvalues]] | Used with select lists to allow users to add values to the select list. E.g. widget:editvalues=1 | 0.8 |- | widget:focus | Sets default focus. 0 or 1. (Javascript focus in a form) | 0.6 |- | [[widget:label]] | The label that should be used for the current field on edit forms, column headings, and other relevant locations. | 0.1 |- | [[widget:question]] | Text displayed just before the widget. This is almost the same as [[widget:description]] except that this text is guaranteed to be displayed before the widget, whereas [[widget:description]] may be displayed below or beside the widget. | 0.1 |- | [[widget:type]] | The type of widget that should be used (e.g. checkbox, select, text, etc..) | 0.1 |- | [[xml]] | A flag for use with calculated fields (i.e. fields defined in the [[delegate class]] via the [[field__fieldname]] method) that will include the field in XML output produced by the [[export xml action]]. Default is 0, but setting this value to 1 wil cause the field to be included. | 1.2.7 |} ===Applying Directives to All fields (__global__)=== Xataface 1.2.6 includes support for a [[__global__]] section that allows you to specify directives that should be applied to all fields. These directives can be overridden on a field by field basis. The [[__global__]] section can take all the same directives that a normal field section takes. ===widget:atts:class Values=== The widget:atts:class directive allows you to assign a CSS class to a field's widget. There are certain CSS classes that have meaning to Xataface and will cause additional functionality to automatically be added to the field. These built-in classes are listed below: {| class="listing listing2" |- ! Name ! Description ! Version |- | [[passwordTwice]] | Applicable only to password fields. If you set widget:atts:class=passwordTwice, then this will convert the password field into two fields whereby both fields need to match in order for submission to continue on the edit form. This operates as a password verification field." | 1.3rc2 |} ===Global Directives=== The following directives can be added to the beginning of the fields.ini file (before any field sections) to customize field groups and the table as a whole. {| class="listing listing2" |- ! Name ! Description ! Version |- | [[__dependencies__]] | A comma-delimited list of tables that this table is dependent upon for caching purposes. E.g. if any table in this list is modified, then the query cache is cleared for queries on this table. See this [http://xataface.blogspot.com/2009/06/using-query-caching-in-xataface.html blog article] for more information about query caching. | 1.2 |- | [[__isa__]] | The name of the parent table of the current table. This directive allows you to have a heirarchical structure amongst the tables in your application. | 0.8 |- | [[__source_tables__]] | A comma-delimited list of tables that this table/view is derived from. This is used with the query caching feature and is necessary to use this directive if the table is actually a view. If this directive is not set, then any queries involving this view will not use the query cache because Xataface would have no way to discern the update time of the view. See this [http://xataface.blogspot.com/2009/06/using-query-caching-in-xataface.html blog article] for more information about query caching. | 1.2 |- | [[__sql__]] | Defines a custom select query to override the default select query for the current table. (The default select query is generally "select * from tablename"). | 0.7 |- | [[__prefs__]] | Sets preferences for this table and its records. | 1.0b4 |} ===Field Groups=== The [[group]] directive allows you to group multiple fields together so that they will be rendered in the same field group on forms. You can also configure these groups as a whole by defining a section named "[fieldgroup:GROUPNAME]" (where GROUPNAME is the name of the field group, corresponding to the [[group]] directive values for the fields) in the fields.ini file. This section provides a few basic directives to customize some aspects of the field group: * label * order * description * template * more... The most common use of these sections is to customize the label or order of groups, especially when there are multiple field groups in the table. For example, suppose we have a table "people" with fields "first_name", "last_name", "phone", "fax", "email", "address", "city", and "country". Suppose these fields are grouped as follows: * "first_name" and "last_name" * "phone", "fax", and "email" * "address", "city", and "country" so that the fields.ini file looks like: <code> [first_name] group=name [last_name] group=last_name [phone] group=contact [fax] group=contact [email] group=contact [address] group=address [city] group=address [country] group=address </code> By default, the "name" group will appear first in the form, followed by "contact" and "address". If we want to place "address" first we could add the following section to our fields.ini file: <code> [fieldgroup:address] order=-1 </code> Since the default order value is 0 on other groups, setting the "order" parameter to -1 will place the "address" group before all others. ====Field Group Directives==== The following directives are applicable in a fieldgroup section: {| class="listing listing2" |- ! name ! description ! version |- | [[fieldgroup order|order]] | Specifies the order of the group with respect to other groups on the form. Accepts any numerical value (e.g. 0, 1, -1, 25.43), with lower values appearing first. Default value is 0. | 0.6 |- | [[fieldgroup label|label]] | Specifies the label that should be used for the field group. | 0.6 |- | [[label_link]] | Specifies a URL that the field group label should link to. | 1.1.3 |- | [[fieldgroup template|template]] | The path to a custom template that should be used to render the fields of the field group. | 1.0 |- | [[fieldgroup collapsed|collapsed]] | Boolean value (0 or 1) indicating whether the field group should be collapsed by default (user can expand it). | 1.0 |} fields.ini directives en 0 examples 34 examples ==Xataface Examples== [[toc]] This section includes concrete examples of how Xataface has been used in the past. ===Demo Applications=== {| class="listing listing2" |- ! Screenshot ! Title/Description ! Developed by |- | [[Image:http://images.websnapr.com/?size=150&key=40f0knTakb1b&url=http://demo.weblite.ca/apps/librariandb/]] | '''Librarian DB''' A searchable database of library books. Useful for small libraries (e.g. Church Libraries). Log in with: username: admin password: password [http://demo.weblite.ca/apps/librariandb/ Try the app] | [http://solutions.weblite.ca Web Lite Solutions Corp.] |- | [[Image:http://images.websnapr.com/?size=150&key=40f0knTakb1b&url=http://demo.weblite.ca/apps/webauction/]] | '''Web Auction''' A simple web-based auction application for organizations to hold auctions. Login with: username: admin password: password [http://demo.weblite.ca/apps/webauction/ Try the app] | [http://solutions.weblite.ca Web Lite Solutions Corp.] |} ===Websites Powered by Xataface=== {| class="listing listing2" |- ! Screenshot ! Title/Description ! Developed by |- | [[Image:http://images.websnapr.com/?size=150&key=40f0knTakb1b&url=http://fueleconomydb.com]] | '''Fuel Economy Database''' - A searchable database of gas mileage and fuel economy statistics for automobiles from 1986 to present. [http://fueleconomydb.com Visit the site] | [http://solutions.weblite.ca Web Lite Solutions Corp.] |- | [[Image:http://images.websnapr.com/?size=150&key=40f0knTakb1b&url=http://physics.sfu.ca]] | '''Department of Physics, Simon Fraser University''' This website is completely powered by Xataface. It is backed by a MySQL database that stores faculty members, research groups, news, events, and more. Faculty members are able to update their personal profiles and research profiles through a Xataface administration console. [http://physics.sfu.ca Visit the site] | [http://fas.sfu.ca/ SFU Faculty of Applied Sciences] |- | [[Image:http://images.websnapr.com/?size=150&key=40f0knTakb1b&url=http://science.ca]] | '''Science.ca''' The source for science in Canada. Includes profiles for prominent scientists as well as other useful science-related information. Xataface is used to power the bilingual (English/French) capabilities of this site. It includes web-based administrative console for the administrator to manage all content, and for translators to translate the content. [http://science.ca Visit the site] | Science.ca web team |- | [[Image:http://images.websnapr.com/?size=150&key=40f0knTakb1b&url=http://translation.weblite.ca]] | '''Simple Website Translation Engine''' A service that allows website owners to easily convert their website into multiple languages. Support human and machine translation. This service is powered by Xataface, and provides an administrative console for users to manage their website translations. [http://translation.weblite.ca Visit the Site] [http://swete.weblite.ca More about this service] | [http://translation.weblite.ca Web Lite Translation Corp.] |- | [[Image:http://images.websnapr.com/?size=150&key=40f0knTakb1b&url=http://www.credituniondb.com]] | '''Credit Union Database''' A database of credit unions in the United States. This site is powered by Xataface. [http://www.credituniondb.com Visit the site] | Vlad |- | [[Image:http://images.websnapr.com/?size=150&key=40f0knTakb1b&url=http://ierg.net/lessonplans/unit_plans.php]] | '''IERG Lesson Plans Database''' A searchable database of lesson plans created by the Imaginative Education Research Group. This database is managed by Xataface. It provides researchers with a web-based control panel to manage their lesson plans. [http://ierg.net/lessonplans/unit_plans.php Visit the site] | [http://solutions.weblite.ca Web Lite Solutions Corp.] |- | [[Image:http://images.websnapr.com/?size=150&key=40f0knTakb1b&url=http://ierg.net/people/]] | '''IERG People Database''' A simple database to manage the contributors and associates of the Imaginative Education Research Group. Administrators have a web-based control panel to manage the people profiles in this database. [http://ierg.net/people/ Visit the site] | [http://solutions.weblite.ca Web Lite Solutions Corp.] |- | [[Image:http://images.websnapr.com/?size=150&key=40f0knTakb1b&url=http://sustain-gradnetwork.envr.sfu.ca/]] | '''Sustainability Research Database''' A database at Simon Fraser University for grad students to post and share research profiles. [http://sustain-gradnetwork.envr.sfu.ca/ Visit the site] | [http://fas.sfu.ca Faculty of Applied Sciences Web Team] |- | [[Image:http://images.websnapr.com/?size=150&key=40f0knTakb1b&url=http://apps.weblite.ca/]] | '''Web Lite Applications Catalog''' A catalog of applications available through Web Lite Solutions. Allows users to set up their own online applications on Web Lite's servers. This site is completely powered by Xataface. [http://apps.weblite.ca/ Visit the site] | [http://solutions.weblite.ca Web Lite Solutions Corp.] |} examples, samples en 0 Email 54 Email ==Xataface Email Module== [[toc]] The Xataface Email module allows you to convert your database into a mailing list so that you can easily send email to any found set of records, as long as the records contain an email address to send to. ==Features== * Send email to any found set. * Mail merge macros * HTML Email support (uses NicEdit WYSIWYG editor for email editing). * Opt out support (allows recipients to opt out of your mailing list). ==Requirements== * Xataface 1.0+ * MySQL 4.1+ * PHP 5+ ==Download== https://sourceforge.net/project/platformdownload.php?group_id=253820 ==Installation== # Download and extract Email directory so that it is located inside the xataface/modules directory (i.e. xataface/modules/Email) # Add the following to the ''[_modules]'' section of your application's conf.ini file:<code> modules_Email="modules/Email/Email.php" </code> # Configure the [email] action in your application's actions.ini file. See the section called 'Configuration' for configuration details. # Add a line to your crontab file to send out pending email periodically. The line should look like:<code> * * * * * /usr/bin/php <cronpath> <indexpath> <indexurl> mail where <cronpath> is the absolute path to the cron.php script. <indexpath> is the absolute path to your application's index.php script. <indexurl> is the absolute url to your application's index.php script. For example: * * * * * /usr/bin/php /var/www/xataface/modules/Email/cron.php \ /var/www/myapp/index.php \ http://example.com/myapp/index.php \ mail </code> If you want to see what this line should be like for your server, you can simply point your browser to the email_install action of your application (i.e. http://example.com/yourapp/index.php?-action=email_install) and it will generate this line to copy and paste into your crontab. Note that the /usr/bin/php portion of this line may vary according to your environment. It represents the path to your PHP binary. # That's it! You're ready to send email. See the ''Usage'' section to see how to send email from your application. ==Configuration== Though the email action may work out of the box, you will likely have to configure it to work the way you want. Some examples of things you will want to configure include: # Limit the email action to only be available for certain tables. # Apply permissions to the action so that only administrators can send email. # Set the name of the column that contains email address (default is 'email'). # Change the name of the table that is used to store sent email messages. ===Overriding the ''[email]'' action=== The first thing you need to do to configure the email action is override it in your appliation's actions.ini file. You can do this by adding the following to your [[actions.ini file]]: <code> [email > email] </code> Now any directives you add in this section will override the email action. ====Examples:==== =====Limiting email action to certain tables===== In your appliation's [[actions.ini file]]: <code> [email > email] condition="$query['-table'] == 'Pledge' or $query['-table'] == 'User'" </code> =====Limiting email action by permission===== By default your users require the ''email'' permission in order to have access to the email form. This permission is not included with any roles by default so you'll need to extend any roles that you want to have access to the email access and explicitly add the ''email'' permission. The exception to this rule is if you have assigned your users the ''Dataface_PermissionsTool::ALL()'' permissions in your ''getPermissions()'' method. Suppose you want the ''READ ONLY'' role to have access to the email action, you could add the following to your application's [[permissions.ini file]]: <code> [READ ONLY extends READ ONLY] email=1 </code> =====Changing the name of the email address column===== By default, the Email module will try to guess which column contains the email address for a table. Generally it looks for a column named ''email''. You can override this setting to explicitly tell the module which column contains the email address by overriding the ''email_column'' directive of the ''email'' action in your application's [[actions.ini file]]: <code> [email > email] email_column = "emailAddress" </code> =====Changing the name of the table that stores the sent email==== Xataface automatically stores each sent email for your records. By default it stores these emails in a table named ''newsletters''. You can override this table name with the ''email_table'' directive in your application's [[actions.ini file]]. This table will be automatically created by Xataface when email is sent out. <code> [email > email] email_table = "newsletters" </code> =====Altogether===== <code> [email > email] condition="$query['-table'] == 'Pledge' or $query['-table'] == 'User'" permission=email email_column = "emailAddress" email_table = "newsletters" </code> ==Usage:== ===Sending Email to All Records of a Table=== # Navigate to a table for which your email module is enabled, and click on the ''list'' tab. # Click on the "Email" icon in the upper right corner. This should display an email form.<nowiki> <img src="http://media.weblite.ca/files/photos/email_icons.png"/> </nowiki> # Fill in the email form and press Save.<nowiki> <div><img src="http://media.weblite.ca/files/photos/email_form.png?max_width=500"/></div> </nowiki> # You should receive a message saying that the email has been queued for delivery. Your cron script will automatically begin sending emails the next time around. So make sure that you have yoru cron script set up properly. ===Opting Out of the Email List=== If you have received an email that was sent via the email module you can easily opt out of the mailing list by clicking on the link at the end of the email. This link will bring you to a webpage that asks you to confirm that you no longer wish to receive email from this list. ==Using a View to add Email Action to Related Record List== You can simulate a many-to-many [[relationships.ini file|relationship]] in a mysql view by creating a view with all possible combinations. e.g. If you have a Many to Many [[relationships.ini file|relationship]] between books and authors your [[relationships.ini file|relationship]] from the books table might be something like: <code> [authors] __sql__ = "select * from authors a inner join book_authors ab on a.author_id=ab.author_id where ab.book_id='$book_id'" </code> And your relationship from the authors table would be something like: <code> [books] __sql__ = "select * from books b inner join book_authors ab on b.book_id=ab.book_id where ab.author_id='$author_id'" </code> Now if our goal was to be able to send email to all authors of a particular book (i.e. send to the authors relationship), we could create a view: <code> create view book_authors_maillist as select * from authors a inner join book_authors ab on a.author_id=ab.author_id </code> This view can now be used in xataface like a regular table (if you add a [[fields.ini file]] for it and [[Key|mark the primary key columns]]). If you wanted to find all authors for a certain book you would just do: index.php?-action=list&-table=book_authors_maillist&book_id=10 So you could easily create an action in the [[actions.ini file]] that would like to the mail action on the book_authors_maillist table with the parameters you wanted. e.g. <code> [related_authors_mail] category=related_list_actions url="{$site_href}?-action=email&-table=book_authors_maillist&book_id={$record->val('book_id')}" icon="{$dataface_url}/images/mail_icon.gif" url_condition="$record" condition="$query['-table']=='books' and $query['-relationship'] == 'authors'" permission="email" </code> This action would send mail to only the authors related to the current books. It would be made available in the icons in the upper right on the related list view of only the authors of a book. ===Mail Merge=== The 'Embed Macro' shown above the email form lists the fields which may be included in the email. Say you have a field called 'email_firstname'. You would type this into the message area like this: %email_firstname% When the email is sent, this is substituted for the record of that recipient. Eg. Dear %email_firstname% would be received by email as Dear Tom If the particular record of the field you are merging is blank, then (in this case) the first name will not be shown. Email,Email module,Sending Email,Maillist en 0 documentation_guide 70 Documentation Guide Xataface uses a wiki to manage its online documentation which can be edited by anyone. All you have to do is [http://xataface.com/wiki/index.php?-action=login login with your forum username and password] ([http://xataface.com/forum/profile.php?mode=register register for the forum here]). Then when you are browsing a page of the wiki, you'll see an 'Edit' tab along the top. Click on this tab to start editing the page in your browser. Wiki markup is a little simpler than HTML and a little more complex than plain text. It is easy to get a handle on once you get started. If you aren't sure how to format it exactly how you want, don't worry. Someone may come by after you and improve on your formatting. That's what the community approach is all about. ==The Documentation Team== Join the Xataface documentation team to help participate in the planning of the documentation. If you want to help out, contact [mailto:steve@weblite.ca Steve Hannah] and he'll add you to the documentation group where you can access the private documentation forums and meet the rest of the team. ==Using the Wiki== The following is a brief guide in using the Xataface Wiki. All following instructions assume that you are already [http://xataface.com/wiki/index.php?-action=login logged in] to the wiki. You can use your forum username and password to login. ===Editing an Existing Page=== # Navigate to the page that you want to edit # Click on the "Edit" tab along the top. # Make changes to your page. # Save the changes. ===Adding a New Page=== ====Method 1: Add a link from an existing page=== # Navigate to an existing page that you want to link to your new page. # Click on the "Edit" tab along the top. # Somewhere in the content of the page, add a link to your new page (which doesn't exist yet), by adding the following markup<code> [[The name of your new page]] </code> # Save your changes. # Click on the "view" tab along the top and find the place where you added your link. It should be displayed with a '?' right after it. Click on the '?' and it will bring you to the "new page form". # fill in the form with your page contents and click save. ====Method 2: Accessing new page form directly==== # Access the [http://xataface.com/wiki/index.php?-action=new&-table=wiki new page form] directly. ===Uploading Images=== Image can be uploaded at [http://media.weblite.ca The Web Lite Media Manager]. You'll need an account to access this site. If you are a member of the documentation team you can request an account from [mailto:steve@weblite.ca Steve Hannah] so that you can upload images here. Steps: # Log into [http://media.weblite.ca the Web Lite Media Manager]. # Click on "Add New File" in the menu on the left. # Select a name for the file, and browse to the image you want to upload in the file upload field. You don't need to check any category boxes. Press save. # Click on the "View" tab for your newly uploaded image. # Copy the embed code for the image from the "Embed Code" field. # In the wiki page add the embed code where you want your image to appear as follows:<code> [[Image:EMBED_CODE]] </code> Where EMBED_CODE is the URL for the image as you copied and pasted out of the media manager. # Save your changes. ===Uploading Video=== ===Adding Source Code Snippets=== documentation wiki en 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