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> </nowiki>[[Image:http://xataface.com/documentation/tutorial/getting_started/new_database.gif]] <nowiki> </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> </nowiki>[[Image:http://xataface.com/documentation/tutorial/getting_started/create_table.gif]] <nowiki> </nowiki> Then click 'Go'. # This should bring up a form to specify the fields for the course table: <nowiki> </nowiki>[[Image:http://xataface.com/documentation/tutorial/getting_started/course-table-def-small.gif]] <nowiki> </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> </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> </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>OK, I guess some explanations are in order. The first line imports the all of the public functions for dataface from the dataface-public-api.php file. The second line initializes the application for the current directory and specifies the URL to the dataface installation. The third line obtains an instance to the Application object - the core of your Dataface application. The fourth line simply displays the application.</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>Explanations:There are 2 sections in this INI file: '_database', and '_tables'. The '_database' section specifies the database connection information for the MySQL database. The '_tables' section specifies which tables will be included in the navigation menu for the application.</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> </nowiki>[[Image:http://xataface.com/documentation/tutorial/getting_started/basic-app-dir-structure-manual-1.gif]]<nowiki> Note, however, that there is also an .htaccess file that is hidden from this image.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.</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> </nowiki>[[Image:http://xataface.com/documentation/tutorial/getting_started/basic-application-1.gif]] ===Download source files=== [[File:http://xataface.com/documentation/tutorial/getting_started/facultyofwidgetry-4-tar.gz|Download the source files]] for this application at a tar.gz archive. These files reflect the state of the application at this point of the tutorial. As later sections make changes to the application you will be able to download those versions also. htaccess first application installation en GettingStarted:Installation 73 Installation ==Installation== Download and installation instructions for the Web Lite framework. Xataface is a 100% PHP Framework that comes with all dependencies as part of the installation. The framework itself lives inside a single directory that should be placed inside the document root of your web server so that it can be accessed from the web. You can install a single copy of Xataface to be used by multiple applications on your web server. Each application just "requires" the key files from the Web Lite framework. ===Downloading=== # Go to the Xataface Sourceforge project file releases page # Download the latest file release. ===Installing=== # Unpack the gzipped tar archive that you downloaded somewhere in your web server's document root (i.e., make sure that the 'dataface' directory is in a web-accessible location). # Make the dataface/Dataface/templates_c directory writable by the web server. An unsafe way to do this is to chmod 777 Dataface/templates_c But it would be better to just give write access to the web server user. # Confirm that the installation worked by pointing the web browser to http://yourdomain.com/path/to/dataface/dataface_info.php . If it worked OK, you should receive a web page that says "Dataface is installed correctly", along with some basic instructions for creating a Xataface Application. (Note: Sometimes this page will give you a false positive. i.e., it may say the installation worked but then your Xataface application receives errors. Check the troubleshooting section below to deal with these issues). ===Troubleshooting=== If your installation is not going as planned, don't panic. There is a possiblity that your system has a slightly different configuration and you have to make some small adjustments to make the installation work. The general procedure for troubleshooting the installation is as follows: # Check the [[Troubleshooting]] page. # Look through the [http://xataface.com/forum forum] to see if others have experienced the same thing. # Post your question in the forum if you can't find the answer already. installation troubleshooting downloading en GettingStarted:Introduction 71 Introduction Web Lite is a simple framework for building data-driven web applications in PHP and MySQL. This section introduces some of the concepts and applications of Dataface. To fully understand what Xataface is, we must first define a few key terms: '''Framework''' - A set of software routines that provide a foundation structure for an application. Frameworks take the tedium out of writing an application from scratch. (From Answers.com) '''Data-driven design'''- Designing an application around the data that it will store. Xataface is a ''Framework'' in the sense that it is a set of classes and libraries that take the tedium out of writing web applications. It provides a simple web interface to a MySQL database enabling users to update, delete, and find data in the underlying database. The interface is targeted at secretaries and end-users as opposed to database administrators. Xataface enables ''data-driven design'' because it allows developers to develop web sites by first designing the database that will be used to store the data on the website, and then design the pages used to display the data. The developer can focus on the data because he or she does not have to worry about having to build forms to update the data. If the requirements of the application change, the developer can simply add a field to the database table and all associated web forms will be updated automatically (because they are all dynamically generated using the database schema). ===Requirements=== * [http://php.net PHP] >= 4.3 * [http://mysql.com MySQL] >= 3.2.3 ===Key Technologies=== * [http://pear.php.net PEAR class libraries] (HTML_QuickForm, etc...) * [http://smarty.net Smarty Templating Engine] * [http://plone.org Plone] Javascript and CSS style sheets ===Development Procedures=== # Identify the data that will need to be stored for a web site. ##[[Image:http://xataface.com/documentation/tutorial/getting_started/er-diagram.png]] # Design the database using your favorite database administration program (e.g., PHPMyAdmin) ##[[Image:http://xataface.com/documentation/tutorial/getting_started/phpMyAdmin-1-small.gif]] # Tell Xataface some DB connection info, and voila! You have an application: ##[[Image:http://xataface.com/documentation/tutorial/getting_started/new-record-form-1-small.gif]] ===Where to go from here=== This tutorial will teach you the basics of Xataface and how to construct a simple application using the Xataface. After reading this tutorial you will be ready to tackle some medium to large web sites with the help of the Xataface reference documentation. You are also encouraged to mail the [http://xataface.com/forum Xataface forum] if you have questions. introduction requirements getting started en GettingStarted:relationships 78 Relationships ==Relationships== Xataface allows you to define relationships between tables using the relationships.ini file. Xataface applications without relationships between tables can be quite boring. In our FacultyOfWidgetry application, we have implicitly defined a relationship between the Program table and the Course table by adding a ProgramID field to the Course table. In the previous section we saw how to configure this relationship from the context of a 'Course' by adding a select list to the Course table form to select the Program that the Course belongs to. From the 'Program' side it is a little bit more complicated. There are no fields in the 'Program' table that can be edited to add a 'Course' to the list of courses in a 'Program', and it would be highly inconvenient to have to edit a 'Course' record in order to add the course to a 'Program'. What we want is a sort of 'Add Course' button to add a course to a 'Program'. ===Concepts, Definitions, and Terminology=== Before we can delve into examples, it will help to go over some of the concepts and terminology involved in relationships using Xataface. Xataface relationships are always defined in a one-way fashion from the point of view of one table. For example, if you define a one-to-many relationship from the 'Program' table to the 'Course' table, the mirror (many-to-one) relationship from 'Course' to 'Program' is not automatically created. This method of defining relationships allows us to unambiguously refer to the source and destination tables of a relationship. '''Definition 1:''' The ''source table'' of a relationship is the table on which a relationship is defined. For example if we define a relationship named 'Courses' on the 'Program' table to associate courses in a given program, then the 'Program' table would be considered the source table of the relationship, and the 'Course' table would be a destination table of the relationship. '''Definition 2:''' The ''destination table'' of a relationship a table from which related records are selected. There may be multiple destination tables in a given relationship but only one source table. If there are multiple destination tables, then one of these tables is designated as the domain table and the remaining destination tables are called join tables. '''Definition 3:''' A ''domain table'' is a destination table which stores the object of the relationship. For example if we define a many-to-many relationship between the 'Program' table and the 'Course' table, (i.e., each program can contain multiple courses and each course can be part of multiple programs), then we would need to add a join table to map 'Course' records to 'Program' records. Let's call this table 'ProgramCourses'. Each record of the 'ProgramCourses' table would contain a 2 fields: a 'ProgramID' field (to reference the program) and a 'CourseID' field to reference the course. If we define the relationship from the point of view of a 'Program' then the 'Program' table would be the source table, the 'ProgramCourses' table would be the join table, and the 'Course' table would be the domain table. Don't worry if these definitions and terms aren't clear at this point. Use this section as a reference for when you run across the terms later in the tutorial. ===Defining a relationship=== To define a relationship in Xataface, all you need to do is tell Xataface how to select the related records using SQL. Xataface will be able to figure out how to add/remove records to the relationship from this information. This information is defined inside a the 'relationships.ini' file inside the configuration folder for the table. ====Example 1: Adding a 'Courses' relationship to the 'Program' table==== We want to be able to associate multiple courses with each program. We do this by defining a relationship on the 'Program' table as follows: # Add a file named 'relationships.ini' to the 'Program' table's configuration folder (i.e., tables/Program/relationships.ini). Your application's directory structure should now look like:<nowiki> </nowiki>[[Image:http://xataface.com/documentation/tutorial/getting_started/directory-structure-relationships.gif]]<nowiki> </nowiki>Notice, in particular the addition of the 'relationships.ini' file in the 'Program' directory. # Add the following to the 'relationships.ini' file:<code> [Courses] Course.ProgramID = "$ProgramID" </code> This little snippet defines a relationship named 'Courses' on the 'Program' table. 'Program' is the source table. 'Course' is the destination table. There are no join tables because this is only a one-to-many relationship. You may be wondering what the $ProgramID means. This is a variable that represents the value of the 'ProgramID' field in the source record. This relationship specifies that courses whose 'ProgramID' field matches the value of the 'ProgramID' field in the source record, are related to the source record. The english language makes this seem more difficult and complex than it really is. Let's check out our changes. Since we have defined the relationship on the 'Program' table, we will click on the 'Program' link in the navigation menu: [[Image:http://xataface.com/documentation/tutorial/getting_started/course-relationship-defined-1.gif]] Notice that there is now a 'course' tab at the top of the page. Click on this tab to see the courses that are related to this Program (as defined by our 'Courses' relationship). If it says that "No records matched the request" or something to that effect, then you don't have any Course records in the relationship yet. Just click the "Add New Courses Record" button in the upper left to add a course. If there are courses in the relationship, then the Courses tab will look something like: [[Image:http://xataface.com/documentation/tutorial/getting_started/courses-related-records.gif]] Currently there is only one course in the program, but we can add more. If you click on the "Add New Courses" button in the upper left, you will be presented with a new course form that will allow you to add a new course in this Program. ===Example 2: Making the 'Courses' relationship a Many-to-Many relationship=== Example 1 shows how Xataface can handle a one-to-many relationship. Now we will alter the database a little bit and turn this into a many-to-many relationship. # Add a table named 'ProgramCourses' to the database. The SQL table definition for this table should be something like:<code> CREATE TABLE `ProgramCourses` ( `ProgramID` INT( 11 ) NOT NULL , `CourseID` INT( 11 ) NOT NULL , PRIMARY KEY ( `ProgramID` , `CourseID` ) ) </code><nowiki>Note that it is important for ALL of your tables to have Primary keys. If a table is missing its primary keys, some strange behavior may occur with relationships involving that table. The above defined table will serve as a join table between 'Program' and 'Course' </nowiki> # Since this is now going to be a many-to-many relationship, we no longer need the 'ProgramID' field in the 'Course' table. (Do not confuse this with the ProgramID field in the 'Program' table. That field is important and needed.). Before removing this field, we will transfer the information across so that the existing relationships are maintained. The following SQL query will effectively all of the old one-to-many relationships into equivalent many-to-many relationships:<code> INSERT INTO ProgramCourses( ProgramID, CourseID ) SELECT ProgramID, CourseID FROM Course </code><nowiki> And now we can remove the 'ProgramID' field from the 'Course' table. ALTER TABLE Course DROP ProgramID</nowiki> # Finally, we will need to modify the relationship definition in the relationships.ini file of the 'Program' table:<code> [Courses] Course.CourseID = ProgramCourses.CourseID ProgramCourses.ProgramID = "$ProgramID" </code><nowiki> This means that all courses for which a (ProgramID, CourseID) pair matches the CourseID of the course and the ProgramID of the source Program record are included in the relationship.</nowiki> # Now we can check our application for changes. Go to the 'Program' table in your application (using your web browser) and click on the 'courses' tab once again:<nowiki> </nowiki>[[Image:http://xataface.com/documentation/tutorial/getting_started/multi-relationship.gif]]<nowiki> This looks almost the same as before. Notice, however that now there is an "Add Existing Courses Record" button at the top. This is because with a many-to-many relationship, you are able to add related records in 2 ways:</nowiki> ## Adding a completely new record that did not exist before. ## Selecting a record that already exists and adding it to the relationship. ===Example 3: Defining Relationships using SQL=== The previous examples used a simple INI file syntax to define relationships. However, some people may be more comfortable defining their relationships using SQL. This is also possible. Let's look at the relationships.ini file from example 1:<code> [Courses] Course.ProgramID = "$ProgramID" </code> This also could have been defined as follows:<code> [Courses] __sql__ = "SELECT * FROM Course WHERE ProgramID='$ProgramID'" </code> '''Note: Make sure you use two underscores on either side of 'sql' in the above example. It should be '__sql__' not '_sql_'.''' The two syntaxes are equivalent. In fact, the former will be converted into the later by Xataface behind the scenes. Now let's look at example 2's relationships.ini file:<code> [Courses] Course.CourseID = ProgramCourses.CourseID ProgramCourses.ProgramID = "$ProgramID" </code> This could have been written as:<code> [Courses] __sql__ = "SELECT * FROM ProgramCourses, Course WHERE Course.CourseID = ProgramCourses.CourseID AND ProgramCourses.ProgramID = '$ProgramID'" </code> The two are equivalent. This example, however, shows how defining a relationship using SQL can be beneficial. The above SQL query will work but it can be done better using Joins as follows:<code> [Courses] __sql__ = "SELECT * FROM ProgramCourses pc INNER JOIN Course c ON pc.CourseID = c.CourseID WHERE pc.ProgramID = '$ProgramID'" </code> All of these 3 methods will produce the same results, but the last one will probably give a little bit better performance. ===Relationship Restrictions=== Xataface has built-in logic to figure out how to add new and existing records to relationships that you define, as long as your relationships obey a few guidelines. # All tables must have a Primary key # The WHERE clause of your SQL definition for the relationship must contain only '=' comparisons, and 'AND' conjunctions. i.e., it cannot receive an 'OR' conjunction, nor can comparisons be done using '>', or '<'. This is because given 'AND' and '=' conjunctions it is easy for Xataface to be able to add records that will satisfy the relationship. If an 'OR' conjunction is used, it makes it ambiguous (though this will probably be corrected in future Xataface releases. ===Download Source Files=== [http://xataface.com/documentation/tutorial/getting_started/facultyofwidgetry-8-tar.gz Download the source files for this application as a tar.gz archive] relationships en GettingStarted:triggers 81 Triggers ==Triggers== Triggers are methods that can be defined to carry out custom behaviors when certain events occur in the application (e.g., when records are saved, inserted, or deleted). Triggers are generally regarded as one of the more advanced features of database applications. Despite the "advanced" status of triggers, however, they are very simple to use and can be leveraged by Xataface developers to add powerful functionality to their applications. So what can you do with a trigger? * Send a confirmation email every time a new record is inserted into a table. * Delete records related to a record that is being deleted (to maintain the consistency of the database). * Add custom logging functionality. * Add extra permissions or validation rules (although these are probably better handled with the validation framework). You can really do just about anything you want with a trigger. A trigger is essentially just a custom PHP method that is called by Xataface when certain events occur. ===What triggers are available?=== As of version 0.5.3 Xataface supports the following triggers: * '''beforeSave''' : called just before a record is saved (either inserted or updated). * '''afterSave''' : called just after a record is saved (either inserted or updated). * '''beforeInsert''' : called just before a record is inserted. * '''afterInsert''' : called just after a record is inserted. * '''beforeUpdate''' : called just before a record is updated. * '''afterUpdate''' : called just after a record is updated. * '''beforeDelete''' : called just before a record is deleted. * '''afterDelete''' : called just after a record is deleted. * '''beforeAddRelatedRecord''' : called just before a related record (new or existing) is added to a relationship. * '''afterAddRelatedRecord''' : called just after a related record (new or existing) is added to a relationship. * '''beforeAddNewRelatedRecord''' : called just before a new related record is added. * '''afterAddNewRelatedRecord''' : called just after a new related record is added. * '''beforeAddExistingRelatedRecord''' : called just before an existing related record is added. * '''afterAddExistingRelatedRecord''' : called just after an existing related record is added. ===How do you define a trigger?=== Triggers are always defined as methods of the delegate class for a table. As an example, suppose we wanted to add a trigger to send a the administrator a notification email every time a new record is inserted into the 'Course' table. The steps would be as follows: # Create a delegate class for the 'Course' table (if one does not already exist) by creating a file named 'Course.php' inside the 'tables/Course' directory. # Add the following to the Delegate class file to make it a valid delegate class:<code><? class tables_Course {} </code> # Okay, we want our trigger to be called every time a record is inserted. There are 2 possible triggers that can be defined, then:<nowiki> <ul> <li>beforeInsert</li> <li>afterInsert</li> </ul> In this case it is probably more appropriate to define the afterInsert trigger because we really only want to send the notification email after the insert has successfully taken place. Therefore, we will define the afterInsert() method in our delegate class as follows: </nowiki><code> <? class tables_Course { .... /** * Trigger that is called after Course record is inserted. * @param $record Dataface_Record object that has just been inserted. */ function afterInsert(&$record){ mail('admin_email@yourdomain.com','Subject Line', 'Message body'); } } </code> # That's all for now. The afterInsert() method defined above will automatically be called every time a record is inserted into the Course table. This method, as we have defined it, will send a notification email to the administrator email. ===Sending feedback to the user=== The above example sends the email without any feedback to the application's user of whether the email succeeded or not. When the user inserts a new Course he will only see that the record was succesfully saved, but no mention is made of the email. The following example does the same thing as the previous one, except that it sends a confirmation to the user when the email has been successfully sent: <code> function afterInsert(&$record){ $response =& Dataface_Application::getResponse(); // get reference to response array if ( mail('shannah@sfu.ca', 'Subject Line', 'Message Body') ){ $response['--msg'] .= "\nEmail sent to shannah@sfu.ca successfully."; } else { $response['--msg'] .= "\nMail could not be sent at this time."; } } </code> Now, when the user inserts a new record he will see a confirmation as follows: [[Image:http://framework.weblite.ca/documentation/tutorial/getting_started/trigger-after-insert-confirm.gif]] Notice that we used the Dataface_Application::getResponse() function to obtain a reference to the application's response array. The response array is just a global array that is shared by the entire application that allows you to pass information easily from one part of the application to another. The '--msg' index of array is where you can place text that you wish to have displayed to the user as a confirmation. '''Note''': It is important to use '=&' to assign the result of Dataface::getResponse() and not just '='. e.g.: <code> $response =& Dataface_Application::getResponse(); // correct! $response = Dataface_Application::getResponse(); // WRONG!! </code> This is because we need a reference to the response array, not a copy. That way when we assign a value to the '--msg' index it is applied to the actual response array and not a copy of it. ===Handling Errors=== The above method of sending messages to the user is useful for notifications and confirmations. However, in some cases you want to inform the user that an error occurred and cancel further operations. For example you may want to disallow a record to be inserted if a confirmation email cannot be sent. In this case we define the beforeInsert() trigger and return a PEAR_Error object if the email fails as follows: <code> <? class tables_Course { function beforeInsert(&$record){ $response =& Dataface_Application::getResponse(); if ( mail('shannah@sfu.ca', 'Notification', 'Your record was created')){ $response['--msg'] .= "\nEmail sent successfully to shannah@sfu.ca"; } else { return PEAR::raiseError( "Errors occurred while sending email. Record could not be inserted", DATAFACE_E_NOTICE ); } } } </code> This trigger is called just before a course record is inserted into the database. If the mail succeeds, then the user sees a success message. If it fails, on the other hand, the insert is cancelled, and the user will see a message as follows: [[Image:http://framework.weblite.ca/documentation/tutorial/getting_started/trigger-error.gif]] '''Note''': Notice the use of the DATAFACE_E_NOTICE constant as a second parameter for PEAR::raiseError(). This is important as without it Xataface will display a less user-friendly error message complete with stack trace. If the error is such that you want a complete stack trace, you can use the DATAFACE_E_ERROR constant instead. triggers, beforeSave, afterSave, beforeInsert, afterInsert,sending email en GettingStarted:using_first_app 75 Using Your First Application ==Using Your First Application== A Web Lite application, at its core, provides 4 standard operations: Add new records, edit existing records, delete records, and find records. This section gives a brief overview of how to use your first Dataface application. When you first create your Xataface application and there are no records in the database, the application will look quite plain. If you point your web browser to your newly created application it will look something like: [[Image:http://xataface.com/documentation/tutorial/getting_started/basic-application-1.gif]] You may be wondering why it says "No records matched your request" when you haven't even really made a request. This is because the 'default' request that is performed if no other request is specified is to show the first record from the first table in the navigation menu. Since there are no records, it is true that there are NO records matching the default request. So what can you do with this application anyways? Essentially there are 4 operations you will want to perform: # Create new records # Edit Existing records # Find records # Delete records ==Basic Navigation== The navigation tabs (aka Navigation menu) at the top left represent the tables in your database. You can navigate to any of the tables in this list by clicking on that table: [[Image:http://xataface.com/documentation/tutorial/getting_started/navmenu-1.gif]] There are 3 "views" associated with tables in the database: * '''Details''' - Shows the details of a single record in the table * '''List''' - Shows the records in the current "found set" as a list. (in a table). * '''Find''' - Allows users to find records matching certain criteria. You can toggle between these 3 views using the tabs at the top of the page: [[Image:http://xataface.com/documentation/tutorial/getting_started/basic-tabs-1.gif]] ===The "Found Set"=== Throughout this tutorial you will see the phrase "found set" an awful lot, so it is important to understand just what this means. A "found set" is the set of all records in the current table that match the current "find criteria". This begs the question, "what is 'find criteria'?". By default there is no find criteria. When you perform a search or a find on the current table, you add "find criteria" so that only the records satisfying these criteria will be included in the "found set". For example, if you click on the "find" tab, you will get a search form that allows you to search for records that match certain criteria. The "find" tab for the "Course" table in our application looks like: [[Image:http://xataface.com/documentation/tutorial/getting_started/find-form-1.gif]] If you type in "English" in the "Subject" field and click "Find", then the "found set" will consist of only records that contain the word "English" in their subject fields. On the top left of the application window there will always be a "Found" line that indicates how many records are currently in the found set. e.g., This indicates that there are 256 records in the current table (which is the 'Groups' table). There are currently only 225 records in the current "found set" (meaning that we have performed a "find" operation and it matched 225 of the records). It also indicates that the currently displayed record is record number 1 out of the 225 found records. ===The Actions Menu=== Just below the view tabs ('details', 'list', and 'find') there are a few buttons that allow you to perform actions such as create new records, clear find parameters (i.e. Show All), and delete records. [[Image:http://xataface.com/documentation/tutorial/getting_started/actions-menu-1.gif]] '''Descriptions:''' * '''new record''' - Creates a new record in the current table. * '''show all''' - Clears all find criteria on current table so that all records are shown. * '''delete''' - Deletes the current record in the table. * '''delete found records''' - Deletes all records in the current "found set". If no find criteria is specified this will delete all records in the table. ===Creating new records=== The basic FacultyOfWidgetry application that we created in the previous section isn't very interesting when it doesn't contain any records, so let's create some Program records. # Select the "Program" table by clicking on the "Program" option of the navigation menu. # Click "new record" in the actions menu (top left). # This will bring up a form to insert a new record that looks like: <nowiki> </nowiki>[[Image:http://xataface.com/documentation/tutorial/getting_started/new-record-1.gif]] # Fill in the form and click "Save". If everything went OK, you will see the same form again, but with a "success" message at the top of the page: <nowiki> </nowiki>[[Image:http://xataface.com/documentation/tutorial/getting_started/successfully-saved-1.gif]] ===Editing an existing record=== The "details" view allows you to view details or edit the current record. There should be at least 2 sub-tabs: 'View' and 'Edit'. If you click on the 'Edit' tab, you will be presented with a form to edit the record. The form is identical to the "create new record" form. ===Deleting records=== If the 'list' tab is selected, then you will see a button called 'delete found records' in the actions menu (just below the view tabs). Alternatively if the 'details' tab is selected, you will see a button called simply 'delete'. [[Image:http://xataface.com/documentation/tutorial/getting_started/actions-menu-1.gif]] Select "delete" to delete only the current record you are viewing in the "details" view. Select "delete found records" to delete all of the records in the current found set. In either case, you will be prompted to confirm your decision before the records are actually deleted. ===Interface Overview=== Xataface applications provide an intuitive and consistent interface throughout. The following screenshot contains a map of some comment interface components along with some explanations: [[Image:http://xataface.com/documentation/tutorial/getting_started/interface-schematic.png]] Other topics This short section is only intended to get you acquainted with the basics of Xataface applications. As your application becomes more complex with relationships and value-lists, there will be other usage scenarios of interest. "find form","edit form","delete record","user interface",ui,template,look and feel en GettingStarted:validation 79 Form Validation ==Form Validation== Xataface allows you to add validation rules to fields using the fields.ini file A common requirement for forms is to have some validation rules. Here are some example validation rules: * The Username field is required. * The Username must be between 6 and 16 characters long. * The password must have at least one letter and one digit. * The Email field must contain a valid email address. There is no end to the types of things that you will need to validate. Xataface takes care of most of this for you with both client-side (javascript) and server-side validation. All you have to do is define some validation rules in the fields.ini file. ===Example 1: Make 'Username' a required field=== <code> [Username] validators:required = true validators:required:message = "Username is required" </code> Placing the above inside the fields.ini file will cause the Username field to be a required field. ===Example 2: Username must be between 6 and 16 characters long=== For this rule we will use a regular expression. <code> [Username] validators:regex = "/^.{6,16}$/" validators:regex:message = "Username must be between 6 and 16 characters long" </code> ===Example 3: Email field must contain a valid email address=== <code> [Email] validators:email = true validators:regex:message = "Email must contain a valid email address" </code> ===Available validation rules=== Xataface uses the PEAR library HTML_Quickform for validation, so any of the validators available in this package will be available in Xataface. Some of the available validation rules include: * required * maxlength * rangelength * regex * email * emailorblank * lettersonly * alphanumeric * numeric * nopunctuation * nonzero ===Default validation rules=== There are certain validation rules that are automatically applied to fields of with certain characteristics. For example, any field designated NOT NULL in the SQL table definition will automatically be a 'required' field. At the time of this writing, that is the only 'default' validation rule applied, but more may be added in the future if their addition makes sense. form validation,required field,validation rules en GettingStarted:valuelists 77 Using Valuelists ==Using Value-lists== Value-lists serve as vocabularies that can be used for fields such as select lists, checkbox groups, and auto-complete fields. So far we have not used any enumerated fields such as select lists, checkbox groups, or auto-completion fields in our examples. This is because we are missing a key ingredient that is required by all of these widget types: a vocabulary. We need a way to define options for these fields. This is where 'valuelists' come into play. A valuelists is essentially a list of key-value pairs that can be used as a vocabulary in enumerated fields like checkbox groups, select lists, and auto-completion fields. Valuelists are defined in the valuelists.ini file in each table's configuration directory. ===Example 1: Use a select list for the Subject field in the Course table=== The "Subject" field in the "Course" table really shouldn't be a free-form field that will accept any value. The user should just be able to pick from a finite list of subjects in a select list. To make these changes we will follow these steps: # Create the configuration directory for the "Course" table if it does not exist yet. # Create a file named 'fields.ini' inside the Course table's configuration directory (i.e., tables/Course/fields.ini), if it does not already exist. # Create a file named 'valuelists.ini' inside the Course table's configuration directory (i.e., tables/Course/valuelists.ini) if it does not already exist. Your application directory structure should now look like:<nowiki> </nowiki>[[Image:http://xataface.com/documentation/tutorial/getting_started/application-structure-valuelists.gif]] # Edit the valuelists.ini file so that it looks like:<code> [Subjects] ENGL = English MATH = Math PHYS = Physics CHEM = Chemistry </code> This defines a valuelist named 'Subjects' with values {ENGL, MATH, PHYS, CHEM} and associated labels {English, Math, Physics, Chemistry}. The values (i.e., ENGL, MATH, etc..) represent what will be stored in the database, and the values is a user-friendly representation that will be displayed on the screen. # Now we edit the fields.ini file so that it looks like:<code> [Subject] widget:type = select vocabulary = Subjects </code> This tells Xataface that we want to use a select widget to edit the "Subject" field, and its values should be drawn from the "Subjects" valuelist. #Navigate to the "Course" table in our application and select "new record" from the "Actions to be performed menu" in the top left.<nowiki> </nowiki>[[Image:http://xataface.com/documentation/tutorial/getting_started/actions-menu-1.gif]]<nowiki> </nowiki>This will bring up a form to create a new Course record, so that we can see what the form looks like. It should look like:<nowiki> </nowiki>[[Image:http://xataface.com/documentation/tutorial/getting_started/new-course-form-1.gif]]<nowiki> </nowiki>Notice that the "Subject" field is represented by a select widget, its options are as follows:<nowiki> </nowiki>[[Image:http://xataface.com/documentation/tutorial/getting_started/course-subject-pulldown-1.gif]]<nowiki> </nowiki> And if you look at the HTML source code for this select list, it would look like:<code> <select class="default" id="Subject" name="Subject"> <option value="">Please Select...</option> <option value="ENGL">English</option> <option value="MATH">Math</option> <option value="PHYS">Physics</option> <option value="CHEM">Chemistry</option> </select> </code> ===Example 2: Using a checkbox group for the 'Subject' field=== In Example 1, we showed how to use a select list for the 'Subject' field in the 'Course' table. This is great if each course can only be one subject. But what if a course can be categorized in 2 subject areas. Then we will need a widget the allows you to select multiple items. Checkbox groups work well for this. Make a change to the 'fields.ini' file for the 'Course' table to change the widget:type attribute of the 'Subject' field to 'checkbox' as follows:<code> [Subject] widget:type = checkbox vocabulary = Subjects </code> Now load the form again and notice that the 'Subject' field is now represented by checkboxes. [[Image:http://xataface.com/documentation/tutorial/getting_started/checkbox-group-1.gif]] You may be wondering how we store multiple values in a single field. In this case Subject is treated as a 'repeat' field where each value is on a separate line. I.e., with the form above, if we clicked 'save' and checked the values stored in the database we would see:<code> PHYS CHEM </code> As the value in the 'Subject' field. Please note that if you are going to use a repeating field like this, you should make sure that the field is 'big' enough to store all of the values. E.g., I think my Subject field was a VARCHAR(64) (64 characters long), so the sum of the lengths of all of the values 'checked' for 'Subject' should be less than 64. ===Example 3: Dynamic Valuelists based on the results of SQL queries=== Example 1 & 2 demonstrated the basic idea of valuelists and how they can be used as values for select lists and checkbox groups. However defining valuelists "statically" inside the valuelists.ini file doesn't really seem to offer anything over using and ENUM or SET field in the MySQL database. In many cases we want the user to be able to choose from a number of options that are pulled from the database. For example, we may want the user to be able to specify the Program that a Course belongs to, using a pull-down list. Recall that when we created the 'Course' table we included a field named 'ProgramID' to store the ID number of the Program that this course belongs to. It would be unreasonable to expect the users of your application to remember the ID number of the Program to which the course belongs when they are filling in the 'Course' form. It would be much better if the user could choose the program from a list of available programs. Fortunately, this functionality is simple to add: # Add a valuelist named 'Programs' to the valuelists.ini file for the 'Course' table as follows:<code> [Programs] __sql__ = "SELECT ProgramID, ProgramName FROM Program ORDER BY ProgramName" </code> '''Note: Make sure you use two underscores on either side of 'sql' in the above example. It should be '__sql__' not '_sql_'.'''<nowiki></nowiki>This valuelist will be a list of the records in the 'Program' table in alphabetical order on the program name. Note that this query selects 2 columns. The first column is always taken to be the ID column of the value-list and the 2nd column (if specified) is the Name column of the valuelist. The ID column is what will actually be stored in the database, and the Name column is what will be shown to the user in place of the ID.<nowiki></nowiki> # Add a field definition for the ProgramID field in the fields.ini file of the 'Course' table as follows:<code> [ProgramID] widget:type = select vocabulary = Programs </code> Now we can load up our form and see what it looks like: [[Image:http://xataface.com/documentation/tutorial/getting_started/programid-select-list.gif]] We can see that the ProgramID field now appears with a select list of all of the programs in the database. The HTML code for the select list is:<code> <select class="default" id="ProgramID" name="ProgramID"> <option value="">Please Select...</option> <option value="2">Advanced Widgetry</option> <option value="1">Basic Widgetry</option> <option value="3">International Widgetry</option> </select></code> ===Download Source Files=== [http://xataface.com/documentation/tutorial/getting_started/facultyofwidgetry-7-tar.gz Download application source files as tar.gz archive] These source files reflect the application's state at this point in the tutorial. As changes are made to the application in later sections, modified source archives will be available to be downloaded. ===Summary=== In this section, we have learned how to use valuelists to add selection lists and checkbox groups to our web forms. We also shows how valuelists can be dynamically defined using SQL. Using valuelists in this way is like defining a many-to-one relationship to our database (in example 3, it was many 'Course' records to one 'Program' record). In the next section we will learn how to add many-to-many and one-to-many relationships to our database in such a way that records can be easily added and removed from relationships using Xataface. valuelists, __sql__, select lists, checkbox options,checkbox groups,vocabularies en GettingStarted:Why_Use_Xataface 72 Why Use Xataface ==Why Use Xataface?== Some simple examples similar to those that are frequently encountered by web developers, and how dataface can be used to acheive a solution. As a web services developer in the Faculty of Applied Sciences at Simon Fraser University, I am frequently getting requests to build websites that are manageable by the site owner. Most of these requests also specify certain types of content that must be stored on the website, and much of this content needs to be n-ary (i.e., there will be multiple instances of each type of content). Let me give you an example. ===Example 1: Website for Faculty of Widgetry=== The Faculty of Widgetry needs a website to publish information about its undergraduate programs. It is important for them to be able to publish admission requirements, and program overviews for each program. It is also important to have course outlines and timetables for each course. The Faculty of Widgetry has 12 undergraduate programs and over 100 courses offered. ====Solution 1: Static HTML==== To build this web site using only static HTML pages using Dreamweaver or some other HTML editor would require at least 112 pages to be created (one for each course and program). However, once we recognize that there are only 2 types of pages required (one for courses and one for programs), we can reduce the task down to creating 2 templates and filling in the main content for each program and course individually. Most HTML editors have some templating ability so you can make changes to the template and have the changes propogated to all pages that use that template with the click of a button. This works great, but courses are added frequently, and outlines are changed. Do you really want to receive requests to update all of these pages every time there are changes to make? (If your answer is 'yes', then you probably won't be interested in reading the rest of this tutorial). Whether the Dean of the faculty knows it or not, it is very important for the program assistants to be able to update these web pages on their own. To acheive these goals you can: * Install Dreamweaver on the Program Assistants' computers, teach them how to use it, and allow them to perform updates. * Install Contribute, which is a scaled down version of Dreamweaver to make it easier for the Program Assistants to edit the content. * Use another solution that is equivalent to one of the above 2 solutions. Installing Dreamweaver for each Program Assistant is a little overkill, and since it has the ability to do much more than just update content. In addition, Dreamweaver is really a developer's tool - not a secretary's tool, so it can be difficult to learn at first. The best reason NOT to install Dreamweaver on the Program Assistant's computer, however, is that it enables him/her to muck things up by accident (believe me, I has happened to me more times than I care to count). Admittedly, Contribute is a viable option as it controls access to only certain portions of web pages to be edited, and it is targetted at secretaries (not developers) so it is easier to use. In fact, given the requirements for this web site (as stated above), this is a perfectly good solution. However you better hope that none of the following requirements are added: * Each program web page should contain an up-to-date list of all of the courses required for the program, along with a link to the course outline for that course. * Course outlines should be available in PDF format as well as HTML format. * An index page showing all of the courses available should be added. This page must allow courses to be organized by program, course subject, or course number. * Any other requirement that would have information formatted in more than one way. If any of these requirements are likely to be added (EVER) then you would be well-advised to look into solutions that use a database back-end. ====Solution 2: Use a Content Management System (CMS)==== There are hundreds of content management systems available that will allow you to store and update content through the web (TTW). Some of them even have an assortment of add-ons that will allow you to store more specific types of information. Some good CMS's include Plone, Drupal, and Xoops. Suppose we want to develop the Faculty of Widgetry website using one of these CMS's. Any good CMS will allow you to create and edit HTML documents easily (without having to write any custom products). However, it is often the case that our documents require the content to be structured. For example, each program has some common data associated with it: Program Name, Admission Deadline, Program Description, Outline, Courses, etc... If we want to properly separate data from presentation, we would need to build a special content-type to store our programs. Most CMS's allow you to develop custom content-types using the underlying programming language and an API (Application Programming Interface). Some API's are easier to use than others and some are documented better than others. The common element is that each has its own proprietary interface for writing these add-ons. If you are using a CMS and you are proficient in the creation of add-on content-types, then you will be able to build the Faculty of Widgetry website without great difficulty. However there are a number of reasons why you may choose NOT to use a CMS: * Steep learning curve: Depending on the CMS it can be very time consuming and difficult to learn how to use and modify the CMS to suit you purposes. * It is over-kill: Most CMS's are filled with features and modules that you will never need. In fact it can even be a pain to turn them off if you don't want them. * You can get tied into the CMS: When you are using a CMS, you will start developing for the CMS. With all of your content in the CMS it may be difficult to migrate to a different solution later on. (The truth of this statement will vary for different CMS's). Choose your CMS carefully. ====Solution 3: Use an existing Application==== OK, OK, let's not get too carried away with trying to develop the website until we have checked the market to see if someone else has already done it better. Maybe there is already a PHP application that makes websites for Faculties easy. I mean, I can't be the first person that needed to build a website for a Faculty. In fact if you do a search or go to Hotscripts.com, you will probably find a handful of applications or scripts that almost do what you need. If you're lucky, maybe you can find an application that does exactly what you need (but frankly, I've never been that lucky). If you find one, maybe it's worth taking it for a test drive. But beware. Using a system that almost does what you need but is difficult to modify to your needs can be worse than building it by scratch. Make sure that you are able to modify the application to suit your needs exactly. ====Solution 4: Use PHP and MySQL==== If all we want to do is separate the data from the presentation and allow the Program Assistants to update data on the website, why not just design a MySQL database with the appropriate tables and fields to store the required data. In our case we will need 2 tables: '''Programs''': * Fields: ** ProgramID : int ** ProgramName : varchar ** ProgramDescription: text ** AdmissionDeadline: date ** Outline_HTML : text ** Outline_PDF : blob '''Courses''': * Fields: ** CourseID : int ** CourseSubject : varchar ** CourseTitle : varchar ** CourseNumber : int ** ProgramID : int ** CourseDescription : text ** Outline_HTML : text ** Outline_PDF : blob Now it's easy to create a few web pages that extract data from the database and displays it as HTML. In fact if there is an existing page template that you can use for the header and footer, you can develop the entire Faculty website in under an hour (you just have to create 3 pages). '''Question''': How will the Program Assistants update the information in the database? '''Answer''': OK, let's assume that you're not going to teach them SQL and that a DB Admin tool will also be too difficult to learn. Then you have to create HTML forms to update records in the database. Ouch! What was easy just became hard. Making HTML forms is a real pain, because you have to validate the input, deal with file uploads, and also make sure that everything is stored to the database OK without losing any information. Such a basic task, but it can be very difficult. This is when it is time to use Xataface. ====Solution 5: Use Xataface==== OK, this isn't really its own solution. It is more like "Solution 4 Part II", because Xataface is intended to complement your custom application you built with solution 4, by providing an easy-to-use, configurable user interface that is targeted at secretaries and normal users (as opposed to database administrators). A Xataface application takes only seconds to set up and it will provide you with a full user interface for your users to edit information in the database. introduction motivation why en Grafted_fields 158 Grafted fields ==Grafted Fields== ===Introduction=== When there are numerous tables, it is difficult for the user to see get an information that will help one to enter the right data in the right field. So instead of navigating in the relative tables and lose some time, it is more convenient to add a grafted field from that relative table in the table. To be able to sort a column by the content displayed when this content is extracted form a relative table, a grafted field is necessary because the real content is just an id, not the most convenient to sort in human-readable way. ===Procedure=== Two ways to add a grafted filed * The first one is to add a __sql__ statement at the beginning of fields.ini, including the grafted field through a join. <code>__sql__ = "select p.*, d.total from programmation p left join dev d on p.id_programmation=d.id_programmation" </code> * The second one is to create the function __sql__ in the delegate class <code>function __sql__(){ return "select p.*, d.total from programmation p left join dev d on p.id_programmation=d.id_programmation"; } </code> ===Sorting order based on relationship=== The solution is to hide the field with the id and to add the grafted field with the name in the fields.ini <code>[name_programmation] order=10 [id_programmation] visibility:list=hidden </code> ===Debugging=== A couple of things to check for: *1. If you have set blanket default permissions for your fields using the __field__permissions() method you could be disallowing access to the field. *2. If you have set default field visibility in the fields.ini file via the [__global__] section.... *3. Check to make sure that your __sql__ directive is at the beginning of the file and that it is __sql__ and not _sql_ *4. Try to enter an obviously invalid SQL query for the __sql__ directive to see if you get an error (to confirm that it is picking up the __sql__ directive at all). grafted fields, grafted, sorting columns, sort, relative records, relative tables en grid 67 grid ==widget:type = grid== Suppose we have two tables, tbl_organisation and tbl_individuals, in the edit view for a record in the organisations table (tbl_organisations) we also want to be able to view and edit the individuals within this organisation we can use widget:type=grid In the /tables/tbl_organisation/fields.ini we create a transient field by adding: <code> [Individuals] widget:label = "Individuals" transient=1 relationship=individuals widget:type=grid widget:columns="ind_firstname,ind_lastname,ind_tel" </code> The above assumes we have a relationship entry in our /tables/tbl_organisation/relationships.ini that looks like this: <code> [individuals] __sql__ = "SELECT * FROM tbl_individual WHERE org_id='$org_id'" </code> The fields.ini will show the three columns shown in widget:columns from the table tbl_individual Correct permissions need to be set to enable editing and deletion etc of these records. en 0 group 28 group ==group directive in [[fields.ini file]]== The group directive allows you to declare that certain fields of your table should be grouped together on the edit form and the view tab (and other logical places). For example, fields like address, city, state, country, postal_code would likely be grouped together as address_info. Grouping the fields together will make the fields appear in a section of their own in the view tab and the edit form. E.g. In your fields.ini file: <code> [address] group=address_info [city] group=address_info [state] group=address_info [country] group=address_info [postal_code] group=address_info </code> ===Configuring the Group as a Whole=== You can also configure your group in the fields.ini file by adding a '''fieldgroup:NAME''' section, where '''NAME''' is the name of the group. E.g. <code> [fieldgroup:address_info] label="Address Information" description = "Please enter your address information below" </code> ====See also:==== * [[fields.ini file]] - Scroll down to the '''Field Groups''' section. en 0 How_to_Add_Custom_Sections_to_View_Tab 52 How_to_Add_Custom_Sections_to_View_Tab ==How to Add Custom Sections to the View tab== [[toc]] The ''View'' tab is intended to give the user a detailed view of the contents of a record. By default it shows the values of each non-empty field grouped into their appropriate field groups. It also shows the most recent 5 related records from each relationship in the record. You can also add your own sections by implementing the [[section__xxx]] method of the delegate class. ==Example 1: A "Hello World" Section== We'll start by adding a simple section that simply displays "Hello World" to the user. In the delegate class for your table, add the following method: <code> function section__hello(&$record){ return array( 'content' => 'Hello World!!!', 'class' => 'main' ); } </code> Now if you reload our application and click on the "View" tab for any of the records in the database, you'll notice a section labelled ''hello'' with the text ''Hello World!!!'' in it. Let's dissect the above code so that we can better understand what is going on here. # The function ''section__hello()'' defines a section named ''hello''. If you wanted to define a section named ''foo'' you would call the function ''section__foo()'' # This function returns an array with the keys ''content'', and ''class''. # The ''content'' key points to the actual HTML content of the section. In this case it is simply the text ''Hello World!!!''. # The ''class'' key defines where the section should be displayed. It accepts values of ''left'' and ''main'' only. If it is set to ''left'', then the section will be displayed in the left column. A value of ''main'' indicates that it should be displayed in the main column. ===Customizing the Section Label=== ''hello'' is a boring label, so let's add our own custom label by adding the ''label'' key to the array returned by our method: <code> function section__hello(&$record){ return array( 'content' => 'Hello World!!!', 'class' => 'main', 'label' => 'Message of the Day' ); } </code> Now if you load the view tab of your application, you'll notice that the section has a heading "Message of the Day". ===Customizing the Section Order=== A section can also specify an ''order'' attribute to define the order in which this section should appear. It defaults to 0 which may cause the section to appear at the top of the view tab. You can push it to the bottom of the view tab by assiging a higher number to the ''order'' attribute: <code> <code> function section__hello(&$record){ return array( 'content' => 'Hello World!!!', 'class' => 'main', 'label' => 'Message of the Day', 'order' => 10 ); } </code> Now if you reload the view tab you'll notice that the section has moved to the bottom of the page. en 0 How_to_authenticate_users_with_LDAP_or_Active_Directory 64 How_to_authenticate_users_with_LDAP_or_Active_Directory ==How to authenticate users with LDAP or Active Directory== en 0 How_to_build_a_PHP_MySQL_Application_with_4_lines_of_code 38 How to build a PHP MySQL Application with 4 lines of code '''The [http://xataface.com Xataface Application Framework] allows you to convert your existing MySQL database into a full-fledged with as little as 4 lines of code. And it's Not a code generator.''' [[toc]] This article is intended to spark interest in the [http://xataface.com Xataface Application Framework] amongst PHP developers by showing how easy it is to set up a full-featured front-end for your MySQL database. If you are a PHP developer, surly you can identify with the situation where you've built a snazzy website with PHP and MySQL but you need to create some way the website users to administer it. I.e., you need to make an administrative back-end for your users. You need to do this because PHP admin is too technical for your users, and it is an aweful lot of tedious work to create all of the necessary forms and lists for your users to edit the data themselves. ===Features for our Application=== * Create, edit and delete records using simple web forms. * Browse through database and find records without any SQL. * Lots of great widgets for editing records including html editors, select lists, grids, checkboxes, calendars and more. * Sort records. * Export result sets as CSV or XML. * Fully configurable and extendable by you to implement more [[about|features]]. ===Creating the Application=== Here are 6 steps to a full-featured front-end for your database: # Create a directory for your application on your webserver. Call it ''myapp''. # Download the latest version of [http://xataface.com Xataface] and copy it into your application directory that we just created. (i.e. ''myapp/xataface''. # Create a configuration file named ''conf.ini'' inside your application directory (i.e. ''myapp/conf.ini'') to store your database connection info:<code> [_database] host=localhost name=mydb user=username password=mypass [_tables] ;; This section lists the tables to include in your application menu table1=Label for table 1 table2=Label for table 2 </code> # Create an .htaccess (i.e. ''myapp/.htaccess'') file to prevent Apache from serving your ''conf.ini'' file:<code> <FilesMatch "\.ini$"> Deny from all </FilesMatch> </code> '''Note: If you are not using Apache as your web server you'll need to block access to the .ini files using a different mechanism. E.g. On IIS you can create a Web.config file to block this access and place it inside your application's directory.''' Download a sample Web.config file [http://weblite.ca/svn/dataface/core/trunk/site_skeleton/Web.config here]. # Create an index.php file (i.e. ''myapp/index.php'') to serve as an access point for your application:<code> <?php // Include the Xataface API require_once 'xataface/dataface-public-api.php'; // Initialize Xataface framework df_init(__FILE__, 'xataface')->display(); // first parameter is always the same (path to the current script) // 2nd parameter is relative URL to xataface directory (used for CSS files and javascripts) </code> # Create a ''templates_c'' directory to store cached smarty templates or your application (i.e. ''myapp/templates_c'', and make sure that it is writable by the webserver: $ mkdir templates_c $ chmod 777 templates_c That's all there is to it! Point your web browser to the index.php file we just made, and check out your new app! ===Screenshots of Our App=== ====Find Form==== [[Image:http://media.weblite.ca/files/photos/people-find.png?max_width=400]] ====New Record Form==== [[Image:http://media.weblite.ca/files/photos/people-new-record.png?max_width=400]] ====List View==== [[Image:http://media.weblite.ca/files/photos/people-list.png?max_width=400]] ===Where to go now=== # Sign up for the Xataface mailing list to receive exclusive development tips (see the left column for a signup form). # Check out the [[about|About Xataface]] page for more information about features and requirements. # Use the [http://xataface.com/documentation/getting_started Getting Started Tutorial] to get started making your own application. # [http://xataface.com/videos Watch screencasts] showing Xataface in action. tutorial, getting started, installation, first app, 4 lines of code en 0 How_to_granulate_permissions_on_each_field 63 How_to_granulate_permissions_on_each_field ==How to granulate permissions on each field== To reach this aim, there is the method fieldname__permissions to place into the delegate class of the table. ===Getting the role=== First it is necessary to know the user's role. For this, the method getUser() is added in the class : <code>function getUser(&$record){ $auth =& Dataface_AuthenticationTool::getInstance(); $user =& $auth->getLoggedInUser(); return $user; }</code> ===Setting up the permissions for each field=== Next, the permissions are built for each column or field where they are needed, like in this example where the method name is formed with the field name, followed by 2 underscores then by ''permissions'' : <code>function fieldname__permissions(&$record){ $the_user =$this->getUser($record); $user=$the_user->val('identifiant'); if ( !$user) return Dataface_PermissionsTool::NO_ACCESS(); if ( $user=='demande' ){ return Dataface_PermissionsTool::ALL(); } elseif ($user=='admin'){ return Dataface_PermissionsTool::ALL(); } else { return Dataface_PermissionsTool::READ_ONLY(); } }</code> === Also See === * [[viewable_editable_fields]] - How to make a field editable for some users and only viewable for some other users * [[no_access_text]] - Replace the default NO ACCESS permission text with another text. * [[__field__permissions]] - Returns the default permissions for a field of a given record. * [[Delegate_class_methods#toc5|Permissions]] - other Delegate class methods en 0 http://xataface.com/documentation/how-to/site_with_backoffice 85 How to build a site with an optional login form ==How to build a site with an optional login form== To publish a public site with data without any need to login to access, here is the code : <code> function getPermissions(&$record){ if ( isAdmin() ) return Dataface_PermissionsTool::ALL(); else return Dataface_PermissionsTool::READ_ONLY(); } </code> In this way, you still can login to administrate your data. en http://xataface.com/documentation/how-to/site_with_backoffice_How_to_build_a_site_with_a_backoffice_ 84 A site with a backoffice ==A site with a backoffice== To create a site with a backoffice for the administrator, so that the visitors do not have to log in to read the pages, you add this code in the ApplicationDelegate.php file in the conf directory : <code> function getPermissions(&$record){ if ( isAdmin() ) return Dataface_PermissionsTool::ALL(); else return Dataface_PermissionsTool::READ_ONLY(); } </code> en index_page 1 index_page ==Documentation== [[toc]] ===Introductory=== * [[about|About Xataface]] * [http://xataface.com/documentation/tutorial/getting_started Getting Started Tutorial] * [[How to build a PHP MySQL Application with 4 lines of code]] * [[Troubleshooting]] ===Reference=== * [http://dataface.weblite.ca API Docs] * [[conf.ini file]] directives * [[fields.ini file]] directives * [[valuelists.ini file]] directives * [[relationships.ini file]] directives * [[Delegate class methods]] * [[Application Delegate Class]] * [[permissions.ini file]] directives * [[actions.ini file]] directives * [[preferences|User Preferences]] - options for customizing the application further via the getPreferences() method. * [[xataface templates|templates]] * '''[[URL Conventions]]''' - Learn how to use Xataface's URL conventions to form URLs that return exactly the result set that you want. * '''[[Roadmap]]''' - What is planned for the next releases of Xataface ===Cook Book=== * [[Customizing Theme Based on IP Address]] - An article on storing IP addresses in the database and showing users a different theme depending on which range of IP addresses they are connecting from. ===By Topic=== ====Installation==== * '''[http://xataface.com/documentation/tutorial/getting_started/installation Xataface Installation Instructions]''' - This document explains how to install Xataface on your system. It does not describe how to create an application with Xataface. * '''[http://xataface.com/documentation/tutorial/getting_started/first_application Creating your first App]''' - How to create an application using Xataface (from the Getting Started Tutorial) * '''[[about|About Xataface]]''' - Quick overview of Xataface. Includes a 6 step example of creating an application with Xataface. ====Configuration==== * '''[http://xataface.com/documentation/tutorial/getting_started/customizing Customizing field labels, descriptions, and widgets]''' - This document explains how to customize some basic aspects of your application's edit forms. (From the Getting Started tutorial). * '''[http://xataface.com/documentation/tutorial/getting_started/valuelists Using Valuelists]''' - How to use valuelists to set up options for your select lists and checkbox groups. * '''[http://xataface.com/documentation/how-to/list_tab Configuring and customizing the list tab]''' - This document explains how to customize the display of the list tab using INI files, templates, and delegate classes. ====Internationalization==== * '''[[Contribute to Xataface Translation Project]]''' - We need translators to help us keep the Xataface translations up to date. This page shows how you can help. * '''[http://xataface.com/documentation/tutorial/internationalization-with-dataface-0.6 Internationalization with Xataface]''' (tutorial) * '''[http://xataface.com/documentation/how-to/how-to-internationalize-your-application How to internationalize your application]''' (how to) - Xataface 0.6 contains a LanguageTool class that allows your applications to be presented in multiple languages * '''[http://xataface.com/documentation/how-to/use-translations How to use other translations]''' - Xataface 0.7 includes German and French translations. This document explains how to allow your application to use these and other translations, rather than the default English translation. * '''[http://xataface.com/documentation/how-to/unicode How to enable unicode support]''' - As of Xataface 0.6, unicode is fully supported so that your dataface application will work with any and multiple languages simultaneously. * '''[http://weblite.ca/svn/dataface/core/trunk/lang Download latest language files out of SVN]''' - If you want to make sure that you have the latest translations, you can download them from SVN and place them into your xataface lang directory. ====User Interface Customization==== * '''[[preferences|User Preferences]]''' - You can hide, show, enable, and disable features of the application selectively. * '''[http://xataface.com/documentation/tutorial/getting_started/changing-look-and-feel Changing the Look and Feel]''' - Change the way your application looks by adding custom headers, footers, and sections, and by overriding the default templates with your own custom templates. (From the Getting Started tutorial). * [[xataface templates|templates]] * '''[http://xataface.com/documentation/tutorial/customizing-the-dataface-look-and-feel Customizing the Xataface look and feel]''' tutorial * '''[[Customizing the look and feel of a row or a cell| Customizing the look and feel of an element in the list view]]''' - Personnalize the aspect of each part of your list according to its content. * '''[http://xataface.com/documentation/how-to/custom_javascripts How to include custom javascripts and stylesheets]''' - Use the custom_javascripts and custom_stylesheets blocks to include your own custom javascript and CSS files in your application. * '''[http://xataface.com/documentation/how-to/hide_search How to hide the search box]''' - The full-text search box that appears in the upper right can easily be removed. * '''[http://xataface.com/documentation/how-to/list_tab Configuring and customizing the list tab]''' - This document explains how to customize the display of the list tab using INI files, templates, and delegate classes. * '''[[How to Add Custom Sections to View Tab]]''' - The ''View'' tab in a Xataface application can be configured in many ways. This tutorial shows you how to add your own custom sections to the view tab. * '''[[Creating a Dashboard]]''' - Create a dashboard action for your users to so that they have a logical starting point in your application. * '''[[Grafted fields]]''' - Add a grafted field to your table for user convenience. You can use it also to be able to sort columns with relative tables content. * '''[[Clean the html for the export]]''' - Clean the HTML tags and entities for the export in CSV or XML. ====Using the API==== * '''[[Introduction to the Xataface API]]''' - A short introduction to the classes, methods, and functions available in the Xataface API. * '''[http://xataface.com/documentation/how-to/how-to-define-custom-serialization-for-fields How to define custom serialization for fields]''' ====Security==== * '''[[authentication]]''' - Overview of Xataface Authentication * '''[[registration form]]''' - Enabling User Registration in Xataface * '''[[permissions.ini file]]''' - Reference of the permissions.ini file directives. * '''[http://xataface.com/documentation/tutorial/getting_started/permissions Permissions]''' - Use sessions and delegate classes to define permissions at the record and field level. (From the Getting Started tutorial). * '''[[Cached permissions]]''' - Use cached perms for complex queries inside getPermissions() * '''[[Delegate_class_methods#toc5|Delegate class methods]]''' - Permissions-related functions * '''[[Relationship Permissions]]''' - Guide to permissions on related records. * '''[http://xataface.com/documentation/how-to/disallow_tables How to disallow access to tables]''' * '''[[site_with_backoffice]]''' - A site with a backoffice without obligation to log in * '''[http://xataface.com/documentation/how-to/security_filters Security Filters]''' - Use security filters to block users from seeing certain records. * '''[[How to granulate permissions on each field]]''' - Decide for each field who can edit, read... ** '''[[no_access_text]]''' - Replace the default NO ACCESS permission text with another text. * '''[[LDAP or Active Directory]]''' - How to authenticate users with LDAP or Active Directory... ====Performance==== * '''[http://xataface.blogspot.com/2009/06/using-query-caching-in-xataface.html Using Query Caching]''' - Query caching can drastically improve performance of busy applications with large databases. This article explains how to enable this caching in your Xataface application. * '''[[_output_cache]]''' - Xataface does quite a bit of heavy lifting on each page request. If your application is getting a lot of traffic that is slowing your server down, you may want to look at enabling the Xataface output cache. ====Modules==== * [[modules]] - Available Xataface Modules. This includes such things as CAPTCHA validation, editable javascript grids, and more. * [[Module Developers Guide]] - A guide / Tutorial on how to develop your own Xataface modules. ====Preferences==== ====Relationships==== * '''[http://xataface.com/documentation/tutorial/getting_started/relationships Relationships]''' - Xataface allows you to define relationships between tables using the relationships.ini file. (From the Getting Started Tutorial) * '''[http://xataface.com/documentation/how-to/how-to-assign-order-to-related-records How to assign order to related records]''' - Sometimes it is desirable for the records in a relationship to take on a particular default order. Dataface 0.6 makes this easy if you follow a few conventions. * '''[[Drag and Drop Reordering of Relationships]]''' - A more in-depth tutorial about adding ordering to relationships. * '''[[relationships.ini file]] reference * '''[[Relationship Permissions]] ====Forms==== * '''[http://xataface.com/documentation/how-to/DisableEnterKeyInFields How to disable the enter key in forms]''' * '''[http://xataface.com/documentation/tutorial/getting_started/customizing Customizing field labels, descriptions, and widgets]''' - This document explains how to customize some basic aspects of your application's edit forms. (From the Getting Started tutorial). * '''[http://xataface.com/documentation/tutorial/getting_started/valuelists Using Valuelists]''' - How to use valuelists to set up options for your select lists and checkbox groups. (From the Getting Started tutorial) * '''[http://xataface.com/documentation/tutorial/getting_started/validation Form Validation]''' - Xataface allows you to add validation rules to fields using the fields.ini file. (From the Getting Started tutorial). * '''[http://xataface.com/documentation/how-to/how-to-handle-file-uploads How to handle file uploads]''' - Xataface allows you to store file uploads in BLOB fields or on the file system. * '''[http://xataface.com/documentation/how-to/custom_validation How to add custom validation with delegate classes]''' - If the standard validators (e.g., required, email, regex, etc..) don't quite cut it for your validation rules, Xataface allows you to define custom validation methods in the delegate class. * '''[http://xataface.com/documentation/how-to/regex_validation Validating with regular expressions]''' - How to validate input into a field using regular expressions. * '''[[Dynamic select boxes]]''' - How to create two dynamic javascript select boxes from the valuelists. ====Importing==== * '''[http://xataface.com/documentation/how-to/import_filters Import Filters]''' - It is common to need to import records en masse into a database. This is what import filters are for. (Since 0.7). ====Actions==== * '''[http://xataface.com/documentation/tutorial/getting_started/dataface_actions Actions I: The Basics]''' - Web Lite's actions framework allows you to customize existing actions (e.g. new, edit, find) and create your own new actions. (From the Getting Started Tutorial). * '''[http://xataface.com/documentation/how-to/after_action_triggers Adding triggers to actions]''' - Xataface 0.6.1 adds some triggers to actions so that the developer can define custom functionality to be performed after an action has successfullly taken place. * '''[[Calendar Action]]''' - Using the built-in calendar action to add a full-fledged event calendar to your application. * '''[[Creating a Dashboard]]''' - Create a dashboard action for your users to so that they have a logical starting point in your application. * '''[[Selected Records Actions]]''' - Create custom actions that are performed on records that have been selected in the list tab. * '''[[Creating Printable Reports]]''' - Create a custom printable report using a custom action. * '''[[Using RecordGrid]]''' - Using Dataface_RecordGrid to print data in tabular form. ====History==== * '''[http://xataface.com/documentation/how-to/history-howto How to activate history logging]''' - Xataface 0.6.9 comes with support for managing the history of your records. This how-to shows you how to enable and use this feature. ====RSS Feeds==== * '''[[Introduction to RSS Feeds in Xataface]]''' - Xataface provides RSS feeds to any found set in your application. This tutorial shows how it works and how you can configure these feeds to get your desired results. ====Event Calendar==== * '''[[Calendar Action]]''' - Introduction to the Xataface calendar action which can be used to convert your application into a full-fledged event calendar. en 0 init 140 init() Delegate Class Method == Synopsis == This method is called once, just after the table is loaded for the first time. It allows you to specify initialization details, such as [[setSecurityFilters|security filters]]. Note that it takes a single parameter: a Dataface_Table object of the table that is being initialized. == Example == <code> function init(&$table){ .... } </code> en Internet_Media_Manager 8 Internet Media Manager '''Manage your videos and photos all in one place''' [[toc]] ===Watch the Guided Tour (6 minutes)=== <nowiki> <embed src="http://media.weblite.ca/lib/flvplayer.swf" width="640" height="448" bgcolor="#FFFFFF" type="application/x-shockwave-flash" pluginspage="http://www.macromedia.com/go/getflashplayer" flashvars="file=http%3A%2F%2Fs3.amazonaws.com%2Fweblite_media%2Fintro_video.flv&image=http%3A%2F%2Fmedia.weblite.ca%2Ffiles%2Fphotos%2Fintro_video.flv.AbpY0Y.jpg&showdigits=true&autostart=false" /> </nowiki> ===Introduction=== The Internet Media Manager is a web-based database application that allows webmasters to centrally store their images and videos to be served on their website(s). It provides a Youtube-like interface whereby users can simply copy and paste code snippets to embed images and videos into their web pages. It also provides a photo gallery component that allows users to easily embed a gallery of images into their web pages by simply copying and pasting a snippet of javascript code. ===Purpose=== I created this application because: # I didn't want to have to resize images in Photoshop anymore before uploading them to the web. # I wanted to be able to embed videos, images, and photo galleries into my web pages without having to muck around with HTML code. IMM (Internet Media Manager) allows you to resize your photos to any size you want, and embed these resized images in your web pages by copying and pasting a snippet of HTML. Similarly it makes embedding videos and photo galleries into your website a snap. ===Features=== * Add/Edit/Delete/Categorize images and videos in a searchable database. * Import multiple images or videos at once by uploading a ZIP file. * Large file imports via FTP/SSH. * Embed video and images directly into other web pages by copying and pasting HTML snippets (like Youtube). * Resize images and videos. * FLV video support (like Youtube). * Search media by content type, category, keyword, etc.. * Includes javascript photo gallery component that can be embedded into any web page. * Amazon Simple Storage Service (S3) integration. ===Requirements=== * [http://www.php.net|PHP] 5.2+ * [http://www.mysql.com|MySQL] 4.1+ * [http://ca.php.net/gd|GD_Image_Processing_Library] * [http://ffmpeg.mplayerhq.hu/|FFMPEG] (optional - if you want to automatically generate poster images for videos). ===Download=== * [https://sourceforge.net/projects/immgr/files/|Internet Media Manager 0.3] ===Installation=== # Download the latest version from Sourceforge. # Extract the files and copy to your web server. # Point your web browser to the install.php and follow the instructions. ===Screenshots=== <nowiki> <script language="javascript" type="text/javascript" src="http://media.weblite.ca/index.php?-action=gallery&-table=files&categories=3&-cursor=0&-skip=0&-limit=30&-mode=list&-photo_max_width=500&--format=js"></script> <div style="clear:both"></div> </nowiki> ===Screencasts=== How to import multiple images at once in a ZIP archive. <nowiki><iframe title="YouTube video player" width="640" height="510" src="http://www.youtube.com/embed/0gfRJ5HkRsI" frameborder="0" allowfullscreen></iframe></nowiki> ===Support=== Visit the [http://xataface.com/forum/viewforum.php?f=12|Support_forum]. Internet Media Manager,resize photos,image gallery,photo gallery,video gallery en 0 Introduction_to_RSS_Feeds_in_Xataface 40 Introduction_to_RSS_Feeds_in_Xataface ==Introduction to RSS Feeds in Xataface== [[toc]] A default Xataface application provides RSS feeds to any found set in your application. This article explains a little bit about RSS and how you can configure Xataface to give you the desired results for your RSS feed. ===What is RSS?=== From [http://en.wikipedia.org/wiki/RSS_(file_format) Wikipedia's RSS article]: "RSS is a family of Web feed formats used to publish frequently updated works such as blog entries, news headlines, audio, and videoin a standardized format.[2] An RSS document (which is called a "feed", "web feed",[3] or "channel") includes full or summarized text, plus metadata such as publishing dates and authorship. Web feeds benefit publishers by letting them syndicate content automatically. They benefit readers who want to subscribe to timely updates from favored websites or to aggregate feeds from many sites into one place. RSS feeds can be read using software called an "RSS reader", "feed reader", or "aggregator", which can be web-based or desktop-based. A standardized XML file format allows the information to be published once and viewed by many different programs. The user subscribes to a feed by entering the feed's URI (often referred to informally as a "URL", although technically, those two terms are not exactly synonymous) into the reader or by clicking an RSS icon in a browser that initiates the subscription process. The RSS reader checks the user's subscribed feeds regularly for new work, downloads any updates that it finds, and provides a user interface to monitor and read the feeds." In a way RSS replaces email subscriptions so that you can subscribe to receive updates when content is added or changed on websites that you monitory. This way you can monitory these changes in your RSS reader so that your email box doesn't get clogged up. ===Using RSS in Xataface=== Xataface allows you to subscribe to: # Entire tables # Any found set # Changes to a particular record # Related record lists ====Example 1: Subscribing to receive news updates==== A user wants to be alerted whenever a new item is inserted into the ''news'' table, so he navigates to the ''list'' tab of the ''news'' table, and clicks the RSS Feed icon in the upper right. If he has an RSS reader application set up, this is all he has to do to subscribe to the RSS feed for the ''news'' table. When new records are inserted, he'll receive alerts in his RSS reader. ====Example 2: Subscribing to receive found set updates==== A user wants to be alerted whenever a new item is inserted into the ''news'' table that contains the phrase "Buffalo Bills", because he is a Buffalo Bills fan. So he navigates to the ''news'' table, and does a search for the phrase "Buffalo Bills". Then he clicks on the "RSS Feed" icon in the upper right of the result set list. If he has an RSS reader application set up, this is all he has to do to subscribe to the RSS feed for ''news'' items containing the phrase "Buffalo Bills". Whenever a new item is posted with this phrase, he will be notified via RSS of the new record. ====Example 3: Subscribing to a related list==== Suppose you want to receive updates whenever a particular author adds a book to his list of published works. Further suppose this is represented by a relationship between the ''authors'' table and the ''books'' table named ''publications''. You can subscribe to the RSS feed for his publications by navigating to the ''publications'' tab for that author, then clicking on the "RSS Feed" icon in the upper right. Now whenever this author adds a new book to his publications list, you'll be notified via RSS. ===Example usage in Xataface=== # A user wants to be alerted whenever a new item is inserted into the ''news'' table, so he navigates to the ''list'' tab of the ''news'' table, and clicks the RSS Feed icon in the upper right. If he has an RSS reader application set up, this is all he has to do to subscribe to the RSS feed for the ''news'' table. When new records are inserted, he'll receive alerts in his RSS reader. # A user wants to be alerted whenever a new record about "Wayne Gretzky" is inserted in to the ''news'' table. He navigates to the ''news'' table, then performs a search for "Wayne Gretzky" using the top right search box. Then, he clicks on the "RSS Feed" icon in the upper right of the result list. Now, whenever a new item is inserted with the phrase "Wayne Gretzky", the user will be notified via RSS. ===Configuring RSS Feeds=== As with everything else in Xataface, you can configure your RSS feeds to appear just as you want them to. The following delegate class methods are available to be defined in the table delegate class for your feed: {| 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 |- | getRSSDescription | Overrides the default generated RSS description for a record. | 1.0 |- | [[getSingleRecordSearchFeed]] | Overrides the default feed for a subsearch within a record. This works identically to the [[getFeed]] method except that it takes 2 parameters: one for the current record, and a second parameter for the query. | 1.2.3 |} ==Example Configuration== There are 2 parts to configuring your RSS feeds. # Configuring the feed as a whole # Configuring the feed items (that is each record that will appear in your RSS feed). ===Configuring the Feed as a whole=== For configuring the feed as a whole, we have 2 options. We can specify the title, description, and link for the feed in the ''[_feed]'' section of your [[conf.ini file]]. This is sort of a "one size fits all" approach where all feeds generated from your application will share the same title. E.g. <code> [_feed] title="My Site News" description="News updates from my site" link="http://www.example.com" </code> However, if we want our feed's information to depend on the user's query (e.g. what the user was searching for, or which table the feed is generated on, we have more flexibility if we define the [[getFeed]] method in either the [[Application Delegate Class|application delegate class]] or the [[Delegate class methods|table delegate class]]. E.g. <code> function getFeed($query=array()){ $params = array(); if ( @$query['-search'] ) $params['title'] = '"'.$query['-search'].'" results'; else $params['title'] = 'All records from my table'; return $params; } </code> Notice that I don't need to define all possible parameters. Any parameters that I don't define will be provided automatically by Xataface, or it will simply use the values specified in your ''[_feed]'' section of the [[conf.ini file]]. ===Configuring Feed Items=== Configuring the feed items is quite important for ensuring that subscribers are seeing what you want them to see in the RSS feed. Xataface tries to guess appropriate content for your feed items if you don't specify it explicitly, but you'll likely want to tweak it a little bit to make the feed look more polished for your purposes. Use the [[getFeedItem]] [[Delegate class methods|delegate class method]] to specify how a feed item behaves (e.g. the title, content, date, author, link). E.g. <code> function getFeedItem(&$record)){ return array( 'description' => $record->val('body') ); } </code> Once again, notice that we don't need to specify all available options. Only those options that we want to override. In this case we want the description of the feed item to simply display the body of our news item. The description of an RSS feed item is effectively the body text that the user sees why they click on an item in their news reader, so this is quite important. RSS Feeds en 0 Introduction_to_the_Xataface_API 101 Introduction to the Xataface API Back to [http://xataface.com/wiki the wiki] [[toc]] ===Synopsis=== Xataface is provides an API to help in developing your own custom actions. This API includes objects and functions to more easily interact with the database (i.e. search, edit, delete, and save records), build forms, use templates, and more. This section of the wiki endeavors to highlight some of the more useful and commonly used aspects of the API. ===The dataface-public-api.php Facade=== Much of the functionality provided by the Xataface API is wrapped up easy-to-use functions which are made available in the dataface-public-api.php script, which is always present in a Xataface application (it is loaded at the beginning of your index.php file). ===Some Common Tasks=== ====Loading a Single Record from the Database==== <code> // Load record from 'people' table matching person_id=10 $record = df_get_record('people', array('person_id'=>10)); // Load record from people table with first_name 'John' and last_name 'Smith' $record2 = df_get_record('people', array('first_name'=>'=John', 'last_name'=>'=Smith')); // $record and $record2 are Dataface_Record objects. echo "Loaded Person: ".$record->val('person_id'). " named ".$record->val('first_name').' '.$record->val('last_name'); </code> In the above examples we load a [http://dataface.weblite.ca/Dataface_Record Dataface_Record] object and use the val() method to display particular field values. The 2nd arguments of df_get_record() is an array which serves as a query. See [[URL Conventions]] for more examples of the types of queries that you can provide here. ====Loading a set of records from the Database==== <code> // Load the first 30 canadians from the people table $people = df_get_records_array('people', array('nationality'=>'=canadian')); foreach ( $people as $person){ // $person is a Dataface_Record object echo " Person ".$person->val('person_id')." is named ".$person->val('first_name'); } </code> '''Caveat: Note that when loading records using df_get_records_array() it only loads a preview of each record for memory's sake.''' A preview of the record is the same as a full record except that all fields are truncated to be less than 255 characters. If you have long text fields that you need to load, then these will be truncated. There are a few different solutions if you need to load the entire contents of a long field, including: * Use df_get_record instead. (This is only preferable if you are only loading a single record). * Use the [[struct]] [[fields.ini file]] directive on the field to designative the field contents as a 'stucture' that should never be truncated. * Use the extended form of ''df_get_records_array()'' with the 5th parameter (preview) set to false. E.g. <code> $people = df_get_records_array('people',array(), null, null, false); </code> ====Editing and Saving a Record==== <code> $person = df_get_record('people', array('person_id'=>10)); // Using setValue() to set a single field value. $person->setValue('first_name', 'Peggy'); // Using setValues() to set multiple field values at once $person->setValues(array('first_name'=>'Peggy', 'last_name'=>'Sue')); // Commit the changes to the database $person->save(); </code> xataface api, df_get_record, df_get_records_array, Dataface_Record, Editing, Saving, Loading, Searching 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 LDAP_or_Active_Directory 65 How to authenticate users with LDAP or Active Directory [[toc]] It is often easier to use the existing LDAP or Active Directory to authenticate users in Xataface than to create a new password for every user in the table users. ===In the conf.ini=== In the conf.ini file, in the [auth] part, you need to add your LDAP or AD configuration data : <code>[_auth] auth_type=ldap users_table = xata_users username_column = id ldap_host = "xxx.xxx.xxx.xxx" ldap_port = "389" ldap_base = "OU=blabla,DC=blablabla"</code> Here in the table users, you need the login but the password can be just ''PASS'', because the password will be fetched into the LDAP base. You need to add the [http://weblite.ca/svn/dataface/modules/Auth/ldap/trunk/ auth module] in the conf/modules directory. ===See Also=== * [[authentication]] - Overview of Authenthentication features in Xataface LDAP,Active Directory,Authentication en 0 list:type 128 list:type relationships.ini file directive Return to [[relationships.ini file]] [[toc]] The list:type directive allows you to override the default list that is used to display related records. As of Xataface 1.3 there is only one possible value that will have any effect on this directive: "treetable". Setting <code> list:type=treetable </code> will cause the related records to be displayed as an expandable/collapsible tree table as shown here: <nowiki><img src="http://media.weblite.ca/files/photos/Screen%20shot%202011-04-29%20at%2011.49.33%20AM.png?max_width=640"/></nowiki> ===Prerequisites=== The TreeTable component needs to be able to figure out the logical children of each record in order to know what to show when a row is expanded. You can use either the [[meta:class]] directive of the [[relationships.ini]] file to specify a relationship as a "children" relationship, or you can implement the [[getChildren]] method of the table delegate class to manually define a record's child elements. ==See Also== * [[getChildren]] * [[meta:class]] * [[getParent]] en loginFailed 184 loginFailed() Application Delegate Trigger [[toc]] The loginFailed() method of the Application Delegate class is executed after a failed login attempt. '''Available since 2.0.1''' ==Example== <code> function loginFailed($username, $userIp, $time){ error_log("Failed login for username: $username at IP $userIp at time $time"); } </code> login permissions failed password en lookup 61 The Lookup Widget Return to [[widget:type]] page to see list of all widget types. Back to [[fields.ini file]] to see other fields.ini directives. [[toc]] ===Synopsis=== The lookup widget allows users to look a record from another table to insert into the field. It is like a select widget except that it doesn't use a vocabulary. Instead you just specify a table on which it should search using the widget:table directive. In order to use the lookup widget to edit a field, you should set the [[widget:type]] directive of the [[fields.ini file]] for the field to '''lookup''. I.e. <code> [fieldname] widget:type=lookup widget:table=mytable </code> '''Note that the lookup widget requires the [[widget:table]] directive to be set to the target table of the lookup or it will not work properly.''' ===Required Directives=== The following [[fields.ini file]] directives are required to accompany the field definition if a lookup widget is used: {| class="listing listing2" |- ! Name ! Description ! Version |- | widget:table | The name of the table in which the lookup widget should look up related records. | 1.0 |} ===Optional Directives=== The following additional optional directives may be used to customize the behaviour of the lookup widget: {| class="listing listing2" |- ! Name ! Description ! Version |- | widget:filters:-limit | Sets the number of records that are shown by default in the lookup widget. Default is 30 if this is omitted. E.g.<code>widget:filters:-limit=100</code> to show 100 records at a time. | 1.0 |- | widget:filters:-sort | Specifies the columns to sort the results on. E.g. <code>widget:filters:-sort=category_name asc, year desc</code> | 1.0 |- | widget:filters:* | Any valid Xataface directive can be used to filter the results by specifying widget:filters:param (where "param" is a valid Xataface GET parameter, which could include a column name to filter results on, or other filter directives). <code>widget:filters:country=Canada</code> To only show results with Country=Canada. | 1.0 |- | widget:filters:*=$* | Dynamic filters. Causes the options in the record browser to be filtered on the value of another field in the form. e.g. <code>widget:filters:country_id="$country_id"</code> would show only results with records having country_id matching the value of the 'country_id' field in the current form. | 1.3.1 |} See [[URL Conventions]] for an overview of the types of GET parameters Xataface can take. Any GET parameters that manipulate a query can be used with the widget:filters:* directive to modify the query results that are shown in the lookup widget. ===Example=== In this example we have a field named appointee that is supposed to reference the contacts table. So in the [[fields.ini file]] we would have: <pre> [appointee] widget:type=lookup widget:table=contacts </pre> Initially we just have a little find icon next to the field. If the user clicks it, a dialog pops up enabling them to search for the contact that they want: [[Image:http://media.weblite.ca/files/photos/Picture%2023.png?max_width=640]] ===Additional Tips=== Although the lookup widget does not use a vocabulary as indicated in the Synopsis above, it is still useful to define a vocabulary in the fields.ini file for this field. The reason is because the lookup widget is only used with the edit action, where you are inserting or editing data into the field. However, it is not used to the display the data in the view or list actions. Therefore, you must still have a vocabulary defined to properly display these values. In order to customize the display of the lookup widget's select list, you must edit the delegate class for the table which is referenced by the widget:table directive. There are two important points to note: # The items in the selection list are formatted based on the getTitle(&$record) delegate class function if it is defined. However, ... # The Search box will search on text in VARCHAR and TEXT fields. If you need to search for data in numeric fields, you can create a grafted field using a function such as CONCAT() to display numbers as text. Links: * [http://xataface.com/forum/viewtopic.php?f=4&t=6723 Lookup widget on view with compound primary key] lookup widget, widget:filters, widget:-filters:limit, widget:table en 0 meta:class 127 meta:class relationships.ini file directive Return to [[relationships.ini file]] [[toc]] The ''meta:class'' directive allows you to ascribe special meaning to a relationship which Xataface can use in various parts of your application to provide enhanced capabilities. For example you can specify a relationship as a "parent" relationship, thereby using the relationship to obtain the "parent" of records of this table. This can be used to help build breadcrumbs. You can also specify a relationship as a "children" relationship which would treat records in the relationship as children of the current record. This can be used in conjunction with the [[list:type]]=treetable directive of the [[relationships.ini file]] to build a tree table that navigates all child records and subtrees. The Dataface_Record class contains some methods for retrieving the parent and children of records and these methods will take into account any settings you make here. ===Allowed Values=== {| class="listing listing2" |- ! Name ! Description ! Version |- | parent | Designates the relationship as a 'parent' relationship, meaning that the first record in this relationship will be treated as the parent of the current record. This setting can be overridden by the [[getParent]] method of the table delegate class if implemented. | 0.8 |- | children | Designates the relationship as a 'children' relationship meaning that records of the the relationship will be treated as a children. This setting can be overridden by the [[getChildren]] method of the table delegate class if implemented. | 0.8 |} ==See Also== # '''[[list:type]]''' - [[relationships.ini file]] directive to use a treetable for the related record list of a relationship. # '''[[getChildren]]''' - Delegate class method to explicitly define the Dataface_Record objects that are to be considered as child records of the current record. # '''[[getParent]]''' - Delegate class method to explicitly define the Dataface_Record object that is to be considered as the parent record of the current record. en modules 30 Xataface Modules [[toc]] Xataface provides a number of hooks that allow developers to create modules to extend its functionality. This page lists a handful of the currently available modules. * [[ShoppingCart|Shopping Cart]] - Converts your application into a shopping cart. * [[Filemaker]] - Export record sets as Filemaker XML. * [[DataGrid|Data Grid]] - Editable Datagrid. * [[Email]] - Convert your database into a email list. Send email to any found set. * [[reCAPTCHA module]] - A reCAPTCHA module to add CAPTCHA support to your Xataface forms. * [[XataJax]] - Platform for building Web 2.0 AJAX applications with Xataface. Will be a standard component for Xataface starting with version 1.3. ==Module Installation== You can add modules in either: # DATAFACE_PATH/modules directory (since 1.0) # DATAFACE_SITE_PATH/modules directory (since 1.3) Modules in the DATAFACE_SITE_PATH directory will supersede modules in the DATAFACE_PATH/modules directory (since 1.3). To activate a module for your application you also need to add an entry to the [[_modules]] section of your [[conf.ini file]]. Each module will come with its own installation instructions. ==Authentication Modules== Modules to add alternative authentication methods are added to the modules/Auth directory. ==Developing Your Own Modules== See [[Module Developers Guide]]. modules, captcha en 0