conf.ini_file 25 conf.ini_file ==conf.ini File== [[toc]] The conf.ini file is where most of the application-level configuration information is stored for a Xataface application. It contains information such as: * database connection information * which tables should appear in the tables menu. * [[preferences|preference settings]] * [[authentication]] settings * which add-on [[modules]] are to be used * output caching settings * history/undo settings * other misc settings. Every conf.ini file must contain at least the following sections: {| class="listing listing2" |- ! Name ! Description ! Version |- | _database | Contains database connection info. | all |- | _tables | Contains a list of tables that are to be included in the navigation menu of the application. | all |} The following optional sections may also be included: {| class="listing listing2" |- ! Name ! Description ! Version |- | [http://xataface.com/documentation/how-to/disallow_tables _allowed_tables] | Specifies tables that should be explicitly allowed to override disallowed tables listed or matched in the [http://xataface.com/documentation/how-to/disallow_tables _disallowed_tables] section. | 0.7 |- | [[_auth]] | Contains information about [[authentication]]. | 0.6 |- | [http://xataface.com/documentation/how-to/disallow_tables _disallowed_tables] | A list of tables or patterns that match tables that should be blocked from being accessed directly through the application. By default any table beginning with an underscore, 'dataface_', or ending in '__history' are blocked. This prevents unintended access to some of the automatically created tables in Xataface. | 0.7 |- | _feed | Configuration options for [[Introduction_to_RSS_Feeds_in_Xataface|RSS feeds]] that are generated by the application. | 1.0 |- | _history | Settings pertaining to the [http://xataface.com/documentation/how-to/history-howto history feature] (e.g. whether it has been enabled). | 0.7 |- | _index | Settings for the full site search indexing. | 1.0 |- | _modules | A list of [[modules]] that are enabled for this application. | 1.0 |- | [[_output_cache]] | Output cache settings. Using output caching can dramatically improve performance for busier sites. | 0.8 |- | _themes | A list of the themes that are to be applied to the application. | 0.8 |} ===Stand-alone Attributes=== Stand-alone attributes for an INI file must appear at the beginning of the INI file (before any of the sections). The conf.ini may contain the following stand-alone attributes. {| class="listing listing2" |- ! Name ! Description ! Values ! Version |- | cache_queries | Enables query caching. Enabling this feature can yield drastic performance improvements especially on busy sites with large databases. | boolean (0 or 1) | 1.2 |- | cache_queries_log | Enables logging of query caching to the file /tmp/querylog.log so that you can tell whether your queries are being cached, and which ones are being cached. | boolean (0 or 1) | 1.2 |- | default_action | The default action to be performed if it is not explicitly specified in the query (e.g. 'list', 'find', 'edit'). Default is 'list'. | string | 0.6 |- | debug | If this is set to 1, then the application will run in debug mode which displays the available slots and blocks on the screen, along with some other debug information. | 0 or 1 (default is 0) | 0.6 |- | default_browse_action | The default action to perform in the details tab. E.g. When you click on the "details" tab there are a number of sub-tabs including 'view', 'edit', etc... . The default value for this directive is 'view'. If you want to go directly to the edit form when clicking on a record in list view, you would set ''default_browse_action'' to 'edit'. | string | 0.6 |- | default_language | The default language to use. This is the 2-digit ISO language code. If this value is not specified it defaults to the first language listed in the ''[languages]'' section. | string (2-digit ISO language code) | 0.6 |- | default_limit | The default limit (i.e. the number of records to show per page) if none is explicitly specified in the query. Default is 30. | int | 0.6 |- | default_table | The default table to show if none is specified by the query. If you do not define this value, then the first table in the ''[_tables]'' section is used. | string |0.6 |- | disable_session_ip_check | Default behaviour automatically tracks the IP address of the user when they log in. If a request is made for a session from a different IP then the session is automatically destroyed and the user is logged out. | boolean | 1.3rc4 |- | title | A title for the application (appears in the browser title bar). | string | 0.6 |- | usage_mode | The usage mode of the application. If this value is set to ''edit'', then ajax inline editing is enabled (i.e. you can click on any value in the application to edit it inline. | 'view' or 'edit' | 0.6 |} ===Example 1: A simple conf.ini file=== <code> [_database] host="localhost" name="mydb" user="mydbuser" password="foo" [_tables] webpage_sites="Websites" translations = "Translations" packages="Packages" users=Users proof_jobs="Jobs" webpage_status="Webpages Status" </code> ===Example 2: A more complex conf.ini file=== <code> ;debug=1 ;default_action=home ;google_translate_url="http://weblite-dns2.com/proxy.php" google_translate_url="http://ec2-75-101-244-123.compute-1.amazonaws.com/proxy.php" title="Web Lite Translate" default_price_per_word=0.15 ;;Configuration settings for application title="translation_weblite_ca" scriptUrl="http://translation.weblite.ca/index.php" multilingual_content=1 [_database] host="localhost" name="mydb" user="mydbuser" password="foo" [_tables] webpage_sites="Websites" translations = "Translations" packages="Packages" users=Users proof_jobs="Jobs" webpage_status="Webpages Status" [_auth] users_table=users username_column=username password_column=password secret_code="ljkasdfjkldsafliasdoiudsfoi" allow_register=1 session_timeout=999999999 [_modules] modules_ShoppingCart="modules/ShoppingCart/ShoppingCart.php" [ShoppingCart_taxes] ;; This section is necessary to declare that we have NO taxes. [metatags] keywords = "translation, translate" description = "Good translation service" ;[_output_cache] ; enabled=1 [_mail] func=mail2 </code> en 0 Creating_Printable_Reports 82 Creating a Custom Printable Report ==Creating a Printable Report== [[toc]] It is often useful to provide your users with a printable report that is generated from your database. Although Xataface doesn't include an explicit reporting module to allow the end users to create their own reports, you (the developer) can still quite easily produce a report by creating a custom action. This report will be subject to the user's sorting and searching preferences. E.g. if the user searches for only books about "frogs", then when he clicks on your printable report it will only display those records that match the query (i.e. only books about frogs). ===Requirements for our report=== # Report will be run against the "products" table (using the WebAuction application). # Report should be accessible by clicking an icon in the top right of the list view (i.e. the resultlist actions). # Report should display the product ID, product name, photo, and description. One product per page. ===Adding the Icon to our Application=== We'll start out by finding an appropriate icon to use for our action. There are loads of free icons that you can download (please observe and respect the license agreement of any icon library that you use). Two good free icon libraries include: # [http://www.famfamfam.com/lab/icons/silk/ FamFamFam Silk Icons] # [http://tango.freedesktop.org/Tango_Icon_Library Tango Icon Library] Once you have found the icon you want to use, just upload it somewhere inside your application's directory. It might be a good idea to create a directory to store your images if you haven't already. An appropriate name might by ''images''. For this example, we'll use the [[Image:http://dev.weblite.ca/phpimageserver/photos/icons/printer.png]] icon from the FamFamFam icon library. So we upload this icon to %APPLICATION_PATH%/images/printer.png Next we need to create an entry in our application's [[actions.ini file]] so that Xataface knows about our action, and where we want its icon to be displayed. We'll start out with a basic definition that just specifies the icon for the action, and the ''category'' of the action. <code> [printable_report] icon="{$site_url}/images/printer.png" category=result_list_actions description="See this product list in a printable format" </code> The ''result_list_actions'' category setting means that the icon for our action will be included along with the result list actions, which are located in the top right corner in the list tab. Now if we reload our application and look at the "list" tab, you'll see that the icon group in the top right now includes our icon: [[Image:http://media.weblite.ca/files/photos/Picture%20-5.png?max_width=640]] If you don't see this icon, but see the text "printable_report" instead, then you have entered an incorrect path to the icon in the ''icon'' directive. If you don't see an icon at all or any text, then your ''category'' directive may be incorrect. Check that it is exactly "result_list_actions". If you mouse over your icon you'll see the text that you specified as your ''description'' directive for the action: [[Image:http://media.weblite.ca/files/photos/Picture%20-6.png?max_width=640]] You'll notice, if you try to click on your icon, that nothing happens. This is because we haven't yet specified a URL for your action. We'll wait to specify our URL, until we've built the back-end of our action (i.e. the actual report). ===Creating the Actual Report=== Most reports involve the following pieces: # Fetch the found set of records from the database. # Loop through the found set and output some information about each record. # Optionally use a template to integrate the report into your application's look and feel. All reports will be placed in the framework of a custom Xataface action. In our case we add a file to our application ''actions'' directory named after our action: %APPLICATION_PATH%/actions/printable_report.php with the following contents: <code> <?php class actions_printable_report { function handle(&$params){ echo "Hello world!!!"; } } </code> Please note the following about this snippet: # The action was placed in a file ''actions/printable_report.php'' because the action is named ''printable_report'' (referring to our definition in the ''[[actions.ini file]]''. If the action was named ''foo'', then we would place our action in file ''actions/foo.php''. # The ''printable_report.php'' file contains a single class named ''actions_printable_report'' after the name of the action. # The action class contains a single method ''handle'' which handles the request for the action (i.e. outputs the report the way we like). This method must exist and me named exactly ''handle''. # The ''handle'' method takes a single ''&$params'' parameter which contains some parameters that may be passed to the action. We won't be dealing with these in this example. Before proceeding, let's try accessing our action just to make sure that we're on the right track. Point your browser to http://example.com/yourapplication/index.php?-action=printable_report Note that you don't point our web browser directly to your action php file (in the ''actions'' directory. Rather you point it to your application's entry point (index.php file), and specify the action via the ''-action'' GET parameter. Your web browser should display something like: [[Image:http://media.weblite.ca/files/photos/Picture%204.png?max_width=640]] If you get a blank white screen, then you should check your error log to see where the error is occuring. See [[Troubleshooting]] for general Xataface troubleshooting strategies in this case. Now that we have all of the formalities out of the way, we can proceed to meat of our report. ====Retrieving the Found Set==== Let's build onto our action now. First we will load the found set of records as follows: <code> <?php class actions_printable_report { function handle(&$params){ $app =& Dataface_Application::getInstance(); $query =& $app->getQuery(); if ( $query['-table'] != 'products' ){ return PEAR::raiseError('This action can only be called on the Products table.'); } $products = df_get_records_array('products', $query); } } </code> Things to note in this snippet: # We start be loading a reference to the ''Dataface_Application'' object. # We then use the ''Dataface_Application'' object to load the current query. This is essentially an associative array of all of the GET parameters, but with some guaranteed attributes such as ''-table'' and ''-action''. # In our particular action we are designing it to only work for the ''products'' table so we do a check on the query parameters to make sure that this is the case. If someone tries to run this action from outside the products table (e.g. if -action=foo) then an error will be displayed. # We use the df_get_records_array() function to return all matching records on the products table. It returns an array of [[Dataface_Record]] objects. ====Overriding -skip and -limit==== Xataface allows the user to specify the number of records to display and the position in the found set to start from by adding the ''-skip'' and ''-limit'' GET parameters to a request. If these are omitted, then default values of 0 and 30 are used respectively. You may notice that if you click "Next" in list view, you see '-skip' and '-limit' parameters automatically added to the URL. ''df_get_records_array'' respects the -limit and -skip parameters that are specified in the query. I.e. if -skip and -limit are omitted it will return only the first 30 records from the found set. If -skip=1 and -limit=10 then it will return 10 records starting from the 2nd record (2nd becuase -skip=0 would point to the first record). This may be desired behavior for your report, but in some reports you may want to print off the entire found set. If this is the case, you will want to explicitly set the -skip and -limit parameters in the ''$query'' array before passing it to ''df_get_records_array''. E.g.: <code> $query =& $app->getQuery(); $query['-skip'] = 0; $query['-limit'] = 10000; $products = df_get_records_array('products', $query); </code> ====Looping through and Printing Product Info==== Now comes the fun part. We're just going to loop through our found set and print off the product information: <code> foreach ($products as $p){ echo '<table>' .'<tr><th>Product ID</th><td>'.$p->htmlValue('product_id').'</td></tr>' .'<tr><th>Product Name</th><td>'.$p->htmlValue('product_name').'</td></tr>' .'<tr><th>Description</th><td>'.$p->htmlValue('product_description').'</td></tr>' .'<tr><th>Photo</th><td>'.$p->htmlValue('product_image').'</td></tr>' .'</table>'; } </code> The entire action at this point will look like: <code> <?php class actions_printable_report { function handle(&$params){ $app =& Dataface_Application::getInstance(); $query =& $app->getQuery(); $query['-skip'] = 0; $query['-limit'] = 10000; if ( $query['-table'] != 'products' ){ return PEAR::raiseError('This action can only be called on the Products table.'); } $products = df_get_records_array('products', $query); foreach ($products as $p){ echo '<table>' .'<tr><th>Product ID</th><td>'.$p->htmlValue('product_id').'</td></tr>' .'<tr><th>Product Name</th><td>'.$p->htmlValue('product_name').'</td></tr>' .'<tr><th>Description</th><td>'.$p->htmlValue('product_description').'</td></tr>' .'<tr><th>Photo</th><td>'.$p->htmlValue('product_image').'</td></tr>' .'</table>'; } } } </code> Now we refresh our action in the web browser, or point the browser again to: http://example.com/yourapplication/index.php?-action=printable_report&-table=products It should display something like: [[Image:http://media.weblite.ca/files/photos/Picture%205.png?max_width=640]] If you get a blank white screen, please check out the [[Troubleshooting]] section for general Xataface troubleshooting strategies. ====Adding a Little Style==== It is a good idea to at least provide the proper HTML HEAD and BODY tags for your report. And to help make things a little nicer looking we're going to add some CSS styles to: # Make the table field labels vertically aligned to the top. # Change the font to helvetica. This is easy to do with simple echo statements: <code> echo '<html><head>' .'<title>Printable Report</title>' .'<style type="text/css">' .' th { vertical-align: top}' .'</style>' .'</head>' .'<body>'; //... </code> So our finished action looks like: <code> <?php class actions_printable_report { function handle(&$params){ $app =& Dataface_Application::getInstance(); $query =& $app->getQuery(); $query['-skip'] = 0; $query['-limit'] = 10000; if ( $query['-table'] != 'products' ){ return PEAR::raiseError('This action can only be called on the Products table.'); } $products = df_get_records_array('products', $query); echo '<html><head>' .'<title>Printable Report</title>' .'<style type="text/css">' .' th { vertical-align: top}' .'</style>' .'</head>' .'<body>'; foreach ($products as $p){ echo '<table>' .'<tr><th>Product ID</th><td>'.$p->htmlValue('product_id').'</td></tr>' .'<tr><th>Product Name</th><td>'.$p->htmlValue('product_name').'</td></tr>' .'<tr><th>Description</th><td>'.$p->htmlValue('product_description').'</td></tr>' .'<tr><th>Photo</th><td>'.$p->htmlValue('product_image').'</td></tr>' .'</table>'; } echo '</body></html>'; } } </code> ===Connecting the Icon to the Action=== FInally it is time to connect our Icon to our Action. We do this by adding a ''url'' directive for the action in the ''[[actions.ini file]]'': <code> [printable_report] icon="{$site_url}/images/printer.png" category=result_list_actions description="See this product list in a printable format" url="{$app->url('-action=printable_report')}" </code> Explanation of the ''url'' directive in this snippet: * The ''url'' method of the ''[[Dataface_Application]]'' object is used to generate a URL with the user's current query settings, but with the ''-action'' parameter set to ''printable_report''. Now if we reload our application, go to the list tab of the ''products'' table and click on our icon, it should take us to our action: [[Image:http://media.weblite.ca/files/photos/Picture%207.png?max_width=640]] ===Trying out the action on different found sets with different sort orders=== One of the cool things about this action is that it is tied directly into the Xataface find settings so that th user is able to search for a subset of products and run our report on only those products that were found. The user can also perform a sort on any column and this sort will be respected by our report. ===Hiding Icon from Other Tables=== Since our action is only intended to operate on the ''products'' table it probably isn't a good idea to make the icon visible for every other table. For example, if you go to the list view of the ''users'' table, you'll see the printer icon in the top right just like it appears for the ''products'' table. Clicking on it should display our error: [[Image:http://media.weblite.ca/files/photos/Picture%206.png?max_width=640]] We will use a ''condition'' directive for our action to hide it from tables other than the ''products'' table as follows: condition="$query['-table'] == 'products'" So our action will now look like: <code> [printable_report] icon="{$site_url}/images/printer.png" category=result_list_actions description="See this product list in a printable format" url="{$app->url('-action=printable_report')}" condition="$query['-table'] == 'products'" </code> Now if you reload the list for the ''users'' table you'll notice that the printer icon is now gone. But returning to the ''products'' table shows our action still alive and well. ===Locking Down our Action with Permissions=== In our case we don't want our action to be accessible to all users. Only administrators. Xataface permissions and all its possibilities are beyond the scope of this tutorial, but we still want to demonstrate how to lock down this action. The WebAuction application into which this action is being installed defines a permission called ''reports'' which only administrators have. We will use this permission to limit access to this action as follows in the actions.ini file: permission=reports So the actions.ini file will now look like: <code> [printable_report] icon="{$site_url}/images/printer.png" category=result_list_actions description="See this product list in a printable format" url="{$app->url('-action=printable_report')}" condition="$query['-table'] == 'products'" permission=reports </code> Now only administrators will see our icon, and if non-administrators attempt to access out action by typing in its URL directly, they will receive an "Access Denied" message. en GettingStarted:first_application 74 Creating your First Application ==Creating Your First Application== Build a simple Xataface application. For our first Xataface application we will try to build a web site for Faculty of Widgetry (From the example in the "Why Use Xataface" page). The web site needs to store information about programs and courses. An entity-relationship diagram (ERD) for this website is included below: [[Image:http://xataface.com/documentation/tutorial/getting_started/er-diagram.png]] As the ERD shows, our database will need 2 tables (Course and Program). Our next step is to build this database. You can use any MySQL database administration tool to builld the database. My personal tool of choice is PHPMyAdmin. ===Step 1: Creating the database using PHPMyAdmin=== The following steps describe the procedure for creating this database using PHPMyAdmin. # At the main menu of PHPMyAdmin, type 'FacultyOfWidgetry' into the 'Create new database field' as follows: <nowiki><br/></nowiki>[[Image:http://xataface.com/documentation/tutorial/getting_started/new_database.gif]] <nowiki><br/></nowiki>Then click 'Create'. # First we will create the 'Course' table to hold course information. In the 'FacultyOfWidgetry' page, fill in the 'Create new table text field as follows: <nowiki><br/></nowiki>[[Image:http://xataface.com/documentation/tutorial/getting_started/create_table.gif]] <nowiki><br/></nowiki> Then click 'Go'. # This should bring up a form to specify the fields for the course table: <nowiki><br/></nowiki>[[Image:http://xataface.com/documentation/tutorial/getting_started/course-table-def-small.gif]] <nowiki><br/></nowiki> Then click "Save". The resulting SQL to create the Course table is as follows:<code> CREATE TABLE `Course` ( `CourseID` int(11) NOT NULL auto_increment, `ProgramID` int(11), `CourseTitle` varchar(64) NOT NULL default '', `CourseDescription` text NOT NULL, `HTMLOutline` text NOT NULL, `PDFOutline` longblob NOT NULL, `PDFOutline_mimetype` varchar(64), `Subject` varchar(128) NOT NULL default '', `CourseNumber` varchar(10) NOT NULL default '', `Credits` int(5) NOT NULL default '0', `LastModified` timestamp NOT NULL default CURRENT_TIMESTAMP, PRIMARY KEY (`CourseID`) ) ENGINE=MyISAM DEFAULT CHARSET=latin1 COMMENT='Store courses' AUTO_INCREMENT=1 ; </code> #In a similar fashion, create the Program table. The resulting SQL for this table is:<code> CREATE TABLE `Program` ( `ProgramID` int(11) NOT NULL auto_increment, `ProgramName` varchar(64) NOT NULL default '', `ProgramDescription` text NOT NULL, `HTMLOutline` text NOT NULL, `PDFOutline` longblob NOT NULL, `PDFOutline_mimetype` varchar(32), `AdmissionDeadline` date NOT NULL default '0000-00-00', `LastModified` timestamp NOT NULL default CURRENT_TIMESTAMP, PRIMARY KEY (`ProgramID`) ) ENGINE=MyISAM DEFAULT CHARSET=latin1 COMMENT='Academic Program' AUTO_INCREMENT=1 ; </code> # The database has been created with 2 tables: Program and Course. We can now move on to building the Xataface application. ===Step 2: Create Xataface Application=== Our Xataface application will provide a user-friendly front-end to our database. A basic application consists of a directory with a configuration file and an entry page (PHP file). Xataface comes with a PHP setup script (called makesite) to create the skeleton for your application. Alternatively you can set up the application manually. Note: For the following instructions and examples, my Daface installation is located at /Users/shannah/Sites/dataface and the URL for the installation is http://localhost/~shannah/dataface. ====Method 1: Setting up application with the 'makesite' script==== # From the command prompt, navigate to the dataface directory. (in my case ''/Users/shannah/Sites/dataface''). # This directory contains a file named 'makesite'. It is a PHP script that can be used to build a website powered by Xataface. To find out the usage options for this script you can simply call the script with no parameters. E.g.,<code> stevepbook:~/Sites/dataface shannah$ ./makesite </code> # This will give you usage instructions for the script as follows:<code> makesite: invalid options entered. Usage: makesite <site_path> <db_user>:<db_pass>@<db_host>/<db_name> <dataface_url> or php makesite <site_path> <db_user>:<db_pass>@<db_host>/<db_name> <dataface_url> where <site_path> = The path (absolute or relative) to your application directory. <db_user> = The MySQL username to connect to the database <db_pass> = The User's password to connect to the database <db_host> = The MySQL host name. <db_name> = The name of the mysql database for the application. <dataface_url> = The URL to the Xataface installation Examples: makesite ../FacultyOfWidgetry root:password@localhost/FacultyOfWidgetry /dataface The above command would create a site at ../FacultyOfWidgetry (i.e., the Faculty of Widgetry directory in the parent directory. The database used for this site is located at localhost, and the database name is FacultyOfWidgetry. The username to connect to the database is root and his password is password. </code> # We create our FacultyOfWidgetry site using the following command:<code> ./makesite ../FacultyOfWidgetry \ root@localhost/FacultyOfWidgetry \ http://localhost/~shannah/dataface </code> # This will create our application in the FacultyOfWidgetry folder if everything worked ok. The contents of the folder will look like: <nowiki><br/></nowiki>[[Image:http://xataface.com/documentation/tutorial/getting_started/directory-structure-1.gif]] You may be wondering what these files. Here is the short version (Read the next section "Creating applications manually" for more detailed information about the contents of these files. The index.php file is the entry point for your application (i.e., you point the web browser at this file to use the application. The conf.ini file contains database connection settings and some other minor settings, like what should appear in the navigation menu. The tables/Program (tables/Course) directory can contain configuration files specific to the Program (Course) table. More on that later. # Point your web browser to the FacultyOfWidgetry directory to see the application: <nowiki><br/></nowiki>[[Image:http://xataface.com/documentation/tutorial/getting_started/basic-application-1.gif]] #Your application is now created. It will enable you to add, edit, delete, and find records in either the Course table or the Program table. There will be more on the basics of using this application in the next section. ====Method 2: Setting up application manually==== Using the makesite script as described above is the recommended way to set up an application because it saves time. However, it is very easy to set up the application manually. Just follow these steps: # Create a directory for the application somewhere in your web site (preferably outside your xataface directory). We will call our directory 'FacultyOfWidgetry'. ):<code> mkdir FacultyOfWidgetry </code> # Create a PHP file to serve as the access point for the application. Generally we will name this file 'index.php', but you can name it anything. Place the following contents in the index.php file:<code> <? require_once '/path/to/dataface/dataface-public-api.php'; df_init(__FILE__, 'http://yourdomain.com/dataface'); $app =& Dataface_Application::getInstance(); $app->display(); </code><nowiki><p>OK, I guess some explanations are in order.</p><p> The first line imports the all of the public functions for dataface from the dataface-public-api.php file.</p><p> The second line initializes the application for the current directory and specifies the URL to the dataface installation.</p><p> The third line obtains an instance to the Application object - the core of your Dataface application.</p><p> The fourth line simply displays the application.</p></nowiki> # Create a file named 'conf.ini' to contain database connection information. Its contents should be:<code> [_database] host = "localhost" user = "dbuser" password = "secret" name = "FacultyOfWidgetry" [_tables] Course = "Course" Program = "Program" </code><nowiki><p><b>Explanations:</b></p><p>There are 2 sections in this INI file: '_database', and '_tables'.</p><p> The '_database' section specifies the database connection information for the MySQL database.</p><p> The '_tables' section specifies which tables will be included in the navigation menu for the application.</p></nowiki> # At this point, the application is functional. However there is one more thing that should be done for security reasons. The conf.ini file contains sensitive password information and should not be served to the web. We will create an .htaccess file to tell Apache NOT to serve this (or any) .ini file. The .htaccess file should contain:<code> <FilesMatch "\.ini$"> Deny from all </FilesMatch></code> # The directory structure of your application will now look like: <nowiki><br/></nowiki>[[Image:http://xataface.com/documentation/tutorial/getting_started/basic-app-dir-structure-manual-1.gif]]<nowiki><p> Note, however, that there is also an .htaccess file that is hidden from this image.</p><p>You may be wondering why there is no 'tables' directory like the directory structure that was generated by the makesite script. The 'tables' directory is not required for the application to be functional. It will be required later on when we start to decorate the database.</p></nowiki> # The application is now ready to go. Point your web browser to the index.php file that you created. It will look like:<nowiki><br/></nowiki>[[Image:http://xataface.com/documentation/tutorial/getting_started/basic-application-1.gif]] ===Download source files=== [[File:http://xataface.com/documentation/tutorial/getting_started/facultyofwidgetry-4-tar.gz|Download the source files]] for this application at a tar.gz archive. These files reflect the state of the application at this point of the tutorial. As later sections make changes to the application you will be able to download those versions also. htaccess first application installation en Creating_a_Dashboard 57 Creating_a_Dashboard ==Creating a Dashboard for your Users== [[toc]] Xataface allows you to build powerful data-driven applications quickly, but these applications may be daunting to your users if they don't know what they can do with the application. Most applications provide some sort of dashboard or control panel with some introductory instructions and links to commonly used actions in the application. This makes the application more intuitive for users so that they can start using it right away, even without instruction from the developer. ===Characteristics of a Dashboard=== # Should be the default page when someone visits the application. # Should be customized to show menus and content that are relevant to the current user. (i.e. different users may see different links and content on their dashboard). # Should contain at least some basic instructions so that the user understands what the application does when he visits the dashboard for the first time. # Should contain links to frequently used actions. ===Strategies: 8 ways to skin the cat=== There are many viable strategies for adding a dashboard to your Xataface application. This article presents only one. It has been chosen because it satisfies all of the desired characteristics of a dashboard listed above, and it is easy to implement. This strategy involves the following components: # Create a dummy ''dashboard'' table. # Create a dashboard action and associated template. # Make sure our dashboard action is the default action for our application (more complex than just using the [[default_action]] directive in the [[conf.ini file]]. ==Our Sample Application== Consider our sample application, a publications management system for professors and research groups at a university. It allows users to manage their publications using either BibTex format or a web-based form, and embed those publications into their webpage in a slick sortable format. Currently, when the user accesses the application for the first time, they are shown the ''list'' tab of the ''bibliographies'' table. This isn't all that informative and it may not be obvious to the user that their first step should be to create a new bibliography via the ''new record'' button. Ideally we would like the user to go directly to a dashboard page with options to: # Add New Bibliography # Edit an Existing Bibliography # Embed a Bibliography into their Webpage And we want some basic instructions so that the user knows what to do when they first access the page. ==The Steps== To create this dashboard we will follow the steps listed below (and mentioned above in the ''strategies'' section. ===Step 1: Create a dummy ''dashboard'' table=== This may seem unorthodox but it just happens to make our lives easier in the long run. By creating a dummy table we are able to cause that table to be listed first in the ''_tables'' section of the [[conf.ini file]] and thus be the default table when users visit our application. <code> CREATE TABLE dashboard ( dashboard_id int(11) not null auto_increment primary key ); INSERT INTO dashboard values (1); </code> ===Step 2: Make ''dashboard'' table default=== We now modify the conf.ini file to list the ''dashboard'' table first: <code> [_tables] dashboard=Dashboard bibliographies=Bibliographies </code> ===Step 3: Create a Dashboard action and associated template=== This is the step where we actually create our dashboard action. There are three parts to this story: ====Creating Action PHP Class==== The actual action will be located in the ''actions/dashboard.php'' file of our application, and looks like: <code> <?php class actions_dashboard { function handle(&$params){ $bibs = df_get_records_array('bibliographies', array()); df_display(array('bibliographies'=>$bibs), 'dashboard.html'); } } </code> All this does is loads the ''bibliographies'' records owned by the current user. Elsewhere we are using security filters so that the user can only see ''his'' bibliographies, which is why we don't need to specify any query here in the ''df_get_records_array'' function. It then passes those bibliographies to the ''dashboard.html'' template that we create next. ====Creating the Action's Template==== The template for our action is located in the ''templates/dashboard.html'' file: <code> {use_macro file="Dataface_Main_Template.html"} {fill_slot name="main_column"} <h1>Welcome to the BibTeX Publication Management System (BPMS)</h1> <p>This system allows you to manage your publications and publish them on the web. Some common actions you may perform with this system include: <ul> <li><img src="{$ENV.DATAFACE_URL}/images/add_icon.gif"/> <a href="{$ENV.DATAFACE_SITE_HREF}?-table=bibliographies&-action=new"> Create New Bibliography</a> </li> <li><img src="{$ENV.DATAFACE_URL}/images/edit.gif"/> Edit existing bibliography: <select onchange="window.location.href=this.options[this.selectedIndex].value"> <option value="">Select ...</option> {foreach from=$bibliographies item=bibliography} <option value="{$bibliography->getURL('-action=edit')}"> {$bibliography->getTitle()} </option> {/foreach} </select> </li> <li><img src="{$ENV.DATAFACE_URL}/images/file.gif"/> Embed your bibliography in a webpage: <select onchange="window.location.href=this.options[this.selectedIndex].value"> <option value="">Select ...</option> {foreach from=$bibliographies item=bibliography} <option value="{$bibliography->getURL('-action=view')}#embed"> {$bibliography->getTitle()} </option> {/foreach} </select> </li> </ul> {/fill_slot} {/use_macro} </code> A few key things to notice in this template: # It extends the ''Dataface_Main_Template.html'' template placing its content in the ''main_column'' slot. This allows our action to still display within the header and footer of our application. # It makes use of the {$ENV.DATAFACE_SITE_URL} and {$ENV.DATAFACE_SITE_HREF} variables to refer to the site's base url and create links to the desired common actions. # It provides a direct link to the ''new bibliography record'' form. # It uses some slick javascript combined with select lists to allow the user to select any of his current bibliogaphies and edit them, or embed them into a webpage. ====Adding entry to the actions.ini file==== Currently our dashboard action has no permissions attached to it so users can see it whether they are logged in or not. In this particular application we want to require users to log in, and we have set permissions for all logged in users to NO_ACCESS(). Unfortunately this permission setting is only helpful if our action requires a particular permission to access it. We'll require the 'view' permission for this action, by adding the following to the actions.ini file: <code> [dashboard] permission=view </code> ===Step 4: Specify permissions=== We still want to specify permissions for our ''dashboard'' table to ensure that only logged in users can access the dashboard. So we create a delegate class for the ''dashboard'' table at ''tables/dashboard/dashboard.php'' with the following contents: <code> <?php class tables_dashboard { function getPermissions(&$record){ if ( getUser() ){ return Dataface_PermissionsTool::ALL(); } return null; } } </code> '''Note that we have defined the getUser() function elsewhere as a means of obtaining the current user and checking if a user is indeed logged in.''' Notice that this [[getPermissions]] method returns all permissions only if the user is logged in. Otherwise it returns null, which means that it should use the same permissions as the rest of the application as defined in the [[Application Delegate Class]]. ===Step 6: Make ''dashboard'' the default action for the ''dashboard'' table=== Now we just have one more detail that needs to be taken care of. We want the ''dashboard'' action to be the default action for the ''dashboard'' table only. By default we would see the ''list'' action which isn't helpful at all, so we will want to add a rule in our application delegate class to ensure that the user only sees our custom ''dashboard'' action if they access the ''dashboard'' table. We define a beforeHandleRequest() method in our conf/ApplicationDelegate.php (the application delegate class) file for this purpose: <code> <?php class conf_ApplicationDelegate { ... function beforeHandleRequest(){ ... $app =& Dataface_Application::getInstance(); $query =& $app->getQuery(); if ( $query['-table'] == 'dashboard' and ($query['-action'] == 'browse' or $query['-action'] == 'list') ){ $query['-action'] = 'dashboard'; } } ... } </code> This simply checks to see if the table is ''dashboard'' and changes the current action to ''dashboard'' if so. ===Step 7: Try it out=== At this point, we are ready to try out our new dashboard to see how it works. When we load our application it should now go to the dashboard action that we created. We should also see ''Dashboard'' listed as the first table in the tables menu. This dashboard presents a major improvement to our application as it is now much more user friendly. <nowiki> <img src="http://media.weblite.ca/files/photos/pub-dashboard.png?max_width=640"/> </nowiki> dashboard en 0 GettingStarted:customizing 76 Customizing Field labels, descriptions, and widgets ==Customizing Field labels, descriptions, and widgets== Using simple INI configuration files, you can customize the look and feel of your application. You can change widgets, labels, field descriptions, and more. In the previous 2 sections we learned how to create a simple application by desiging a database and then installing the basic directory structure to make our application operational. Now it is time to "decorate" the application a little bit. Decoration occurs by way of simple configuration files that are placed in strategic locations in the application. We can customize such things as: * Widget types (e.g., use a select list for a field rather than a text field) * Labels (e.g., The ProgramName field's label can say "Program Name" instead of just "ProgramName") * Field Descriptions . You can add descriptions to fields to help explain their meaning and how to use the application. * HTML attributes. (e.g., Make a text field 50 characters wide) ===Table Configuration Directories=== You will recall, that when we used the 'makesite' script to generate the directory structure for our web application, it created a directory named 'tables', with subdirectories named after each of the tables in our database. The directory structure of the application looked like: [[Image:http://xataface.com/documentation/tutorial/getting_started/directory-structure-1.gif]] The 'tables/Program' and 'tables/Course' are refered to as "table configuration directories" . All of the configuration files a table in a Xataface application are stored in its associated table configuration directory. For example all configuration files for the 'Program' table are located in the 'tables/Program' directory. There are 4 main files that are generally contained in a table's configuration directory: * '''fields.ini''' - Contains configuration for the fields of the table (e.g., field labels, descriptions, widget types, etc...) * ''valuelists.ini''' - Contains value lists (vocabularies) that can be used in the table to limit input into certain fields like select lists. * '''relationships.ini''' - Defines the relationships between this table and other tables in the application. * '''<TableName>.php''' (where <TableName> is the name of the table. - A delegate PHP class that allows you to further customize the behavior of the application with respect to this table. May contain custom fields, importing/exporting functionality, permissions information, and more... ===Customizing Labels and Descriptions=== We will start off by adding custom labels and descriptions to the 'Program' table of our 'FacultyOfWidgetry' application. This sort of customization settings are placed in a file named 'fields.ini' inside the table's configuration directory. # Create the 'fields.ini' file in the Program table configuration directory (i.e., tables/Programs/fields.ini). # Add the following to this file:<code> [ProgramName] widget:label = "Program Name" widget:description = "Enter the name of the program" </code><nowiki><br></nowiki>Now look at the "Edit Record" form in the Xataface application: [[Image:http://xataface.com/documentation/tutorial/getting_started/program-name-label-1.gif]] Notice how the label for the "ProgramName" now says "Program Name" (note the space between "Program" and "Name"). And its description matches the description specified in the fields.ini file. The widget:label and widget:description attributes can be defined for any field in any table of the application. ===Using different widgets=== If no widgets are defined in the fields.ini file, a Xataface application will make a best guess at the type of widget that should be used to edit the value in a field. In general, the widgets used by default are as follows: * VARCHAR, CHAR, INT : html text field * DATE, DATETIME fields: calendar widget * TEXT fields : html text area * BLOB fields : html file upload field * INT Fields with "AUTO INCREMENT" : html hidden field * VARCHAR or CHAR fields with "Password" or "password" as part of the name : html password field * ENUM fields : html select list * SET fields : html checkbox group (not yet supported as of this writing). You can change the widget that is used to edit a field by specifying a "widget:type" attribute for the field in the fields.ini file. For more information about the available widgets, see [[widget:type]]. ====Example: Using HTML Editor to edit the HTMLOutline field==== Clearly the HTMLOutline field in the Program table is intended to store HTML content. By default our application only provides a text area to do the editing so the user is expected to enter the HTML markup by hand. It would be much better to provide the user with a WYSIWYG (What you see is what you get) HTML editor widget. That is exactly what we are going to do. We will add a section to the fields.ini file so that it now looks like: <code> [ProgramName] widget:label = "Program Name" widget:description = "Enter the name of the program" [HTMLOutline] widget:type = "htmlarea" </code> Now refresh the Xataface application in your web browser and look at the edit form for a record of the Program table: [[Image:http://xataface.com/documentation/tutorial/getting_started/htmlarea-1.gif]] As you can see, the HTMLOutline field now has an HTML Editor widget for editing. Most users will find this much nicer to work with than a normal text area. Xataface uses FCKEditor for its html editor widget. There are a number of widgets that can be specified in the [[widget:type]] parameter: * '''[[checkbox]]''' - An HTML checkbox (or checkbox group depending on context). * '''[[date]]''' - Month/Day/Year select lists for selecting dates. * '''[[calendar]]''' - A text field with a button that opens a small calendar widget when clicked. * '''[[group]]''' - A complex widget type for editing multiple values as a group (useful for XML fields) * '''[[hidden]]''' - a hidden field * '''[[password]]''' - An HTML password widget * '''[[select]]''' - An HTML select list (requires the 'vocabulary' attribute) * '''[[static]]''' - an uneditable field * '''[[table]]''' - A complex widget type for editing multiple values in a tabular format (Useful for XML fields) * '''[[text]]''' - an html text field * '''[[textarea]]''' - an html text area ===Changing HTML attributes of widgets=== Sometimes you may want even finer grained control of your widgets' appearance than to just specify the type, label, and desription. Perhaps you want to make a text field 50 characters wide, or to set the CSS class of the html element. This can be done using the 'widget:atts:' parameter for a field. A short example is the easiest way to explain how this works. Modify the fields.ini for the Program table so it looks like:<code> [ProgramName] widget:label = "Program Name" widget:description = "Enter the name of the program" widget:atts:size = 50 widget:atts:style = "font-size: 24pt; font-family: Apple Chancery" [HTMLOutline] widget:type = htmlarea </code> We have added 2 lines:<code> widget:atts:size = 50 widget:atts:style = "font-size: 24pt; font-family: Apple Chancery" </code> What this does is add the html attributes size="50" and style="font-size: 24pt; font-family: Apple Chancery" to the html text field that is used to edit the ProgramName field. Look at the results: [[Image:http://xataface.com/documentation/tutorial/getting_started/widget-atts-1.gif]] The HTML tag for the text field now looks like:<code> <input class="default" id="ProgramName" name="ProgramName" type="text" size="50" style="font-size: 24pt; font-family: Apple Chancery" value="Basic Widgetry" /> </code> In fact you can add arbitrary attributes to any of the fields using the same convention. Some useful examples are: * '''[[widget:atts:rows]]''' for text areas to set the number of rows of text they should display. * '''[[widget:atts:cols]]''' for text areas to set the number of columns (1 character = 1 column) You can even use javascript calls in here if you like: * '''[[widget:atts:onclick]]''' = "doJsFunction();" ===Download source files=== [http://xataface.com/documentation/tutorial/getting_started/facultyofwidgetry-6-tar.gz Download the source files] for this application as a tar.gz archive These source files reflect the state of the application at the current point of the tutorial. As changes are made to the application in later sections, downloads of those versions are made available for download also. ===Summary=== In this section we learned how to change the labels, descriptions, and widgets for fields. We also learned how to add HTML attributes to the widgets to achieve very fine-grained control over the display of our forms. widget labels descriptions onclick handlers en 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 Customizing_the_look_and_feel_of_a_row_or_a_cell 62 Customizing_the_look_and_feel_of_a_row_or_a_cell ==How to customize the look and feel of elements in the list view== ===Create a method in a delegate class=== In the delegate class, the method ''css__tableRowClass'' is implemented, like in this example : <code>class tables_journal_interventions { function css__tableRowClass(&$record){ if ( !$record->val('fermeture')){ return 'intervention_close'; } else return ''; } } </code> Here the function tests a condition : is there a value in the field ''fermeture'' ? ===Add the class in a CSS stylesheet=== Now the class is created in a CSS stylesheet. <code>td.intervention_close { background-color: #FFE6E6 !important; } </code> This is a class for each cell, the <td> tag. The ''!important'' attribute is added to be sure that this information has precedence over all the others. It is better to add this class in a [http://xataface.com/documentation/how-to/custom_javascripts custom CSS stylesheet]. ===Remarks=== Beware that some versions of IE don't respect the background-color property on the <tr> tag, so it is probably better to write: <code> tr.intervention_close td { background-color: #FFE6E6; }</code> i.e. to apply the background color to the individual cells. en 0 DataGrid 32 DataGrid ==Xataface DataGrid Module== Created by Steve Hannah, [http://weblite.ca Web Lite Solutions Corp.] ===Synopsis=== The Xataface DataGrid module uses the Ext DataGrid component (http://extjs.com) to add an editable grid component to your Xataface application. [[toc collapse=0]] ===Requirements=== * PHP 4.3+ * MySQL 4.1+ * Xataface 0.8+ ===License=== This module is distributed with ExtJS 2.2, which is distributed under the GPL v 3 (http://extjs.com/products/license.php). In order to be compatible with the ExtJS license, this module is also distributed under the terms of the GPL v3 (http://www.gnu.org/copyleft/gpl.html). ===Demo Video=== <nowiki> <embed src="http://media.weblite.ca/lib/flvplayer.swf" width="640" height="500" bgcolor="#FFFFFF" type="application/x-shockwave-flash" pluginspage="http://www.macromedia.com/go/getflashplayer" flashvars="file=http%3A%2F%2Fs3.amazonaws.com%2Fweblite_media%2FDataGrid-640x480.flv&image=http%3A%2F%2Fmedia.weblite.ca%2Ffiles%2Fphotos%2FDataGrid-640x480.flv.jpg&showdigits=true&autostart=false" /> </nowiki> ===Screenshots=== Click on image to enlarge <nowiki> <script language="javascript" type="text/javascript" src="http://media.weblite.ca/index.php?-action=gallery&-table=files&categories=8&-cursor=0&-skip=0&-limit=30&-mode=list&-photo_max_width=640&--format=js"></script> <div style="clear:both">&nbsp;</div> </nowiki> ===Demo=== # LibrarianDB Demo: http://demo.weblite.ca/apps/librariandb/index.php?-table=books&-action=DataGrid_view , '''Log in with username "admin" and password "password"''' ===Download=== * [https://sourceforge.net/project/platformdownload.php?group_id=250381 DataGrid-0.2] * SVN Repository: http://weblite.ca/svn/dataface/modules/DataGrid ===Installation=== # Download and extract the DataGrid directory into your xataface/modules directory. # Add the following line to the [_modules] section of your application's [[conf.ini file]]:<code> modules_DataGrid=modules/DataGrid/DataGrid.php </code> # Ensure that your [[permissions]] are set up appropriately to allow your users to access the grid action (see next section). ===Setting Up Permissions=== This module defines the following [[permissions]]: * DataGrid:view_grid - Permission to view the data grid for a table. * DataGrid:create_grid - Permission to create a new data grid * DataGrid:edit_grid - Permission to edit an existing data grid * DataGrid:update - Permission to update records via the grid * DataGrid:manage_grids - Permission to access the datagrid control panel In order for a user to access/use the grid he must be granted at least the Datagrid:view_grid and DataGrid:update [[permissions]]. Both of these [[permissions]] are included in the following system roles by default: * EDIT * EDIT AND DELETE * DELETE * ADMIN * MANAGER And of course these [[permissions]] are included with the call to Dataface_PermissionsTool::ALL() . If you have assigned your own custom roles and want to enable access to the grid, you can simply add the following to your role definition in your [[permissions.ini file]]: <code> [MY ROLE] DataGrid:view_grid=1 DataGrid:update=1 </code> If you want to explicitly disable the grid for a role, you can extend the role and deny those same [[permissions]]: <code> [MY ROLE extends MY ROLE] DataGrid:view_grid=0 DataGrid:update=0 </code> ===Usage=== Once installed, log in as a user that has permission to access the grid. You should notice a new tab along with "details", "list", and "find", called "grid". Click on the "grid" tab to access the grid. You can double click on any field to edit it. Modified fields will be marked in red, and automatically saved every 5 seconds - after the changes are saved the field is no longer marked in red. ===Limitations=== Currently only fields with the following widget types are available to be edited in the grid: # text # textarea # select # date/datetime/time Other types of fields will simply not be included in the grid. ===Support/Questions=== Visit the Xataface forum at http://xataface.com/forum en 0 field__fieldname 141 Defining Calculated Fields Return to [[Delegate class methods]] Xataface allows you to define calculated fields using the delegate class. These fields won't be visible in the UI by default, but they will be accessible to some modules (e.g. the HTML Reports Module) and they are always accessible to you via the API. E.g. If you define a calculated field named ''year'', you would be able to access this value using the regular Dataface_Record syntax: <code> $record->val('year'); </code> You could also define any number of filter methods and permissions on this field just as you can on regular fields. e.g. <code> function year__permissions($record){ // Return special permissions on the year field. } </code> or <code> function year__display($record){ // Override how the year is displayed in the UI. return $record->val('year').' A.D.'; } </code> ==How to Define a Calculated Field== In the delegate class you simply create a method with the following naming convention: <code> function field__fieldname(Dataface_Record $record); </code> where the return value is the value that the given record should have for the field ''filedname''. E.g. <code> function field__year($record){ $time = trtotime($record->strval('date')); if ( $time ){ return date('Y', $time)); } else { return ''; } } </code> calculated fields, field__fieldname 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 Delegate_class_methods 7 Delegate_class_methods ==Delegate Class Reference== [[toc]] A delegate class is a PHP class that complements a particular table with custom bahaviors. Basic table metadata can be supplied using the [[fields.ini file]], however some things are better customized using PHP. ===Delegate Class Location=== The delegate class should be located in a file named TABLENAME.php (where TABLENAME is the name of the table with which the delegate class is associated) inside the table's [[table configuration directory|configuration directory]]. E.g. given a table named "people", you would place the delegate class in the file "tables/people/people.php" ===Basic Delegate Class=== <code> <?php class tables_people {} ?> </code> ===Available Methods=== ====Table Settings==== {| class="listing listing2" ! Name ! Description ! Version |- | [[sql delegate method|__sql__]] | Defines the SQL query that can be used to fetch records of this table. This is identical to the [[fields.ini file]] [[__sql__]] directive, except that by defining it in the delegate class you have more flexibility. | 1.0 |} ====Permissions==== {| class="listing listing2" ! Name ! Description ! Version |- | [[getPermissions]] | Returns the permissions available for a given record. | 0.6 |- | getRoles | Returns the roles allowed for a given record. | 1.0 |- | [[__field__permissions]] | Returns the default permissions for a field of a given record. | 1.0 |- | __field__roles | Returns the default roles for a field of a given record. | 1.0 |- | [[fieldname__permissions]] | Returns the permissions that are allowed for the field "fieldname" on a given record. | 0.7 |- | fieldname__roles | Returns the roles that are allowed for the field "fieldname" on a given record. | 1.0 |- | rel_relationshipname__permissions | Returns the permissions pertaining to the relationship ''relationshipname'' on a given record. | 1.0 |- | rel_relationshipname__roles | Returns the role or roles pertaining to the relationship ''relationshipname'' on a given record. | 1.0 |} ====Triggers==== {| class="listing listing2" ! Name ! Description ! Version |- | [[after_action_edit]] | Trigger called after the edit action is succesfully completed. | 0.7 |- | [[after_action_new]] | Trigger called after the new action is successfully completed. | 0.7 |- | [[after_action_delete]] | Trigger called after the delete action is successfully completed. | 0.7 |- | [[afterAddExistingRelatedRecord]] | Trigger called after an existing related record is added. | 0.5 |- | [[aftereAddNewRelatedRecord]] | Trigger called after a new related record is added. | 0.5 |- | [[afterCopy]] | Trigger called after a record is copied. | 1.3 |- | [[afterDelete]] | Trigger called after a record is deleted. |0.5 |- | [[afterAddRelatedRecord]] | Trigger called after a related record of this table is added (either an existing record or a new record). | 0.5 |- | [[afterRemoveRelatedRecord]] | Trigger called after a related record is removed from a relationship. | 1.1.6 |- | [[afterInsert]] | Trigger called after a given record is inserted. | 0.5 |- | [[afterSave]] | Trigger called after a given record is saved (insert or update). | 0.5 |- | [[afterUpdate]] | Trigger called after a given record is updated. | 0.5 |- | [[beforeAddExistingRelatedRecord]] | Trigger called before an existing related record is added. | 0.5 |- | [[beforeAddNewRelatedRecord]] | Trigger called before a new related record is added. | 0.5 |- | [[beforeAddRelatedRecord]] | Trigger called before a related record of this table is added (either an existing record or a new record). | 0.5 |- | [[beforeCopy]] | Trigger called before a record is copied. | 1.3 |- | [[beforeDelete]] | Trigger called before a record is deleted. | 0.5 |- | [[beforeRemoveRelatedRecord]] | Trigger called before a related record is removed. | 1.1.6 |- | [[beforeSave]] | Trigger called before a given record is saved (insert or update). | 0.5 |- | [[beforeInsert]] | Trigger called before a given record is inserted. | 0.5 |- | [[beforeUpdate]] | Trigger called before a given record is updated. | 0.5 |- | [[init]] | This method is called the first time the table is loaded. It allows you to specify initialization details. | 0.8 |} ====Field Filters==== {| class="listing listing2" ! Name ! Description ! Version |- | fieldname__htmlValue | Returns the value of the field "fieldname" for a given record as HTML. | 0.5 |- | fieldname__display | Returns the value of the field "fieldname" appropriate for displaying. | 0.5 |- | [[fieldname__default]] | Returns the default value for the field ''fieldname''. New record forms will be prepopulated with this value. | 0.7 |- | [[fieldname__validate]] | Validates the input for the field ''fieldname''. | 0.6 |- | fieldname__parse | Parses the input value for the field ''fieldname''. This is called by Xataface inside the setValue() method or each record to normalize input values before they are stored in the object (not the database). | 0.5 |- | fieldname__toString | Converts the value of the field ''fieldname'' to a string. This string representation is used as the basis for most higher level data retrieval methods (such as serialize and display). This could be treated as an inverse to the [[fieldname__parse]] method. | 0.5 |- | fieldname__serialize | Converts a value of the field ''fieldname'' to be saved in the database. This should return a string representation of the value that is suitable for database storage. | 0.5 |- | fieldname__link | A link that appears beside the field ''fieldname'' on the edit form. | 0.6 |- | [[field__pushValue]] | Converts form input for field ''fieldname'' to be ready to store in a Dataface_Record. | 0.6 |- | [[field__pullValue]] | Converts a value for field ''fieldname'' in a Dataface_Record object to be ready to be inserted as a value on an HTML form. | 0.6 |- | [[field__fieldname]] | Effectively creates a calculated field named "fieldname" available on the given record. | 0.6 |- | [[no_access_text]] | Replace the default NO ACCESS permission text with another text. | 1.1.6 |- | [[no_access_link]] | Replace the default link of the NO ACCESS permission link with another link. | 1.1.6 |} ====Template Customization==== {| class="listing listing2" ! Name ! Description ! Version |- | [[block__blockname]] | Outputs content that is meant to override a slot or a block named "blockname". | 0.6 |} ====List Tab Customization==== {| class="listing listing2" ! Name ! Description ! Version |- | css__tableHeaderCellClass | Returns a custom CSS class for a table header cell (th tag) in the list view. Takes the name of a table column as a parameter. | 2.0alpha2 |- | css__tableRowClass | Returns a custom CSS class for a table row (tr tag) in list view. Takes a Dataface record as a parameter. | 1.2 |- | fieldname__renderCell | Overrides the table cell content for the "fieldname" field in list view with custom HTML. | 1.0 |- | renderRow | Overrides the the html used for a row in list view for the given record. | 0.7 |- | renderRowHeader | Overrides the header for the table in list view. | 0.7 |- | renderRelatedRow | Overrides the html used for a row in a related record list for a given related record. | 1.0 beta 4 |- | renderRelatedRowHeader | Overrides the html used for the header in a related list. | 1.0 beta 4 |} ====Record Metadata==== {| class="listing listing2" ! Name ! Description ! Version |- | [[getBreadCrumbs]] | Returns the bread crumbs (i.e. you are here) for a given record as an associative array of path parts. | 0.6 |- | [[getChildren]] | Returns a list of Dataface_Record objects that are to be considered children of the given record. | 0.8 |- | [[getCreated]] | Returns a unix timestamp marking the date that a record was created. | 0.9 |- | getDescription | Returns a string description summary of this record. This is used for indexing, RSS feeds, and anywhere that a brief summary of a record is appropriate. | 0.7 |- | getPublicLink | Returns the public URL of this record (in case it is different than the standard URL). | 0.8 |- | getTitle | Returns the title for a given record. The title is used in various parts of the application to represent the record. | 0.5 |- | [[getURL]] | Overrides the getURL() method for a record. Returns the URL that should be used to display the given record. | 0.6 |- | titleColumn | Returns a string SQL select expression that is used to describe the title of records. | 0.5 |} ====View Tab Customization==== {| class="listing listing2" ! Name ! Description ! Version |- | [[How_to_Add_Custom_Sections_to_View_Tab|section__sectionname]] | Defines a section to be displayed in the view tab for the given record. | 0.7 |} ====Search Setup==== {| class="listing listing2" ! Name ! Description ! Version |- | getSearchableText | If [[_index|Indexing]] is turned on, then this returns the text that should be stored in the index for this record for searchability. | 1.0 |} ====RSS Feed Customization==== {| class="listing listing2" ! Name ! Description ! Version |- | [[getFeedItem]] | For RSS Feeds, overrides the defaults and returns an associative array with feed elements for a particular record | 1.0 |- | [[getFeed]] | For RSS feeds, overrides the default feed for a query, returning an array of feed items. | 1.0 |- | getFeedSource | Overrides the default feed source parameter for an RSS feed. | 1.0 |- | [[getRelatedFeed]] | For RSS feeds, overrides the default feed for a related feed. | 1.0 |- | getRSSDescription | Overrides the default generated RSS description for a record. | 1.0 |} ===XML Output Customization=== {| class="listing listing2" ! Name ! Description ! Version |- | [[toXML]] | Overrides the default XML produced for a record in the [[export xml]] action. Returns an XML string. | 1.2.7 |- | [[getXMLHead]] | Returns a string to be included at the beginning of XML output for a particular record. (just inside the opening tag). | 1.2.7 |- | [[xmlTail]] | Returns a string to be included at the end of XML output for a particular record. (just inside the closing tag). | 1.2.7 |} ====Valuelist Customization==== {| class="listing listing2" ! Name ! Description ! Version |- | [[valuelist__valuelistname]] | Defines a valuelist named ''valuelistname''. | 0.7 |} ====Importing Records==== {| class="listing listing2" ! Name ! Description ! Version |- | [[__import__filtername]] | Defines an import filter to named ''filtername'' which is used to import records into the table. | 0.7 |} RSS,Feeds,delegate classes, triggers en 0 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 Drag_and_Drop_Reordering_of_Relationships 39 Drag_and_Drop_Reordering_of_Relationships ==Drag and Drop Reordering of Related Records in Xataface== One powerful aspect of Xataface is its abstraction of relationships between tables. Once you define a relationship users can browse related records, add new and existing related records, and delete related records to or from the relationship. For example, suppose you have a ''people'' table and a ''publications'', you could define a relationship from ''people'' to ''publications'' to identify publications that belong to a particular person. The table's might look something like: ===people table=== {| class="listing listing2" ! person_id ! person_name |- | 1 | John Smith |- | 2 | Ben Stein |- | 3 | Harley Davidson |- | 4 | Trevor Linden |} ===publications table=== {| class="listing listing2" ! publication_id ! owner_id ! pub_title |- | 1 | 2 | Introduction to widgetry |- | 2 | 2 | Intermediate Widgetry |- | 3 | 2 | Advanced Widgetry |- | 4 | 3 | How to play the violin |} See http://xataface.com/documentation/tutorial/getting_started/relationships for an introduction to relationships in Xataface, and how to define them. Our relationship definition in the ''people'' table's [[relationships.ini file]] might look something like: <code> [my_pubications] publications.owner_id="$person_id" </code> This indicates that any publication whose ''owner_id'' column matches the current ''people'' record's ''person_id'' field is considered part of the relationship. Using our example data above, this would mean that Ben Stein's ''my_publications'' relationship would contain 3 records: "Introduction to Widgetry", "Intermediate Widgetry", and "Advanced Widgetry". In our Xataface application this means that in the "Details" tab for the "Ben Stein" record, we would see a sub-tab ''My Publications'' which would contain a list of Ben Stein's publications. ===Adding Publication Order=== Now that we have our relationship, what if Ben Stein wants his publications to appear in a particular order whenever they are displayed to the user. Xataface allows us to specify an "order" column for our relationship, which will cause the related records to be orderable by drag and drop (if the user has appropriate permissions). # Add a field to the ''publications'' table named "pub_order" # Change the relationship definition in the people table's [[relationships.ini file]] to tell Xataface to use the pub_order field for sorting:<code> [my_pubications] publications.owner_id="$person_id" metafields:order="pub_order" </code> Now load up your application and navigate to the "My Publications" tab for the "Ben Stein" record. Now you're able to drag and drop rows in your application to reorder them. ===Permission to Reorder Records=== Only users who have been assigned the ''reorder_related_records'' permission for a record's relationship are allowed to reorder records of that relationship. By default the ''EDIT'' role contains this permission, as does any role that permits the user to edit the parent record of the relationship. The ''READ ONLY'' role does not contain this permission. If you want to explicitly deny this permission for all relationships in a record, you can simply set this permission to 0 in the associated role within your application's [[permissions.ini file]]: <code> [MY ROLE] reorder_related_records=0 </code> For more information about permssions see: * [[permissions.ini file|The Permissions.ini file reference]] * [http://xataface.com/documentation/tutorial/getting_started/permissions Introduction to Permissions] ===Loading Related Records using the Xataface API=== The ordering that is set via this drag and drop method is also honoured by the Xataface API when fetching related records. You can load related records using the [http://dataface.weblite.ca/getRelatedRecordObjects getRelatedRecordObjects] method of the [http://dataface.weblite.ca/Dataface_Record Dataface_Record] class. E.g. <code> $benStein = df_get_record('people', array('person_id'=>2)); $pubs = $benStein->getRelatedRecordObjects('my_publications'); foreach ($pubs as $pub){ echo $pub->val('pub_title').'<br/>'; } </code> This will list up to the first 30 publications of Ben stein in the order prescribed by our drag and drop ordering scheme. en 0 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 encryption 29 encryption ==encryption [[fields.ini file]] directive== The '''encryption''' directive is meant to be used on password fields only. It specifies that a certain type of encryption is to be used in the storing of values in this field. For example, many PHP/MySQL applications use MD5 encryption to store their passwords. If you want your Xataface application to be able to use the same users tables, then you'll need to specify the '''encryption''' directive for the password field. ===Possible Values=== {| class="listing listing2" |- ! Value ! Meaning ! Version |- | md5 | MD5 encryption | 0.6 |- | sha1 | SHA1 encryption | 1.0 |- | encrypt | MySQL encrypt function | 1.0 |- | password | MySQL password encryption | 1.0 |} ===E.g. in the users table [[fields.ini file]]=== <code> [password] encryption=md5 </code> en 0 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 fieldgroup_template 51 fieldgroup_template ==Using a custom template for a field group on the edit form== [[toc]] Xataface allows you to partition your fields into ''groups'' so that similar fields are grouped together on the edit form. The default layout of the fields remains simply vertical, but you can customize this layout (on a per-group basis) by creating a custom template and then assigning this template to the field group with the ''template'' directive. ===Example=== For example, in your [[fields.ini file]] if you wanted to group your address fields together you might have: <code> [fieldgroup:address] label="Address Information" template="AddressInformationGroup.html" [address_1] group=address [city] group=address [state] group=address </code> Then you would add the a template named ''AddressInformationGroup.html'' to your application's ''templates'' directory to display how the fields are laid out: <code> <table width="100%"> <tr><th>Address 1:</th> <td>{$elements.address_1.html}</td> <th>City:</th> <td>{$elements.city.html}</td> <th>State:</th> <td>{$elements.state.html}</td> </tr> </table> </code> This would display all of the fields in this group in a single row (horizontally) instead of vertically. Note that this is an over-simplified example that doesn't take account for display error messages, required notices, grouped fields, and other information that you can obtain from the {$elements} array. en 0 fieldname__default 133 fieldname__default Delegate Class Method Return to [[Delegate class methods]] [[toc]] ===Synopsis=== Xataface allows you to pre-populate any particular field in a table by adding a fieldname__default method to the table's delegate class of the form: <code> function fieldname__default(){ return value; }</code> Returns the default value for the field fieldname. New record forms will be prepopulated with this value. ===Examples=== <code> function minimum_bid__default(){ return 100; }</code> <code> function mydatecol__default(){ return date('Y-m-d'); }</code> <code> function owner_id__default(){ $auth =& Dataface_AuthenticationTool::getInstance(); $user =& $auth->getLoggedInUser(); if ( isset($user) ) return $user->val('userid'); return null; }</code> ===See Also=== * [http://xataface.com/forum/viewtopic.php?t=5028 Pre-entered Data] (forum thread) - setting defaults field values on general fields using the fieldname__default delegate class function * [http://xataface.com/forum/viewtopic.php?t=4004 How to initialize a Date field to today's date?] (forum thread) - alternate methods to use specifically with a date/time field * [http://xataface.com/forum/viewtopic.php?t=3988 Setting default select setting from users table] (forum thread) - solution to populate the current user default, initialize, populate, pre-populate, delegate class default en fieldname__permissions 53 fieldname__permissions ==fieldname__permissions() method== [[toc]] The fieldname__permissions() methods will allow you to define custom permissions on a particular field in the [[delegate class]]. For example to specify permissions on a field named ''foo'' you would define the ''foo__permissions()'' method, and to define permissions on a field named ''role'' you would define the ''role__permissions()'' method. ==Example #1== (Note this example needs to be refined to be more clear) <code> function approval_level__permissions(&$record){ return array('edit'=>0); //this is will merge with what the permissions for the normal record } </code> Here we are targeting the ''approval_level'' field of the [[delegate class]]. The permissions method takes a return value an array of permissions. So for example: <code> $permissions['new'] = 0; $permissions['edit'] = 0; </code> Would be an example of an array of permissions which the key being the permission name and the value being a boolean to specify whether they have (1) or don't (0) have permissions to that field. We don't have to specify a complete array of permissions (ie. permission of edit, new, readonly, etc, etc), but rather only the ones we want specifically. The reason being that the permissions array in the return value gets merged with the permissions that this record normally gets from the record permissions. So if the record normally gives the permissions new=0, edit=1. Then the return value from approval_level will merge with the original permissions to produce an array like this: <code> $permissions['new'] = 0; $permissions['edit'] = 1; </code> === Also See: === * [[How_to_granulate_permissions_on_each_field]] * [[__field__permissions]] en 0 fieldname__validate 94 fieldname__validate Delegate Class Method Return to [[Delegate class methods]] [[toc]] ===Synopsis=== Xataface allows you to add validation on any particular field in table by adding a fieldname__validate method to the table's delegate class of the form: <code> function myfield__validate(&$record, $value, &$params){ if ( $value != 'Steve' ){ $params['message'] = 'Sorry you must enter "Steve"'; return false; } return true; } </code> ===Parameters=== * &$record : A [http://dataface.weblite.ca/Dataface_Record Dataface_Record] object encapsulating the record we are validating. Note that the values of this object correspond with the submitted values from the form, and not necessarily the actual values of the record in the database. * $value : The value that is being inserted. * &$params : An output array that can be used to pass back a message if validation fails. You would set this array's 'message' parameter to be a message. ===Returns=== Returns a boolean value. True if the value is ok and false if validation failed. ===See Also=== * [[validators]] - For simple validation rules you can use the [[validators|validator:VALIDATOR_NAME]] directive of the [[fields.ini file]]. * [http://xataface.com/documentation/tutorial/getting_started/validation Form Validation] - Section on form validation in the Getting Started tutorial. validate, validation, delegate class validation, custom validator en 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 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 field__pullValue 104 field__pullValue delegate class method [[toc]] The field__pullValue() delegate class method can be used to transform database from the database for use in an edit/new record form. Sometimes it is the case that we want users to be able to work with data differently than it is stored in the database. This method should always be accompanied by a corresponding [[field__pushValue]] method which performs the inverse operation and is used to transform the value in an edit form into a format that can be stored in the database. ===Example=== Given a field ''start_ip'' that stores an IP address in the database as an unsigned INT, we want to be able to work with the data on the edit form in a friendlier format - the standard IP address dot notation, so we define pullValue and pushValue methods for the field in the table's delegate class. <code> 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; } } </code> ==References== * [[Delegate class methods]] * [[Application Delegate Class]] * [[http://dataface.weblite.ca/Dataface_Record Dataface_Record API docs] * [http://xataface.com/documentation/how-to/how-to-define-custom-serialization-for-fields How to define custom serialization for fields] - A how-to document. pushValue, pullValue en filter 27 filter ==The filter attribute of the [[fields.ini file]]== The filter attribute with a value of 1 specifies that a field should be used as a filter field in list view. In list view, any filter fields will provide a select list with all of the possible values in that field. Selecting one of the items in this list will filter the results to only show records of that value. ===Example 1: Year, Make, Model=== The Fuel Economy Database has three fields with filter=1 : Year, Make, and Model. I.e., in their fields.ini file we have something like: <code> [Year] filter=1 [Make] filter=1 [Model] filter=1 </code> This causes 3 select lists to appear in list view. See the application [http://fueleconomydb.com/index.php?-action=list here] and notice the select lists for Year, Make, and Model just above the list of results. If you are filtering on a field where an ID is stored in the DB but you are using a vocabulary to associate it with a value, then it will still be sorted on the ID. If you want to sort on value then you should add a [[Grafted fields|grafted field]] with the value using the __sql__ directive of the fields.ini file, then use that grafted field as your filter field, like the following: <code> __sql__ = "select a.*, b.foo_name from a left join b on a.foo_id=b.foo_id" [foo_name] filter=1 </code> en 0 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 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 getFeed 42 getFeed ==getFeed() Delegate Class Method== [[toc]] ===Synopsis:=== The getFeed() method of a table [[Delegate class methods|delegate class]] or [[Application Delegate Class|application delegate class]] returns an associative array of parameters to configure the [[Introduction_to_RSS_Feeds_in_Xataface|RSS feed]] for a particular table . An RSS feed consists of the following components: # '''title''' - The title of the RSS feed as it should appear in the subscribers' feed list. # '''description''' - Describes the RSS feed. # '''link''' - A link to the RSS feed # '''syndicationURL''' - The URL to this RSS feed's site. ===Parameters=== # '''array''' $query - The HTTP query. Contains information like the current table, current action, and search parameters. This allows you to customize your RSS feed depending on the user's query parameters. ===Return Value=== The getFeed() method returns an associative array with the components of the RSS feed. This array does not need to contain all possible keys, or even any keys. Any keys that are omitted will simply use default values in the RSS feed. The array may contain the following keys: {| class="listing listing2" ! Name ! Description ! Version |- | title | The title for the RSS feed. If this omitted, it will try to use the ''title'' directive of the ''[_feed]'' section of the [[conf.ini file]]. Failing that, it will try to generate an appropriate title for the feed depending on the current query. | 1.0 |- | description | A Description for this RSS feed. If this is omitted, it will try to use the ''description'' directive of the ''[_feed]'' section of the [[conf.ini file]]. | 1.0 |- | link | A link to the source page of the RSS feed. If this is omitted, it will try to use the ''link'' directive of the ''[_feed]'' section of the [[conf.ini file]]. | 1.0 |- | syndicationURL | A link to the source page of the RSS feed. If this is omitted, it will try to use the ''syndicationURL'' directive of the ''[_feed]'' section of the [[conf.ini file]]. | 1.0 |} ===Example=== <code> function getFeed(&$query){ return array( 'title' => "RSS feed for the ".$query['-table']." table.", 'description' => "News and updates for automobiles", 'link' => df_absolute_url(DATAFACE_SITE_HREF), 'syndicationURL' => df_absolute_url(DATAFACE_SITE_HREF) ); } </code> '''Note that RSS feeds will work perfectly well without defining this method. This just allows you to customize one or more parameters of the RSS feed'''. ===See Also:=== * '''[[getFeedItem]]''' - A delegate class method available to both the [[Delegate class methods|table delegate classes]] to configure parameters for the particular items of the RSS feed. * '''[[getRelatedFeed]]''' - A [[Delegate class methods|delegate class method]] available to both the [[Application Delegate Class|application delegate class]] and the [[Delegate class methods|table delegate classes]] to configure the [[Introduction to RSS Feeds in Xataface|RSS feed]] for a related records list. * '''[[getRSSDescription]]''' - A delegate class method to override the description that appears for a particular record in an RSS feed. (The same as the ''description'' parameter of the [[getFeedItem]] method. * '''[[Introduction to RSS Feeds in Xataface]]''' - An overview of Xataface's RSS feed support. en 0 getFeedItem 41 getFeedItem ==getFeedItem() Delegate Class Method== [[toc]] ===Synopsis:=== The getFeedItem() method of a table [[Delegate class methods|delegate class]] returns an associative array of parameters for a record as it should appear as part of an [[Introduction_to_RSS_Feeds_in_Xataface|RSS feed]]. An RSS feed item consists of the following components: # '''title''' - The title of the record as it appears in the RSS feed. # '''description''' - The description of the record for the RSS feed. This is really the body of the RSS feed item. # '''link''' - The linkback URL if users want to know more about the record. # '''date''' - The date that the record was posted/modified. # '''author''' - The name of the person who posted this record. # '''source''' - URL to the site where record originated from. ===Parameters=== # '''Dataface_Record''' &$record - The record that is being represented in an RSS feed. ===Return Value=== The getFeedItem() method returns an associative array with the components of the RSS feed. This array does not need to contain all possible keys, or even any keys. Any keys that are omitted will simply use default values in the RSS feed. The array may contain the following keys: {| class="listing listing2" ! Name ! Description ! Version |- | title | The record title as it appears in RSS feeds. If this is omitted, the RSS feed will simply use the output of [http://dataface.weblite.ca/Dataface_Record Dataface_Record's] [http://dataface.weblite.ca/getTitle getTitle()] method. | 1.0 |- | description | The record description. This is used in the main body of the RSS feed. If this is omitted, the RSS feed will use an HTML table that shows all of the field data in the record. This value can also be overridden using the [[getRSSDescription]] method of the delegate class. | 1.0 |- | link | The URL to this record. If this is omitted it just points to the ''view'' tab for this record. However you can direct it anywhere you like. When the user clicks on the "More Info" link in his RSS reader it will direct him to this link. | 1.0 |- | date | The date that this record was posted or last modified. This is the date that an RSS reader will use to decide if it has already loaded the record yet. If this is omitted it will try the [http://dataface.weblite.ca/Dataface_Record Dataface_Record's] [http://dataface.weblite.ca/getLastModified getLastModified()] method to obtain the last modified date of the record. Failing that, it will use [http://dataface.weblite.ca/Dataface_Record Dataface_Record's] [http://dataface.weblite.ca/getCreated getCreated()] method to try to obtain the creation date of the record. This date should be a unix timestamp. | 1.0 |- | author | The name of the user who posted this record. If this is omitted, then it will try to use [http://dataface.weblite.ca/Dataface_Record Dataface_Record's] [http://dataface.weblite.ca/getCreator getCreator()] method. Failing that, it will use the value of the ''default_author'' parameter in the ''[_feed]'' section of the [[conf.ini file]]. If that is not defined, then it simply uses the string "Site Administrator". | 1.0 |- | source | The source URL where the feed is to have originated. If none is specified, then it will use the value of the ''source'' parameter in the ''[_feed]'' section of the [[conf.ini file]]. Failing that, it will simply use the URL to the application. Note that you can alternatively define this value using the [[getFeedSource]] method. | 1.0 |} ===Example=== <code> function getFeedItem(&$record){ return array( 'title' => "News Item: ".$record->getTitle(), 'description' => $record->display('News Body'), 'link' => $record->getPublicLink(), 'date' => strtotime($record->val('last_modified')), 'author' => $record->val('posted_by'), 'source' => 'http://www.example.com' ); } </code> '''Note that RSS feeds will work perfectly well without defining this method. This just allows you to customize one or more parameters of the RSS feed'''. ===See Also:=== * '''[[getFeed]]''' - A delegate class method available to both the [[Application Delegate Class]] and the [[Delegate class methods|table delegate classes]] to configure the RSS feed as a whole (not just for an individual item in the RSS feed. * '''[[getRelatedFeed]]''' - A [[Delegate class methods|delegate class method]] available to both the [[Application Delegate Class|application delegate class]] and the [[Delegate class methods|table delegate classes]] to configure the [[Introduction to RSS Feeds in Xataface|RSS feed]] for a related records list. * '''[[getRSSDescription]]''' - A delegate class method to override the description that appears for a particular record in an RSS feed. (The same as the ''description'' parameter of the [[getFeedItem]] method. * '''[[Introduction to RSS Feeds in Xataface]]''' - An overview of Xataface's RSS feed support. en 0 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 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