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_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_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 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 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 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 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 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><br/></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><br/></nowiki>[[Image:http://xataface.com/documentation/tutorial/getting_started/actions-menu-1.gif]]<nowiki><br/><br/></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><br/></nowiki>[[Image:http://xataface.com/documentation/tutorial/getting_started/new-course-form-1.gif]]<nowiki><br/></nowiki>Notice that the "Subject" field is represented by a select widget, its options are as follows:<nowiki><br/></nowiki>[[Image:http://xataface.com/documentation/tutorial/getting_started/course-subject-pulldown-1.gif]]<nowiki><br/></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><p></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></p></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: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: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><br/></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><br/></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: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> <p>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:</p> </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: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><br/></nowiki>[[Image:http://xataface.com/documentation/tutorial/getting_started/directory-structure-relationships.gif]]<nowiki><br/></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><p>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.</p> <p> The above defined table will serve as a join table between 'Program' and 'Course' </p></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><p> And now we can remove the 'ProgramID' field from the 'Course' table. ALTER TABLE Course DROP ProgramID</p></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><p> 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.</p></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><br/></nowiki>[[Image:http://xataface.com/documentation/tutorial/getting_started/multi-relationship.gif]]<nowiki> <p> 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:</p></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: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:Installation 73 Installation ==Installation== Download and installation instructions for the Web Lite framework. Xataface is a 100% PHP Framework that comes with all dependencies as part of the installation. The framework itself lives inside a single directory that should be placed inside the document root of your web server so that it can be accessed from the web. You can install a single copy of Xataface to be used by multiple applications on your web server. Each application just "requires" the key files from the Web Lite framework. ===Downloading=== # Go to the Xataface Sourceforge project file releases page # Download the latest file release. ===Installing=== # Unpack the gzipped tar archive that you downloaded somewhere in your web server's document root (i.e., make sure that the 'dataface' directory is in a web-accessible location). # Make the dataface/Dataface/templates_c directory writable by the web server. An unsafe way to do this is to chmod 777 Dataface/templates_c But it would be better to just give write access to the web server user. # Confirm that the installation worked by pointing the web browser to http://yourdomain.com/path/to/dataface/dataface_info.php . If it worked OK, you should receive a web page that says "Dataface is installed correctly", along with some basic instructions for creating a Xataface Application. (Note: Sometimes this page will give you a false positive. i.e., it may say the installation worked but then your Xataface application receives errors. Check the troubleshooting section below to deal with these issues). ===Troubleshooting=== If your installation is not going as planned, don't panic. There is a possiblity that your system has a slightly different configuration and you have to make some small adjustments to make the installation work. The general procedure for troubleshooting the installation is as follows: # Check the [[Troubleshooting]] page. # Look through the [http://xataface.com/forum forum] to see if others have experienced the same thing. # Post your question in the forum if you can't find the answer already. installation troubleshooting downloading en GettingStarted:first_application 74 Creating your First Application ==Creating Your First Application== Build a simple Xataface application. For our first Xataface application we will try to build a web site for Faculty of Widgetry (From the example in the "Why Use Xataface" page). The web site needs to store information about programs and courses. An entity-relationship diagram (ERD) for this website is included below: [[Image:http://xataface.com/documentation/tutorial/getting_started/er-diagram.png]] As the ERD shows, our database will need 2 tables (Course and Program). Our next step is to build this database. You can use any MySQL database administration tool to builld the database. My personal tool of choice is PHPMyAdmin. ===Step 1: Creating the database using PHPMyAdmin=== The following steps describe the procedure for creating this database using PHPMyAdmin. # At the main menu of PHPMyAdmin, type 'FacultyOfWidgetry' into the 'Create new database field' as follows: <nowiki><br/></nowiki>[[Image:http://xataface.com/documentation/tutorial/getting_started/new_database.gif]] <nowiki><br/></nowiki>Then click 'Create'. # First we will create the 'Course' table to hold course information. In the 'FacultyOfWidgetry' page, fill in the 'Create new table text field as follows: <nowiki><br/></nowiki>[[Image:http://xataface.com/documentation/tutorial/getting_started/create_table.gif]] <nowiki><br/></nowiki> Then click 'Go'. # This should bring up a form to specify the fields for the course table: <nowiki><br/></nowiki>[[Image:http://xataface.com/documentation/tutorial/getting_started/course-table-def-small.gif]] <nowiki><br/></nowiki> Then click "Save". The resulting SQL to create the Course table is as follows:<code> CREATE TABLE `Course` ( `CourseID` int(11) NOT NULL auto_increment, `ProgramID` int(11), `CourseTitle` varchar(64) NOT NULL default '', `CourseDescription` text NOT NULL, `HTMLOutline` text NOT NULL, `PDFOutline` longblob NOT NULL, `PDFOutline_mimetype` varchar(64), `Subject` varchar(128) NOT NULL default '', `CourseNumber` varchar(10) NOT NULL default '', `Credits` int(5) NOT NULL default '0', `LastModified` timestamp NOT NULL default CURRENT_TIMESTAMP, PRIMARY KEY (`CourseID`) ) ENGINE=MyISAM DEFAULT CHARSET=latin1 COMMENT='Store courses' AUTO_INCREMENT=1 ; </code> #In a similar fashion, create the Program table. The resulting SQL for this table is:<code> CREATE TABLE `Program` ( `ProgramID` int(11) NOT NULL auto_increment, `ProgramName` varchar(64) NOT NULL default '', `ProgramDescription` text NOT NULL, `HTMLOutline` text NOT NULL, `PDFOutline` longblob NOT NULL, `PDFOutline_mimetype` varchar(32), `AdmissionDeadline` date NOT NULL default '0000-00-00', `LastModified` timestamp NOT NULL default CURRENT_TIMESTAMP, PRIMARY KEY (`ProgramID`) ) ENGINE=MyISAM DEFAULT CHARSET=latin1 COMMENT='Academic Program' AUTO_INCREMENT=1 ; </code> # The database has been created with 2 tables: Program and Course. We can now move on to building the Xataface application. ===Step 2: Create Xataface Application=== Our Xataface application will provide a user-friendly front-end to our database. A basic application consists of a directory with a configuration file and an entry page (PHP file). Xataface comes with a PHP setup script (called makesite) to create the skeleton for your application. Alternatively you can set up the application manually. Note: For the following instructions and examples, my Daface installation is located at /Users/shannah/Sites/dataface and the URL for the installation is http://localhost/~shannah/dataface. ====Method 1: Setting up application with the 'makesite' script==== # From the command prompt, navigate to the dataface directory. (in my case ''/Users/shannah/Sites/dataface''). # This directory contains a file named 'makesite'. It is a PHP script that can be used to build a website powered by Xataface. To find out the usage options for this script you can simply call the script with no parameters. E.g.,<code> stevepbook:~/Sites/dataface shannah$ ./makesite </code> # This will give you usage instructions for the script as follows:<code> makesite: invalid options entered. Usage: makesite <site_path> <db_user>:<db_pass>@<db_host>/<db_name> <dataface_url> or php makesite <site_path> <db_user>:<db_pass>@<db_host>/<db_name> <dataface_url> where <site_path> = The path (absolute or relative) to your application directory. <db_user> = The MySQL username to connect to the database <db_pass> = The User's password to connect to the database <db_host> = The MySQL host name. <db_name> = The name of the mysql database for the application. <dataface_url> = The URL to the Xataface installation Examples: makesite ../FacultyOfWidgetry root:password@localhost/FacultyOfWidgetry /dataface The above command would create a site at ../FacultyOfWidgetry (i.e., the Faculty of Widgetry directory in the parent directory. The database used for this site is located at localhost, and the database name is FacultyOfWidgetry. The username to connect to the database is root and his password is password. </code> # We create our FacultyOfWidgetry site using the following command:<code> ./makesite ../FacultyOfWidgetry \ root@localhost/FacultyOfWidgetry \ http://localhost/~shannah/dataface </code> # This will create our application in the FacultyOfWidgetry folder if everything worked ok. The contents of the folder will look like: <nowiki><br/></nowiki>[[Image:http://xataface.com/documentation/tutorial/getting_started/directory-structure-1.gif]] You may be wondering what these files. Here is the short version (Read the next section "Creating applications manually" for more detailed information about the contents of these files. The index.php file is the entry point for your application (i.e., you point the web browser at this file to use the application. The conf.ini file contains database connection settings and some other minor settings, like what should appear in the navigation menu. The tables/Program (tables/Course) directory can contain configuration files specific to the Program (Course) table. More on that later. # Point your web browser to the FacultyOfWidgetry directory to see the application: <nowiki><br/></nowiki>[[Image:http://xataface.com/documentation/tutorial/getting_started/basic-application-1.gif]] #Your application is now created. It will enable you to add, edit, delete, and find records in either the Course table or the Program table. There will be more on the basics of using this application in the next section. ====Method 2: Setting up application manually==== Using the makesite script as described above is the recommended way to set up an application because it saves time. However, it is very easy to set up the application manually. Just follow these steps: # Create a directory for the application somewhere in your web site (preferably outside your xataface directory). We will call our directory 'FacultyOfWidgetry'. ):<code> mkdir FacultyOfWidgetry </code> # Create a PHP file to serve as the access point for the application. Generally we will name this file 'index.php', but you can name it anything. Place the following contents in the index.php file:<code> <? require_once '/path/to/dataface/dataface-public-api.php'; df_init(__FILE__, 'http://yourdomain.com/dataface'); $app =& Dataface_Application::getInstance(); $app->display(); </code><nowiki><p>OK, I guess some explanations are in order.</p><p> The first line imports the all of the public functions for dataface from the dataface-public-api.php file.</p><p> The second line initializes the application for the current directory and specifies the URL to the dataface installation.</p><p> The third line obtains an instance to the Application object - the core of your Dataface application.</p><p> The fourth line simply displays the application.</p></nowiki> # Create a file named 'conf.ini' to contain database connection information. Its contents should be:<code> [_database] host = "localhost" user = "dbuser" password = "secret" name = "FacultyOfWidgetry" [_tables] Course = "Course" Program = "Program" </code><nowiki><p><b>Explanations:</b></p><p>There are 2 sections in this INI file: '_database', and '_tables'.</p><p> The '_database' section specifies the database connection information for the MySQL database.</p><p> The '_tables' section specifies which tables will be included in the navigation menu for the application.</p></nowiki> # At this point, the application is functional. However there is one more thing that should be done for security reasons. The conf.ini file contains sensitive password information and should not be served to the web. We will create an .htaccess file to tell Apache NOT to serve this (or any) .ini file. The .htaccess file should contain:<code> <FilesMatch "\.ini$"> Deny from all </FilesMatch></code> # The directory structure of your application will now look like: <nowiki><br/></nowiki>[[Image:http://xataface.com/documentation/tutorial/getting_started/basic-app-dir-structure-manual-1.gif]]<nowiki><p> Note, however, that there is also an .htaccess file that is hidden from this image.</p><p>You may be wondering why there is no 'tables' directory like the directory structure that was generated by the makesite script. The 'tables' directory is not required for the application to be functional. It will be required later on when we start to decorate the database.</p></nowiki> # The application is now ready to go. Point your web browser to the index.php file that you created. It will look like:<nowiki><br/></nowiki>[[Image:http://xataface.com/documentation/tutorial/getting_started/basic-application-1.gif]] ===Download source files=== [[File:http://xataface.com/documentation/tutorial/getting_started/facultyofwidgetry-4-tar.gz|Download the source files]] for this application at a tar.gz archive. These files reflect the state of the application at this point of the tutorial. As later sections make changes to the application you will be able to download those versions also. htaccess first application installation en GettingStarted:delegate_classes 80 Delegate Classes ==Delegate Classes== Use Delegate classes to add permissions, custom serialization, display filters, calculated fields, import/export functionality, and other custom functionality to your application. For many applications, the configuration files provide sufficient to make them fit the requirements. However, in some cases you may feel the need to "extend" or "bend" your application even more. For these situations, there are delegate classes. ===What is a delegate class?=== A delegate class is a PHP class that defines custom behavior, functions, and fields for a table in a Xataface application. A table may have only 1 delegate class. What kinds of things can a delegate class do? * Define permission rules for tables, records, and relationships. * Define calculated fields. * Define custom serialization/deserialization of fields (useful for XML storage) * Define custom event handlers (actions to be performed when certain events take place) * Define import / export filters. * Define custom titles for records * more ... ===How to create a delegate class=== I will describe the creation process with an example. Referring back to our FacultyOfWidgetry application, let's add a delegate class for the 'Program' table. This is done as follows: # Create a file named 'Program.php' in the Program table configuration directory (i.e., 'tables/Program/Program.php). Your application directory structure should now look like:<nowiki><br/></nowiki>[[Image:http://framework.weblite.ca/documentation/tutorial/getting_started/delegate-class-fs-1.gif]] # Add the following contents to your newly created 'Program.php' file:<code><? class tables_Program {} </code><nowiki><p> In other words, you are creating a class named 'tables_Program'. The above delegate class doesn't do anything yet, but it is a start. The fun part doesn't start until you start defining methods in your delegate class. There are prescribed interfaces that you will need to implement to make this work.</p></nowiki> ===Example 1: Creating a custom title for records=== The "Title" of a record is a string that represents the record. It is used by Xataface in the navigation controller (forward and back buttons) and in the "Jump" menu as well as various places around the interface for referring to that record. As an example, take a look at this partial screen shot of the 'details' tab in a Xataface application. [[Image:http://framework.weblite.ca/documentation/tutorial/getting_started/getTitle-1.gif]] I have circled the parts of the interface that use a record's title in some way. (1), (2), and (4) show the title of the current record and (3) shows the title of the next record in the found set. You will notice that the title is just the value of the first field in the Program record. In fact, the way that Xataface generates titles is by selecting the first VARCHAR or CHAR field in the table to be the Title for records of that table. In the above example this seems like a good choice, but it may not always be what you want. We can use our delegate class to customize the way that these titles are generated. By defining a method named getTitle(), we can customize the way that titles are generated. Let's add such a method to our delegate class as follows: <code> <? class tables_Program { function getTitle(&$record){ return $record->val('ProgramName').' Program'; } } </code> OK, you are probably wondering what this $record object is. The $record object is a Dataface_Record object that represents a record of the 'Program' table (if you want to take a look at the source code for this class it can be found in the 'Dataface/Record.php' file). This object allows you to access all of the information about the record so that you can generate a title for the record. The 'val' method simply returns the value of a field in the record. In the above example, we are telling Xataface that the title of all records of the 'Program' table is the value of the ProgramName field with the string 'Program' appended to it. For example, if the ProgramName of a record was 'Foo', then its title woud be 'Foo Program'. Lets take a look at our application now to see the changes that we have made. [[Image:http://framework.weblite.ca/documentation/tutorial/getting_started/getTitle-2.gif]] Notice that the (1) now has 'Program' appended to the end of the title, but (2) and (3) do not. This is because (2) and (3) are part of the result controller (for navigating through results in the table) and it needs to be able to load hundreds of record titles at a time, but the getTitle() method requires that the entire record be loaded into memory for it to work which would be unfeasible when we need the title of hundreds of records. The result controller titles can also be customized, however, using the titleColumn() method, which simply returns the name of the column that should be used as the title. It can also return MySQL clauses that are equivalent to a column name (e.g., CONCAT('FirstName', ' ', 'LastName') would be valid). Okay, let's add a titleColumn() method to our delegate class so that we can customize the way our records are represented in the result controller: <code> <? class tables_Program { function getTitle(&$record){ return $record->val('ProgramName').' Program'; } function titleColumn(){ return 'AdmissionDeadline'; } } </code> All that the titleColumn method does is return the name of a column to be used as the title for records of the 'Program' table. In this case, we making the 'AdmissionDeadline' field the title column which results in the result controller looking like this: [[Image:http://framework.weblite.ca/documentation/tutorial/getting_started/titleColumn-1.gif]] This was a simple example, but it is possible to do more with the titleColumn() method than just specify the name of a column. Any valid MySQL calculation that can be placed in a SELECT list can be returned here. For example, we can make use of the MySQL 'CONCAT' function to append the string 'Program' to the 'ProgramName' field and achieve the same results as our previous getTitle() method: <code> <? class tables_Program { function getTitle(&$record){ return $record->val('ProgramName').' Program'; } function titleColumn(){ return "CONCAT(ProgramName, ' Program')"; } } </code> And now we can see the changes in our application: [[Image:http://framework.weblite.ca/documentation/tutorial/getting_started/titleColumn-2.gif]] It may seem a little bit inconvenient to have to define 2 methods to effectively customize the title of a record. Future versions may attempt to address this issue so that one or the other can be implemented, but for now, both methods must be implemented to effectively customize the title. In addition, future versions will likely add the 'titleColumn' functionality to an INI file since it is more or less static. ===Summary=== In this section we learned how to add a delegate class to our tables to customize the behavior of our applications. Delegate class become more important when you need very fine-grained customizations to your application, as you will see in later sections. One important feature of delegate classes is the ability to add security permissions to tables and records to limit who can view, edit, and delete certain records. This will be covered in the next section. delegate classes,getTitle,getPermissions en GettingStarted:customizing 76 Customizing Field labels, descriptions, and widgets ==Customizing Field labels, descriptions, and widgets== Using simple INI configuration files, you can customize the look and feel of your application. You can change widgets, labels, field descriptions, and more. In the previous 2 sections we learned how to create a simple application by desiging a database and then installing the basic directory structure to make our application operational. Now it is time to "decorate" the application a little bit. Decoration occurs by way of simple configuration files that are placed in strategic locations in the application. We can customize such things as: * Widget types (e.g., use a select list for a field rather than a text field) * Labels (e.g., The ProgramName field's label can say "Program Name" instead of just "ProgramName") * Field Descriptions . You can add descriptions to fields to help explain their meaning and how to use the application. * HTML attributes. (e.g., Make a text field 50 characters wide) ===Table Configuration Directories=== You will recall, that when we used the 'makesite' script to generate the directory structure for our web application, it created a directory named 'tables', with subdirectories named after each of the tables in our database. The directory structure of the application looked like: [[Image:http://xataface.com/documentation/tutorial/getting_started/directory-structure-1.gif]] The 'tables/Program' and 'tables/Course' are refered to as "table configuration directories" . All of the configuration files a table in a Xataface application are stored in its associated table configuration directory. For example all configuration files for the 'Program' table are located in the 'tables/Program' directory. There are 4 main files that are generally contained in a table's configuration directory: * '''fields.ini''' - Contains configuration for the fields of the table (e.g., field labels, descriptions, widget types, etc...) * ''valuelists.ini''' - Contains value lists (vocabularies) that can be used in the table to limit input into certain fields like select lists. * '''relationships.ini''' - Defines the relationships between this table and other tables in the application. * '''<TableName>.php''' (where <TableName> is the name of the table. - A delegate PHP class that allows you to further customize the behavior of the application with respect to this table. May contain custom fields, importing/exporting functionality, permissions information, and more... ===Customizing Labels and Descriptions=== We will start off by adding custom labels and descriptions to the 'Program' table of our 'FacultyOfWidgetry' application. This sort of customization settings are placed in a file named 'fields.ini' inside the table's configuration directory. # Create the 'fields.ini' file in the Program table configuration directory (i.e., tables/Programs/fields.ini). # Add the following to this file:<code> [ProgramName] widget:label = "Program Name" widget:description = "Enter the name of the program" </code><nowiki><br></nowiki>Now look at the "Edit Record" form in the Xataface application: [[Image:http://xataface.com/documentation/tutorial/getting_started/program-name-label-1.gif]] Notice how the label for the "ProgramName" now says "Program Name" (note the space between "Program" and "Name"). And its description matches the description specified in the fields.ini file. The widget:label and widget:description attributes can be defined for any field in any table of the application. ===Using different widgets=== If no widgets are defined in the fields.ini file, a Xataface application will make a best guess at the type of widget that should be used to edit the value in a field. In general, the widgets used by default are as follows: * VARCHAR, CHAR, INT : html text field * DATE, DATETIME fields: calendar widget * TEXT fields : html text area * BLOB fields : html file upload field * INT Fields with "AUTO INCREMENT" : html hidden field * VARCHAR or CHAR fields with "Password" or "password" as part of the name : html password field * ENUM fields : html select list * SET fields : html checkbox group (not yet supported as of this writing). You can change the widget that is used to edit a field by specifying a "widget:type" attribute for the field in the fields.ini file. For more information about the available widgets, see [[widget:type]]. ====Example: Using HTML Editor to edit the HTMLOutline field==== Clearly the HTMLOutline field in the Program table is intended to store HTML content. By default our application only provides a text area to do the editing so the user is expected to enter the HTML markup by hand. It would be much better to provide the user with a WYSIWYG (What you see is what you get) HTML editor widget. That is exactly what we are going to do. We will add a section to the fields.ini file so that it now looks like: <code> [ProgramName] widget:label = "Program Name" widget:description = "Enter the name of the program" [HTMLOutline] widget:type = "htmlarea" </code> Now refresh the Xataface application in your web browser and look at the edit form for a record of the Program table: [[Image:http://xataface.com/documentation/tutorial/getting_started/htmlarea-1.gif]] As you can see, the HTMLOutline field now has an HTML Editor widget for editing. Most users will find this much nicer to work with than a normal text area. Xataface uses FCKEditor for its html editor widget. There are a number of widgets that can be specified in the [[widget:type]] parameter: * '''[[checkbox]]''' - An HTML checkbox (or checkbox group depending on context). * '''[[date]]''' - Month/Day/Year select lists for selecting dates. * '''[[calendar]]''' - A text field with a button that opens a small calendar widget when clicked. * '''[[group]]''' - A complex widget type for editing multiple values as a group (useful for XML fields) * '''[[hidden]]''' - a hidden field * '''[[password]]''' - An HTML password widget * '''[[select]]''' - An HTML select list (requires the 'vocabulary' attribute) * '''[[static]]''' - an uneditable field * '''[[table]]''' - A complex widget type for editing multiple values in a tabular format (Useful for XML fields) * '''[[text]]''' - an html text field * '''[[textarea]]''' - an html text area ===Changing HTML attributes of widgets=== Sometimes you may want even finer grained control of your widgets' appearance than to just specify the type, label, and desription. Perhaps you want to make a text field 50 characters wide, or to set the CSS class of the html element. This can be done using the 'widget:atts:' parameter for a field. A short example is the easiest way to explain how this works. Modify the fields.ini for the Program table so it looks like:<code> [ProgramName] widget:label = "Program Name" widget:description = "Enter the name of the program" widget:atts:size = 50 widget:atts:style = "font-size: 24pt; font-family: Apple Chancery" [HTMLOutline] widget:type = htmlarea </code> We have added 2 lines:<code> widget:atts:size = 50 widget:atts:style = "font-size: 24pt; font-family: Apple Chancery" </code> What this does is add the html attributes size="50" and style="font-size: 24pt; font-family: Apple Chancery" to the html text field that is used to edit the ProgramName field. Look at the results: [[Image:http://xataface.com/documentation/tutorial/getting_started/widget-atts-1.gif]] The HTML tag for the text field now looks like:<code> <input class="default" id="ProgramName" name="ProgramName" type="text" size="50" style="font-size: 24pt; font-family: Apple Chancery" value="Basic Widgetry" /> </code> In fact you can add arbitrary attributes to any of the fields using the same convention. Some useful examples are: * '''[[widget:atts:rows]]''' for text areas to set the number of rows of text they should display. * '''[[widget:atts:cols]]''' for text areas to set the number of columns (1 character = 1 column) You can even use javascript calls in here if you like: * '''[[widget:atts:onclick]]''' = "doJsFunction();" ===Download source files=== [http://xataface.com/documentation/tutorial/getting_started/facultyofwidgetry-6-tar.gz Download the source files] for this application as a tar.gz archive These source files reflect the state of the application at the current point of the tutorial. As changes are made to the application in later sections, downloads of those versions are made available for download also. ===Summary=== In this section we learned how to change the labels, descriptions, and widgets for fields. We also learned how to add HTML attributes to the widgets to achieve very fine-grained control over the display of our forms. widget labels descriptions onclick handlers en getResetPasswordEmailInfo 122 getResetPasswordEmailInfo Application Delegate Class Method Return to [[Application Delegate Class]] [[toc]] ===Synopsis=== Optional method to define the settings for the email that is sent to the user when they request to reset their password. Introduced in Xataface 1.3. Exists in 1.3 or higher. ===Signature=== <code> function getResetPasswordEmailInfo(Dataface_Record $user, string $reset_url){} </code> ===Parameters=== * '''$user''' - The Dataface_Record of the user whose password has been changed. * '''$reset_url''' - The URL where the user should go to reset their password. When they visit this URL they will receive a message saying that their password has been changed and the new password has been emailed to them. That subsequent email can be customized using the [[getPasswordChangedEmailInfo]] method. ===Returns=== This method should return an associative array with 0 or more of the following keys: * '''subject''' - The subject line of the email. * '''message''' - The message content of the email. * '''headers''' - The Email headers (as a string). * '''parameters''' - Extra parameters for the mail function. ==See Also== * [[getPasswordChangedEmailInfo]] - A delegate class method to define the email that is sent to the user once their password has been reset to a temporary password. It informs the user of their new temporary password and should include instructions on how to change their password to their own choice. This step immediately follows the reset password step. forgot password, reset password en getRegistrationActivationEmailSubject 18 getRegistrationActivationEmailSubject ==getRegistrationActivationEmailSubject() Hook== A hook that can be implemented in the [[Application Delegate Class]] or the [[Table Delegate Class]] to override the default registration activation email subject line (the email that the user receives when they register). ===Signature=== function getRegistrationActivationEmailSubject( Dataface_Record &$record, string $activationURL ) : string ====Parameters==== {| class="listing listing2" ! Name ! Description |- | &$record | A Dataface_Record object encapsulating the record that is being inserted in the users table for this registration. |- | $activationURL | The URL where the user can go to activate their account. |- | returns | Mixed. If this method returns a PEAR_Error object, then registration will fail with an error. |} ===Example=== <code> <?php class conf_ApplicationDelegate { function getRegistrationActivationEmailInfo(&$record, $activationURL){ reeturn 'Welcome to the site.. Activation required'; } } </code> ===See Also=== * [[beforeRegister]] * [[afterRegister]] * [[validateRegistrationForm]] * [[sendRegistrationActivationEmail]] * [[getRegistrationActivationEmailInfo]] * [[getRegistrationActivationEmailMessage]] * [[getRegistrationActivationEmailParameters]] * [[getRegistrationActivationEmailHeaders]] en 0 getRegistrationActivationEmailMessage 19 getRegistrationActivationEmailMessage ==getRegistrationActivationEmailSubject() Hook== A hook that can be implemented in the [[Application Delegate Class]] or the [[Table Delegate Class]] to override the default registration activation email message body (the email that the user receives when they register). ===Signature=== function getRegistrationActivationEmailSubject( Dataface_Record &$record, string $activationURL ) : string ====Parameters==== {| class="listing listing2" ! Name ! Description |- | &$record | A Dataface_Record object encapsulating the record that is being inserted in the users table for this registration. |- | $activationURL | The URL where the user can go to activate their account. |- | returns | Mixed. If this method returns a PEAR_Error object, then registration will fail with an error. |} ===Example=== <code> <?php class conf_ApplicationDelegate { function getRegistrationActivationEmailInfo(&$record, $activationURL){ return 'Thanks for registering. Please visit '.$activationURL.' to activate.'; } } </code> ===See Also=== * [[beforeRegister]] * [[afterRegister]] * [[validateRegistrationForm]] * [[sendRegistrationActivationEmail]] * [[getRegistrationActivationEmailInfo]] * [[getRegistrationActivationEmailSubject]] * [[getRegistrationActivationEmailParameters]] * [[getRegistrationActivationEmailHeaders]] en 0 getRegistrationActivationEmailInfo 17 getRegistrationActivationEmailInfo ==getRegistrationActivationEmailInfo() Hook== A hook that can be implemented in the [[Application Delegate Class]] or the [[Table Delegate Class]] to override the default information that is used to send the registration activation email (the email that the user receives when they register). This should return an associative array with the keys: * subject - The subject of the activation email. * message - The message body of the activation email. * parameters - The parameters to be used in the mail() function for the activation email. * headers - The headers to use in the mail() function for the activation email. ===Signature=== function getRegistrationActivationEmailInfo( Dataface_Record &$record, string $activationURL ) : array ====Parameters==== {| class="listing listing2" ! Name ! Description |- | &$record | A Dataface_Record object encapsulating the record that is being inserted in the users table for this registration. |- | $activationURL | The URL where the user can go to activate their account. |- | returns | Mixed. If this method returns a PEAR_Error object, then registration will fail with an error. |} ===Example=== <code> <?php class conf_ApplicationDelegate { function getRegistrationActivationEmailInfo(&$record, $activationURL){ return array( 'subject' => 'Welcome to the site.. Activation required', 'message' => 'Thanks for registering. Visit '.$activationURL.' to activate your account', 'headers' => 'From: webmaster@example.com' . "\r\n" . 'Reply-To: webmaster@example.com' . "\r\n" . 'X-Mailer: PHP/' . phpversion() ); } } </code> ===Example 2: Only override the subject=== <code> <?php class conf_ApplicationDelegate { function getRegistrationActivationEmailInfo(&$record, $activationURL){ return array( 'subject' => 'Welcome to the site.. Activation required' ); } } </code> ===See Also=== * [[beforeRegister]] * [[afterRegister]] * [[validateRegistrationForm]] * [[sendRegistrationActivationEmail]] * [[getRegistrationActivationEmailSubject]] * [[getRegistrationActivationEmailMessage]] * [[getRegistrationActivationEmailParameters]] * [[getRegistrationActivationEmailHeaders]] en 0 getPasswordChangedEmailInfo 121 getPasswordChangedEmailInfo Application Delegate Class Method Return to [[Application Delegate Class]] [[toc]] ===Synopsis=== Optional method to define the settings for the email that is sent to the user upon successful resetting of their password using the password reset function. Introduced in Xataface 1.3. Exists in 1.3 or higher. ===Signature=== <code> function getPasswordChangedEmailInfo(Dataface_Record $user, string $password){} </code> ===Parameters=== * '''$user''' - The Dataface_Record of the user whose password has been changed. * '''$password''' - The new temporary password that has been assigned to the user. ===Returns=== This method should return an associative array with 0 or more of the following keys: * '''subject''' - The subject line of the email. * '''message''' - The message content of the email. * '''headers''' - The Email headers (as a string). * '''parameters''' - Extra parameters for the mail function. ==See Also== * [[getResetPasswordEmailInfo]] - A delegate class method to define the email that is sent to the user when they request a password reset. This is the step that immediately precedes the Password Changed email step. forgot password, reset password en getNavItem 125 getNavItem Application Delegate Class Method Return to [[Application Delegate Class]] [[toc]] ===Synopsis=== The getNavItem() method of the application delegate class can be used to override the items that appear in the navigation menu (i.e. the menu that allows users to select the table via either tabs along the top or items along the side). It should return an associative array with characteristics of the navigation item including the href (i.e. link), label, and selected status. Using this method it is now possible to have non-table navigation items as well. You would just add these items to the \[_tables\] section of the [[conf.ini file]] then override the item using this method. '''Since 1.3''' ====How the Nav Menu Is Built==== Xataface builds the navigation menu by looping through each item in the [_tables] section of the conf.ini file, passing it to the getNavItem() method, and adding the resulting navigation item to the menu. If getNavItem() returns null, then that item will be skipped. If getNavItem throws an exception, then the default rendering for the menu item will take place. ===Signature=== <code> function mixed getNavItem( string $key, string $label ) throws Exception </code> ===Parameters=== * '''$key''' - The key of the nav item. In the case of a table, this would be the table name. * '''$label''' - The label of the nav item (may be overridden). ===Returns=== This method should return either: # An associative array with the properties of the nav item. # null to indicate that this nav item should be omitted altogether. (e.g. if the user shouldn't have permission for it). If returning an associative array, it should contain the following keys: * '''href''' - (String) The URL where this nav item should point. * '''label''' - (String) The label of this nav item. * '''selected''' - (Boolean) True if the nav item is currently selected. False otherwise. ===Throws=== If you want to signal Xataface to just use default rendering for the current navigation item you can just throw an exception. The default rendering will link to the table named ''$key'', and the item's label will be the same as ''$label''. ==Examples== Given the following conf.ini file: <code> ... [_tables] people=People books=Books accounts=Accounts reports=Reports ... </code> Suppose we want the navigation menu to only show the ''people'' and ''books'' options for regular users. Admin users can see all options. In addition, the 'reports' option doesn't correspond with a table of the database. Instead we are just going to link it to a custom action named 'reports'. Our getNavItem() method will look something like this: <code> function getNavItem($key, $label){ if (!isAdmin() ){ switch ($key){ case 'people': case 'books': // non-admin users can see these throw new Exception("Use default rendering"); } // Non-admin users can't see any other table. return null; } else { //Admin users can see everything.. $query =& Dataface_Application::getInstance()->getQuery(); switch ($key){ case 'reports': // reports is not a table so we need to return custom properties. return array( 'href' => DATAFACE_SITE_HREF.'?-action=reports', 'label' => $label, 'selected' => ($query['-action'] == 'reports') ); } // For other actions we need to make sure that they aren't selected // if the current action is reports because we want the 'reports' // tab to be selected only in that case. return array( 'selected' => ($query['-table'] == $key and $query['-action'] != 'reports') ); } } </code> ===See Also=== * [[isNavItemSelected]] - Overrides default behavior of whether a navigation item is currently selected. getNavItem, navigation menu en getFeedItem 41 getFeedItem ==getFeedItem() Delegate Class Method== [[toc]] ===Synopsis:=== The getFeedItem() method of a table [[Delegate class methods|delegate class]] returns an associative array of parameters for a record as it should appear as part of an [[Introduction_to_RSS_Feeds_in_Xataface|RSS feed]]. An RSS feed item consists of the following components: # '''title''' - The title of the record as it appears in the RSS feed. # '''description''' - The description of the record for the RSS feed. This is really the body of the RSS feed item. # '''link''' - The linkback URL if users want to know more about the record. # '''date''' - The date that the record was posted/modified. # '''author''' - The name of the person who posted this record. # '''source''' - URL to the site where record originated from. ===Parameters=== # '''Dataface_Record''' &$record - The record that is being represented in an RSS feed. ===Return Value=== The getFeedItem() method returns an associative array with the components of the RSS feed. This array does not need to contain all possible keys, or even any keys. Any keys that are omitted will simply use default values in the RSS feed. The array may contain the following keys: {| class="listing listing2" ! Name ! Description ! Version |- | title | The record title as it appears in RSS feeds. If this is omitted, the RSS feed will simply use the output of [http://dataface.weblite.ca/Dataface_Record Dataface_Record's] [http://dataface.weblite.ca/getTitle getTitle()] method. | 1.0 |- | description | The record description. This is used in the main body of the RSS feed. If this is omitted, the RSS feed will use an HTML table that shows all of the field data in the record. This value can also be overridden using the [[getRSSDescription]] method of the delegate class. | 1.0 |- | link | The URL to this record. If this is omitted it just points to the ''view'' tab for this record. However you can direct it anywhere you like. When the user clicks on the "More Info" link in his RSS reader it will direct him to this link. | 1.0 |- | date | The date that this record was posted or last modified. This is the date that an RSS reader will use to decide if it has already loaded the record yet. If this is omitted it will try the [http://dataface.weblite.ca/Dataface_Record Dataface_Record's] [http://dataface.weblite.ca/getLastModified getLastModified()] method to obtain the last modified date of the record. Failing that, it will use [http://dataface.weblite.ca/Dataface_Record Dataface_Record's] [http://dataface.weblite.ca/getCreated getCreated()] method to try to obtain the creation date of the record. This date should be a unix timestamp. | 1.0 |- | author | The name of the user who posted this record. If this is omitted, then it will try to use [http://dataface.weblite.ca/Dataface_Record Dataface_Record's] [http://dataface.weblite.ca/getCreator getCreator()] method. Failing that, it will use the value of the ''default_author'' parameter in the ''[_feed]'' section of the [[conf.ini file]]. If that is not defined, then it simply uses the string "Site Administrator". | 1.0 |- | source | The source URL where the feed is to have originated. If none is specified, then it will use the value of the ''source'' parameter in the ''[_feed]'' section of the [[conf.ini file]]. Failing that, it will simply use the URL to the application. Note that you can alternatively define this value using the [[getFeedSource]] method. | 1.0 |} ===Example=== <code> function getFeedItem(&$record){ return array( 'title' => "News Item: ".$record->getTitle(), 'description' => $record->display('News Body'), 'link' => $record->getPublicLink(), 'date' => strtotime($record->val('last_modified')), 'author' => $record->val('posted_by'), 'source' => 'http://www.example.com' ); } </code> '''Note that RSS feeds will work perfectly well without defining this method. This just allows you to customize one or more parameters of the RSS feed'''. ===See Also:=== * '''[[getFeed]]''' - A delegate class method available to both the [[Application Delegate Class]] and the [[Delegate class methods|table delegate classes]] to configure the RSS feed as a whole (not just for an individual item in the RSS feed. * '''[[getRelatedFeed]]''' - A [[Delegate class methods|delegate class method]] available to both the [[Application Delegate Class|application delegate class]] and the [[Delegate class methods|table delegate classes]] to configure the [[Introduction to RSS Feeds in Xataface|RSS feed]] for a related records list. * '''[[getRSSDescription]]''' - A delegate class method to override the description that appears for a particular record in an RSS feed. (The same as the ''description'' parameter of the [[getFeedItem]] method. * '''[[Introduction to RSS Feeds in Xataface]]''' - An overview of Xataface's RSS feed support. en 0 getFeed 42 getFeed ==getFeed() Delegate Class Method== [[toc]] ===Synopsis:=== The getFeed() method of a table [[Delegate class methods|delegate class]] or [[Application Delegate Class|application delegate class]] returns an associative array of parameters to configure the [[Introduction_to_RSS_Feeds_in_Xataface|RSS feed]] for a particular table . An RSS feed consists of the following components: # '''title''' - The title of the RSS feed as it should appear in the subscribers' feed list. # '''description''' - Describes the RSS feed. # '''link''' - A link to the RSS feed # '''syndicationURL''' - The URL to this RSS feed's site. ===Parameters=== # '''array''' $query - The HTTP query. Contains information like the current table, current action, and search parameters. This allows you to customize your RSS feed depending on the user's query parameters. ===Return Value=== The getFeed() method returns an associative array with the components of the RSS feed. This array does not need to contain all possible keys, or even any keys. Any keys that are omitted will simply use default values in the RSS feed. The array may contain the following keys: {| class="listing listing2" ! Name ! Description ! Version |- | title | The title for the RSS feed. If this omitted, it will try to use the ''title'' directive of the ''[_feed]'' section of the [[conf.ini file]]. Failing that, it will try to generate an appropriate title for the feed depending on the current query. | 1.0 |- | description | A Description for this RSS feed. If this is omitted, it will try to use the ''description'' directive of the ''[_feed]'' section of the [[conf.ini file]]. | 1.0 |- | link | A link to the source page of the RSS feed. If this is omitted, it will try to use the ''link'' directive of the ''[_feed]'' section of the [[conf.ini file]]. | 1.0 |- | syndicationURL | A link to the source page of the RSS feed. If this is omitted, it will try to use the ''syndicationURL'' directive of the ''[_feed]'' section of the [[conf.ini file]]. | 1.0 |} ===Example=== <code> function getFeed(&$query){ return array( 'title' => "RSS feed for the ".$query['-table']." table.", 'description' => "News and updates for automobiles", 'link' => df_absolute_url(DATAFACE_SITE_HREF), 'syndicationURL' => df_absolute_url(DATAFACE_SITE_HREF) ); } </code> '''Note that RSS feeds will work perfectly well without defining this method. This just allows you to customize one or more parameters of the RSS feed'''. ===See Also:=== * '''[[getFeedItem]]''' - A delegate class method available to both the [[Delegate class methods|table delegate classes]] to configure parameters for the particular items of the RSS feed. * '''[[getRelatedFeed]]''' - A [[Delegate class methods|delegate class method]] available to both the [[Application Delegate Class|application delegate class]] and the [[Delegate class methods|table delegate classes]] to configure the [[Introduction to RSS Feeds in Xataface|RSS feed]] for a related records list. * '''[[getRSSDescription]]''' - A delegate class method to override the description that appears for a particular record in an RSS feed. (The same as the ''description'' parameter of the [[getFeedItem]] method. * '''[[Introduction to RSS Feeds in Xataface]]''' - An overview of Xataface's RSS feed support. en 0 getChildren 126 getChildren Delegate Class Method Return to [[Delegate class methods]] [[toc]] The getChildren() method can be implemented in a table's delegate class to specify the logical "child" records of a given record which can be used when creating hierarchical applications. This method will effectively override the output of the Dataface_Record::getChildren() method for records of this table. ===Signature=== <code> function getChildren( Dataface_Record $record) : Dataface_Record[] </code> ===Parameters=== # '''$record''' - The Dataface_Record that is the subject of the query ===Returns=== This method should return an array of Dataface_Record objects that are considered to be children of the subject record. ===Examples=== <code> function getChildren($record){ return df_get_records('webpages', array( 'parent_id'=>'='.$record->val('webpage_id') ) ); } </code> ==See Also== * '''[[getParent]]''' - A Delegate class method to return the logical parent of a given record. getChildren Delegate class method en filter 27 filter ==The filter attribute of the [[fields.ini file]]== The filter attribute with a value of 1 specifies that a field should be used as a filter field in list view. In list view, any filter fields will provide a select list with all of the possible values in that field. Selecting one of the items in this list will filter the results to only show records of that value. ===Example 1: Year, Make, Model=== The Fuel Economy Database has three fields with filter=1 : Year, Make, and Model. I.e., in their fields.ini file we have something like: <code> [Year] filter=1 [Make] filter=1 [Model] filter=1 </code> This causes 3 select lists to appear in list view. See the application [http://fueleconomydb.com/index.php?-action=list here] and notice the select lists for Year, Make, and Model just above the list of results. If you are filtering on a field where an ID is stored in the DB but you are using a vocabulary to associate it with a value, then it will still be sorted on the ID. If you want to sort on value then you should add a [[Grafted fields|grafted field]] with the value using the __sql__ directive of the fields.ini file, then use that grafted field as your filter field, like the following: <code> __sql__ = "select a.*, b.foo_name from a left join b on a.foo_id=b.foo_id" [foo_name] filter=1 </code> en 0 file 89 ==Dynamic select boxes== To create two select boxes whose one is dependent (slave) of the other (master), we need to use some javascript with Jason. Create the valuelists.ini: <code> ;valuelist for the slave [slaves_list] __sql__ = "select slave_id, slave_name, master_id from slaves" ; valuelist for the masters [masters_list] __sql__ = "select master_id,master_name from masters" </code> fields.ini: <code> [master] vocabulary=masters_list [slave] vocabulary=slaves_list </code> delegate class in the table directory : <code> ... function block__after_new_record_form(){ echo <<<END <script language="javascript"><!-- var slave_field= document.getElementById('slave'); var master_field = document.getElementById('master'); END; // Let's get all the slaves available. $app =& Dataface_Application::getInstance(); $query =& $app->getQuery(); $table =& Dataface_Table::loadTable($query['-table']); $slaves = $table->getValuelist('slaves_list'); $slave_masters = $table->getValuelist('slaves_list__meta'); // Note that the slaves_list__meta valuelist is automatically created // because we had three columns in the slaves valuelist. // The first and third columns effectively create a 2nd valuelist // named 'slaves_list__meta' // $slaves is an array with keys slave_id and values slave_name // slave_masters is an array with keys slave_id and values master_id import('Services/JSON.php'); $json =& new Services_JSON(); // A JSON encoder to allow us to easily // convert PHP arrays to javascript arrays. echo ' var slaves_options = '.$json->encode($slaves).'; var slaves_master = '.$json->encode($slave_masters).'; '; echo <<<END master_field.onchange = function(){ var selected_master = master_field.options[master_field.selectedIndex].value; slave_field.options.length = 0; var index = 0; for ( slave_id in slaves_options){ if ( selected_master == slaves_master[slave_id] ){ slave_field.options[index++] = new Option(slaves_options[slave_id], slave_id); } } }; //--></script> END; } // Also place this javascript after an edit record form... function block__after_edit_record_form(){ return $this->block__after_new_record_form(); } </code> en field__pushValue 105 [[toc]] The field__pushValue() delegate class method can be used to transform a field value as entered in the edit form into a format that can be stored in the database.. Sometimes it is the case that we want users to be able to work with data differently than it is stored in the database. This method should always be accompanied by a corresponding [[field__pullValue]] method which performs the inverse operation and is used to transform the value in the database into a format that can be edited in the edit form. ===Example=== Given a field ''start_ip'' that stores an IP address in the database as an unsigned INT, we want to be able to work with the data on the edit form in a friendlier format - the standard IP address dot notation, so we define pullValue and pushValue methods for the field in the table's delegate class. <code> class tables_ip_blocks { /** * @param Dataface_Record $record The record we are pushing the value * into * @param HTML_QuickForm_element $el The QuickForm widget that we are * retrieving the value from. */ function start_ip__pushValue($record, $el){ $val = ip2long($el->getValue()); if ( $val !== false ){ return sprintf('%u', $val ); } return null; } function start_ip__pullValue($record, $el){ $val = $record->val('start_ip'); if ( $val ) return long2ip($val); return $val; } } </code> ==References== * [[Delegate class methods]] * [[Application Delegate Class]] * [[http://dataface.weblite.ca/Dataface_Record Dataface_Record API docs] * [http://xataface.com/documentation/how-to/how-to-define-custom-serialization-for-fields How to define custom serialization for fields] - A how-to document. pullValue, pushValue en field__pullValue 104 field__pullValue delegate class method [[toc]] The field__pullValue() delegate class method can be used to transform database from the database for use in an edit/new record form. Sometimes it is the case that we want users to be able to work with data differently than it is stored in the database. This method should always be accompanied by a corresponding [[field__pushValue]] method which performs the inverse operation and is used to transform the value in an edit form into a format that can be stored in the database. ===Example=== Given a field ''start_ip'' that stores an IP address in the database as an unsigned INT, we want to be able to work with the data on the edit form in a friendlier format - the standard IP address dot notation, so we define pullValue and pushValue methods for the field in the table's delegate class. <code> class tables_ip_blocks { /** * @param Dataface_Record $record The record we are pushing the value * into * @param HTML_QuickForm_element $el The QuickForm widget that we are * retrieving the value from. */ function start_ip__pushValue($record, $el){ $val = ip2long($el->getValue()); if ( $val !== false ){ return sprintf('%u', $val ); } return null; } function start_ip__pullValue($record, $el){ $val = $record->val('start_ip'); if ( $val ) return long2ip($val); return $val; } } </code> ==References== * [[Delegate class methods]] * [[Application Delegate Class]] * [[http://dataface.weblite.ca/Dataface_Record Dataface_Record API docs] * [http://xataface.com/documentation/how-to/how-to-define-custom-serialization-for-fields How to define custom serialization for fields] - A how-to document. pushValue, pullValue en