calendar 100 Calendar Widget Back to [[widget:type]] [[toc]] ===Synopsis=== The calendar widget is the default widget for editing date and datetime fields. It is javascript pop-up calendar that allows users to select date and time visually. It can be configured to allow different date and time formats, themes, starting days of the week, and more. [[image:http://media.weblite.ca/files/photos/calendar_widget.png?max_width=400]] ===Usage=== For DATE and DATETIME fields, the calendar widget is the default widget used, so you need not specify it explicitly in the fields.ini file. For other types of fields you may designate them to use the calendar widget in the [[fields.ini file]] as follows: <code> [my_field] widget:type=calendar </code> ===Configuration Options=== The calendar widget supports some configuration options that can be set in the [[fields.ini file]]. These options are as follows: {| class="listing listing2" |- ! Name ! Description ! Default ! Version |- | [[widget:lang]] | The language to use for the calendar. This is a 2-digit ISO language code. | en | 0.5.3 |- | [[widget:theme]] | The theme to use for the calendar. It only ships with one theme at present. | calendar-win2k-2 | 0.5.3 |- | [[widget:firstDay]] | The first day of the week (e.g. Monday=1) | 1 | 0.5.3 |- | [[widget:showsTime]] | Boolean value indicating whether the calendar should show the time as well. | 0 for DATE fields, 1 for DATETIME fields. | 0.5.3 |- | [[widget:ifFormat]] | The input format of the date. This takes a formatting string as supported by [http://ca2.php.net/strftime the strftime function]. | %Y-%m-%d %I:%M %P | 0.5.3 |- | [[widget:timeFormat]] | Whether to use 12 hour or 24 hour time format. | 12 | 0.5.3 |} ===Examples=== ====Setting the time to use 24 hour format==== In your [[fields.ini file]]: <code> [my_field] wiget:type=calendar widget:timeFormat = 24 </code> ===See Also=== * [[date]] Widget - A widget for editing date and time using select drop-down lists. * [[time]] Widget - A widget for selecting time from a set of possibilities in a single select list. calendar widget, fields.ini file, widget:type en documentation_guide 70 Documentation Guide Xataface uses a wiki to manage its online documentation which can be edited by anyone. All you have to do is [http://xataface.com/wiki/index.php?-action=login login with your forum username and password] ([http://xataface.com/forum/profile.php?mode=register register for the forum here]). Then when you are browsing a page of the wiki, you'll see an 'Edit' tab along the top. Click on this tab to start editing the page in your browser. Wiki markup is a little simpler than HTML and a little more complex than plain text. It is easy to get a handle on once you get started. If you aren't sure how to format it exactly how you want, don't worry. Someone may come by after you and improve on your formatting. That's what the community approach is all about. ==The Documentation Team== Join the Xataface documentation team to help participate in the planning of the documentation. If you want to help out, contact [mailto:steve@weblite.ca Steve Hannah] and he'll add you to the documentation group where you can access the private documentation forums and meet the rest of the team. ==Using the Wiki== The following is a brief guide in using the Xataface Wiki. All following instructions assume that you are already [http://xataface.com/wiki/index.php?-action=login logged in] to the wiki. You can use your forum username and password to login. ===Editing an Existing Page=== # Navigate to the page that you want to edit # Click on the "Edit" tab along the top. # Make changes to your page. # Save the changes. ===Adding a New Page=== ====Method 1: Add a link from an existing page=== # Navigate to an existing page that you want to link to your new page. # Click on the "Edit" tab along the top. # Somewhere in the content of the page, add a link to your new page (which doesn't exist yet), by adding the following markup<code> [[The name of your new page]] </code> # Save your changes. # Click on the "view" tab along the top and find the place where you added your link. It should be displayed with a '?' right after it. Click on the '?' and it will bring you to the "new page form". # fill in the form with your page contents and click save. ====Method 2: Accessing new page form directly==== # Access the [http://xataface.com/wiki/index.php?-action=new&-table=wiki new page form] directly. ===Uploading Images=== Image can be uploaded at [http://media.weblite.ca The Web Lite Media Manager]. You'll need an account to access this site. If you are a member of the documentation team you can request an account from [mailto:steve@weblite.ca Steve Hannah] so that you can upload images here. Steps: # Log into [http://media.weblite.ca the Web Lite Media Manager]. # Click on "Add New File" in the menu on the left. # Select a name for the file, and browse to the image you want to upload in the file upload field. You don't need to check any category boxes. Press save. # Click on the "View" tab for your newly uploaded image. # Copy the embed code for the image from the "Embed Code" field. # In the wiki page add the embed code where you want your image to appear as follows:<code> [[Image:EMBED_CODE]] </code> Where EMBED_CODE is the URL for the image as you copied and pasted out of the media manager. # Save your changes. ===Uploading Video=== ===Adding Source Code Snippets=== documentation wiki en GettingStarted:Introduction 71 Introduction Web Lite is a simple framework for building data-driven web applications in PHP and MySQL. This section introduces some of the concepts and applications of Dataface. To fully understand what Xataface is, we must first define a few key terms: '''Framework''' - A set of software routines that provide a foundation structure for an application. Frameworks take the tedium out of writing an application from scratch. (From Answers.com) '''Data-driven design'''- Designing an application around the data that it will store. Xataface is a ''Framework'' in the sense that it is a set of classes and libraries that take the tedium out of writing web applications. It provides a simple web interface to a MySQL database enabling users to update, delete, and find data in the underlying database. The interface is targeted at secretaries and end-users as opposed to database administrators. Xataface enables ''data-driven design'' because it allows developers to develop web sites by first designing the database that will be used to store the data on the website, and then design the pages used to display the data. The developer can focus on the data because he or she does not have to worry about having to build forms to update the data. If the requirements of the application change, the developer can simply add a field to the database table and all associated web forms will be updated automatically (because they are all dynamically generated using the database schema). ===Requirements=== * [http://php.net PHP] >= 4.3 * [http://mysql.com MySQL] >= 3.2.3 ===Key Technologies=== * [http://pear.php.net PEAR class libraries] (HTML_QuickForm, etc...) * [http://smarty.net Smarty Templating Engine] * [http://plone.org Plone] Javascript and CSS style sheets ===Development Procedures=== # Identify the data that will need to be stored for a web site. ##[[Image:http://xataface.com/documentation/tutorial/getting_started/er-diagram.png]] # Design the database using your favorite database administration program (e.g., PHPMyAdmin) ##[[Image:http://xataface.com/documentation/tutorial/getting_started/phpMyAdmin-1-small.gif]] # Tell Xataface some DB connection info, and voila! You have an application: ##[[Image:http://xataface.com/documentation/tutorial/getting_started/new-record-form-1-small.gif]] ===Where to go from here=== This tutorial will teach you the basics of Xataface and how to construct a simple application using the Xataface. After reading this tutorial you will be ready to tackle some medium to large web sites with the help of the Xataface reference documentation. You are also encouraged to mail the [http://xataface.com/forum Xataface forum] if you have questions. introduction requirements getting started en GettingStarted:Why_Use_Xataface 72 Why Use Xataface ==Why Use Xataface?== Some simple examples similar to those that are frequently encountered by web developers, and how dataface can be used to acheive a solution. As a web services developer in the Faculty of Applied Sciences at Simon Fraser University, I am frequently getting requests to build websites that are manageable by the site owner. Most of these requests also specify certain types of content that must be stored on the website, and much of this content needs to be n-ary (i.e., there will be multiple instances of each type of content). Let me give you an example. ===Example 1: Website for Faculty of Widgetry=== The Faculty of Widgetry needs a website to publish information about its undergraduate programs. It is important for them to be able to publish admission requirements, and program overviews for each program. It is also important to have course outlines and timetables for each course. The Faculty of Widgetry has 12 undergraduate programs and over 100 courses offered. ====Solution 1: Static HTML==== To build this web site using only static HTML pages using Dreamweaver or some other HTML editor would require at least 112 pages to be created (one for each course and program). However, once we recognize that there are only 2 types of pages required (one for courses and one for programs), we can reduce the task down to creating 2 templates and filling in the main content for each program and course individually. Most HTML editors have some templating ability so you can make changes to the template and have the changes propogated to all pages that use that template with the click of a button. This works great, but courses are added frequently, and outlines are changed. Do you really want to receive requests to update all of these pages every time there are changes to make? (If your answer is 'yes', then you probably won't be interested in reading the rest of this tutorial). Whether the Dean of the faculty knows it or not, it is very important for the program assistants to be able to update these web pages on their own. To acheive these goals you can: * Install Dreamweaver on the Program Assistants' computers, teach them how to use it, and allow them to perform updates. * Install Contribute, which is a scaled down version of Dreamweaver to make it easier for the Program Assistants to edit the content. * Use another solution that is equivalent to one of the above 2 solutions. Installing Dreamweaver for each Program Assistant is a little overkill, and since it has the ability to do much more than just update content. In addition, Dreamweaver is really a developer's tool - not a secretary's tool, so it can be difficult to learn at first. The best reason NOT to install Dreamweaver on the Program Assistant's computer, however, is that it enables him/her to muck things up by accident (believe me, I has happened to me more times than I care to count). Admittedly, Contribute is a viable option as it controls access to only certain portions of web pages to be edited, and it is targetted at secretaries (not developers) so it is easier to use. In fact, given the requirements for this web site (as stated above), this is a perfectly good solution. However you better hope that none of the following requirements are added: * Each program web page should contain an up-to-date list of all of the courses required for the program, along with a link to the course outline for that course. * Course outlines should be available in PDF format as well as HTML format. * An index page showing all of the courses available should be added. This page must allow courses to be organized by program, course subject, or course number. * Any other requirement that would have information formatted in more than one way. If any of these requirements are likely to be added (EVER) then you would be well-advised to look into solutions that use a database back-end. ====Solution 2: Use a Content Management System (CMS)==== There are hundreds of content management systems available that will allow you to store and update content through the web (TTW). Some of them even have an assortment of add-ons that will allow you to store more specific types of information. Some good CMS's include Plone, Drupal, and Xoops. Suppose we want to develop the Faculty of Widgetry website using one of these CMS's. Any good CMS will allow you to create and edit HTML documents easily (without having to write any custom products). However, it is often the case that our documents require the content to be structured. For example, each program has some common data associated with it: Program Name, Admission Deadline, Program Description, Outline, Courses, etc... If we want to properly separate data from presentation, we would need to build a special content-type to store our programs. Most CMS's allow you to develop custom content-types using the underlying programming language and an API (Application Programming Interface). Some API's are easier to use than others and some are documented better than others. The common element is that each has its own proprietary interface for writing these add-ons. If you are using a CMS and you are proficient in the creation of add-on content-types, then you will be able to build the Faculty of Widgetry website without great difficulty. However there are a number of reasons why you may choose NOT to use a CMS: * Steep learning curve: Depending on the CMS it can be very time consuming and difficult to learn how to use and modify the CMS to suit you purposes. * It is over-kill: Most CMS's are filled with features and modules that you will never need. In fact it can even be a pain to turn them off if you don't want them. * You can get tied into the CMS: When you are using a CMS, you will start developing for the CMS. With all of your content in the CMS it may be difficult to migrate to a different solution later on. (The truth of this statement will vary for different CMS's). Choose your CMS carefully. ====Solution 3: Use an existing Application==== OK, OK, let's not get too carried away with trying to develop the website until we have checked the market to see if someone else has already done it better. Maybe there is already a PHP application that makes websites for Faculties easy. I mean, I can't be the first person that needed to build a website for a Faculty. In fact if you do a search or go to Hotscripts.com, you will probably find a handful of applications or scripts that almost do what you need. If you're lucky, maybe you can find an application that does exactly what you need (but frankly, I've never been that lucky). If you find one, maybe it's worth taking it for a test drive. But beware. Using a system that almost does what you need but is difficult to modify to your needs can be worse than building it by scratch. Make sure that you are able to modify the application to suit your needs exactly. ====Solution 4: Use PHP and MySQL==== If all we want to do is separate the data from the presentation and allow the Program Assistants to update data on the website, why not just design a MySQL database with the appropriate tables and fields to store the required data. In our case we will need 2 tables: '''Programs''': * Fields: ** ProgramID : int ** ProgramName : varchar ** ProgramDescription: text ** AdmissionDeadline: date ** Outline_HTML : text ** Outline_PDF : blob '''Courses''': * Fields: ** CourseID : int ** CourseSubject : varchar ** CourseTitle : varchar ** CourseNumber : int ** ProgramID : int ** CourseDescription : text ** Outline_HTML : text ** Outline_PDF : blob Now it's easy to create a few web pages that extract data from the database and displays it as HTML. In fact if there is an existing page template that you can use for the header and footer, you can develop the entire Faculty website in under an hour (you just have to create 3 pages). '''Question''': How will the Program Assistants update the information in the database? '''Answer''': OK, let's assume that you're not going to teach them SQL and that a DB Admin tool will also be too difficult to learn. Then you have to create HTML forms to update records in the database. Ouch! What was easy just became hard. Making HTML forms is a real pain, because you have to validate the input, deal with file uploads, and also make sure that everything is stored to the database OK without losing any information. Such a basic task, but it can be very difficult. This is when it is time to use Xataface. ====Solution 5: Use Xataface==== OK, this isn't really its own solution. It is more like "Solution 4 Part II", because Xataface is intended to complement your custom application you built with solution 4, by providing an easy-to-use, configurable user interface that is targeted at secretaries and normal users (as opposed to database administrators). A Xataface application takes only seconds to set up and it will provide you with a full user interface for your users to edit information in the database. introduction motivation why en 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: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: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 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: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: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: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: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 Creating_Printable_Reports 82 Creating a Custom Printable Report ==Creating a Printable Report== [[toc]] It is often useful to provide your users with a printable report that is generated from your database. Although Xataface doesn't include an explicit reporting module to allow the end users to create their own reports, you (the developer) can still quite easily produce a report by creating a custom action. This report will be subject to the user's sorting and searching preferences. E.g. if the user searches for only books about "frogs", then when he clicks on your printable report it will only display those records that match the query (i.e. only books about frogs). ===Requirements for our report=== # Report will be run against the "products" table (using the WebAuction application). # Report should be accessible by clicking an icon in the top right of the list view (i.e. the resultlist actions). # Report should display the product ID, product name, photo, and description. One product per page. ===Adding the Icon to our Application=== We'll start out by finding an appropriate icon to use for our action. There are loads of free icons that you can download (please observe and respect the license agreement of any icon library that you use). Two good free icon libraries include: # [http://www.famfamfam.com/lab/icons/silk/ FamFamFam Silk Icons] # [http://tango.freedesktop.org/Tango_Icon_Library Tango Icon Library] Once you have found the icon you want to use, just upload it somewhere inside your application's directory. It might be a good idea to create a directory to store your images if you haven't already. An appropriate name might by ''images''. For this example, we'll use the [[Image:http://dev.weblite.ca/phpimageserver/photos/icons/printer.png]] icon from the FamFamFam icon library. So we upload this icon to %APPLICATION_PATH%/images/printer.png Next we need to create an entry in our application's [[actions.ini file]] so that Xataface knows about our action, and where we want its icon to be displayed. We'll start out with a basic definition that just specifies the icon for the action, and the ''category'' of the action. <code> [printable_report] icon="{$site_url}/images/printer.png" category=result_list_actions description="See this product list in a printable format" </code> The ''result_list_actions'' category setting means that the icon for our action will be included along with the result list actions, which are located in the top right corner in the list tab. Now if we reload our application and look at the "list" tab, you'll see that the icon group in the top right now includes our icon: [[Image:http://media.weblite.ca/files/photos/Picture%20-5.png?max_width=640]] If you don't see this icon, but see the text "printable_report" instead, then you have entered an incorrect path to the icon in the ''icon'' directive. If you don't see an icon at all or any text, then your ''category'' directive may be incorrect. Check that it is exactly "result_list_actions". If you mouse over your icon you'll see the text that you specified as your ''description'' directive for the action: [[Image:http://media.weblite.ca/files/photos/Picture%20-6.png?max_width=640]] You'll notice, if you try to click on your icon, that nothing happens. This is because we haven't yet specified a URL for your action. We'll wait to specify our URL, until we've built the back-end of our action (i.e. the actual report). ===Creating the Actual Report=== Most reports involve the following pieces: # Fetch the found set of records from the database. # Loop through the found set and output some information about each record. # Optionally use a template to integrate the report into your application's look and feel. All reports will be placed in the framework of a custom Xataface action. In our case we add a file to our application ''actions'' directory named after our action: %APPLICATION_PATH%/actions/printable_report.php with the following contents: <code> <?php class actions_printable_report { function handle(&$params){ echo "Hello world!!!"; } } </code> Please note the following about this snippet: # The action was placed in a file ''actions/printable_report.php'' because the action is named ''printable_report'' (referring to our definition in the ''[[actions.ini file]]''. If the action was named ''foo'', then we would place our action in file ''actions/foo.php''. # The ''printable_report.php'' file contains a single class named ''actions_printable_report'' after the name of the action. # The action class contains a single method ''handle'' which handles the request for the action (i.e. outputs the report the way we like). This method must exist and me named exactly ''handle''. # The ''handle'' method takes a single ''&$params'' parameter which contains some parameters that may be passed to the action. We won't be dealing with these in this example. Before proceeding, let's try accessing our action just to make sure that we're on the right track. Point your browser to http://example.com/yourapplication/index.php?-action=printable_report Note that you don't point our web browser directly to your action php file (in the ''actions'' directory. Rather you point it to your application's entry point (index.php file), and specify the action via the ''-action'' GET parameter. Your web browser should display something like: [[Image:http://media.weblite.ca/files/photos/Picture%204.png?max_width=640]] If you get a blank white screen, then you should check your error log to see where the error is occuring. See [[Troubleshooting]] for general Xataface troubleshooting strategies in this case. Now that we have all of the formalities out of the way, we can proceed to meat of our report. ====Retrieving the Found Set==== Let's build onto our action now. First we will load the found set of records as follows: <code> <?php class actions_printable_report { function handle(&$params){ $app =& Dataface_Application::getInstance(); $query =& $app->getQuery(); if ( $query['-table'] != 'products' ){ return PEAR::raiseError('This action can only be called on the Products table.'); } $products = df_get_records_array('products', $query); } } </code> Things to note in this snippet: # We start be loading a reference to the ''Dataface_Application'' object. # We then use the ''Dataface_Application'' object to load the current query. This is essentially an associative array of all of the GET parameters, but with some guaranteed attributes such as ''-table'' and ''-action''. # In our particular action we are designing it to only work for the ''products'' table so we do a check on the query parameters to make sure that this is the case. If someone tries to run this action from outside the products table (e.g. if -action=foo) then an error will be displayed. # We use the df_get_records_array() function to return all matching records on the products table. It returns an array of [[Dataface_Record]] objects. ====Overriding -skip and -limit==== Xataface allows the user to specify the number of records to display and the position in the found set to start from by adding the ''-skip'' and ''-limit'' GET parameters to a request. If these are omitted, then default values of 0 and 30 are used respectively. You may notice that if you click "Next" in list view, you see '-skip' and '-limit' parameters automatically added to the URL. ''df_get_records_array'' respects the -limit and -skip parameters that are specified in the query. I.e. if -skip and -limit are omitted it will return only the first 30 records from the found set. If -skip=1 and -limit=10 then it will return 10 records starting from the 2nd record (2nd becuase -skip=0 would point to the first record). This may be desired behavior for your report, but in some reports you may want to print off the entire found set. If this is the case, you will want to explicitly set the -skip and -limit parameters in the ''$query'' array before passing it to ''df_get_records_array''. E.g.: <code> $query =& $app->getQuery(); $query['-skip'] = 0; $query['-limit'] = 10000; $products = df_get_records_array('products', $query); </code> ====Looping through and Printing Product Info==== Now comes the fun part. We're just going to loop through our found set and print off the product information: <code> foreach ($products as $p){ echo '<table>' .'<tr><th>Product ID</th><td>'.$p->htmlValue('product_id').'</td></tr>' .'<tr><th>Product Name</th><td>'.$p->htmlValue('product_name').'</td></tr>' .'<tr><th>Description</th><td>'.$p->htmlValue('product_description').'</td></tr>' .'<tr><th>Photo</th><td>'.$p->htmlValue('product_image').'</td></tr>' .'</table>'; } </code> The entire action at this point will look like: <code> <?php class actions_printable_report { function handle(&$params){ $app =& Dataface_Application::getInstance(); $query =& $app->getQuery(); $query['-skip'] = 0; $query['-limit'] = 10000; if ( $query['-table'] != 'products' ){ return PEAR::raiseError('This action can only be called on the Products table.'); } $products = df_get_records_array('products', $query); foreach ($products as $p){ echo '<table>' .'<tr><th>Product ID</th><td>'.$p->htmlValue('product_id').'</td></tr>' .'<tr><th>Product Name</th><td>'.$p->htmlValue('product_name').'</td></tr>' .'<tr><th>Description</th><td>'.$p->htmlValue('product_description').'</td></tr>' .'<tr><th>Photo</th><td>'.$p->htmlValue('product_image').'</td></tr>' .'</table>'; } } } </code> Now we refresh our action in the web browser, or point the browser again to: http://example.com/yourapplication/index.php?-action=printable_report&-table=products It should display something like: [[Image:http://media.weblite.ca/files/photos/Picture%205.png?max_width=640]] If you get a blank white screen, please check out the [[Troubleshooting]] section for general Xataface troubleshooting strategies. ====Adding a Little Style==== It is a good idea to at least provide the proper HTML HEAD and BODY tags for your report. And to help make things a little nicer looking we're going to add some CSS styles to: # Make the table field labels vertically aligned to the top. # Change the font to helvetica. This is easy to do with simple echo statements: <code> echo '<html><head>' .'<title>Printable Report</title>' .'<style type="text/css">' .' th { vertical-align: top}' .'</style>' .'</head>' .'<body>'; //... </code> So our finished action looks like: <code> <?php class actions_printable_report { function handle(&$params){ $app =& Dataface_Application::getInstance(); $query =& $app->getQuery(); $query['-skip'] = 0; $query['-limit'] = 10000; if ( $query['-table'] != 'products' ){ return PEAR::raiseError('This action can only be called on the Products table.'); } $products = df_get_records_array('products', $query); echo '<html><head>' .'<title>Printable Report</title>' .'<style type="text/css">' .' th { vertical-align: top}' .'</style>' .'</head>' .'<body>'; foreach ($products as $p){ echo '<table>' .'<tr><th>Product ID</th><td>'.$p->htmlValue('product_id').'</td></tr>' .'<tr><th>Product Name</th><td>'.$p->htmlValue('product_name').'</td></tr>' .'<tr><th>Description</th><td>'.$p->htmlValue('product_description').'</td></tr>' .'<tr><th>Photo</th><td>'.$p->htmlValue('product_image').'</td></tr>' .'</table>'; } echo '</body></html>'; } } </code> ===Connecting the Icon to the Action=== FInally it is time to connect our Icon to our Action. We do this by adding a ''url'' directive for the action in the ''[[actions.ini file]]'': <code> [printable_report] icon="{$site_url}/images/printer.png" category=result_list_actions description="See this product list in a printable format" url="{$app->url('-action=printable_report')}" </code> Explanation of the ''url'' directive in this snippet: * The ''url'' method of the ''[[Dataface_Application]]'' object is used to generate a URL with the user's current query settings, but with the ''-action'' parameter set to ''printable_report''. Now if we reload our application, go to the list tab of the ''products'' table and click on our icon, it should take us to our action: [[Image:http://media.weblite.ca/files/photos/Picture%207.png?max_width=640]] ===Trying out the action on different found sets with different sort orders=== One of the cool things about this action is that it is tied directly into the Xataface find settings so that th user is able to search for a subset of products and run our report on only those products that were found. The user can also perform a sort on any column and this sort will be respected by our report. ===Hiding Icon from Other Tables=== Since our action is only intended to operate on the ''products'' table it probably isn't a good idea to make the icon visible for every other table. For example, if you go to the list view of the ''users'' table, you'll see the printer icon in the top right just like it appears for the ''products'' table. Clicking on it should display our error: [[Image:http://media.weblite.ca/files/photos/Picture%206.png?max_width=640]] We will use a ''condition'' directive for our action to hide it from tables other than the ''products'' table as follows: condition="$query['-table'] == 'products'" So our action will now look like: <code> [printable_report] icon="{$site_url}/images/printer.png" category=result_list_actions description="See this product list in a printable format" url="{$app->url('-action=printable_report')}" condition="$query['-table'] == 'products'" </code> Now if you reload the list for the ''users'' table you'll notice that the printer icon is now gone. But returning to the ''products'' table shows our action still alive and well. ===Locking Down our Action with Permissions=== In our case we don't want our action to be accessible to all users. Only administrators. Xataface permissions and all its possibilities are beyond the scope of this tutorial, but we still want to demonstrate how to lock down this action. The WebAuction application into which this action is being installed defines a permission called ''reports'' which only administrators have. We will use this permission to limit access to this action as follows in the actions.ini file: permission=reports So the actions.ini file will now look like: <code> [printable_report] icon="{$site_url}/images/printer.png" category=result_list_actions description="See this product list in a printable format" url="{$app->url('-action=printable_report')}" condition="$query['-table'] == 'products'" permission=reports </code> Now only administrators will see our icon, and if non-administrators attempt to access out action by typing in its URL directly, they will receive an "Access Denied" message. en Key 83 fields.ini Directive: Key The '''Key''' directive is used only when the table is a view and you need to explicitly define which columns are part of the primary key. For example, if we created a view on the books table to only show books in a given year as follows: <code> create view books_2000 as select * from books where year='2000' </code> And we wanted to use this view as a table in our Xataface application we would need to tell it that the primary key of this view is the book_id field. So in the fields.ini file we would add: <code> [book_id] Key=PRI </code> Note that this is case sensitive. key=PRI will not work. ===Compound Primary Keys=== For primary keys comprising multiple columns we would add this directive for each field in the key. E.g. if our books_2000 view had 2 fields in the primary key, say author_id and book_index, we would have in the books_2000 fields.ini file: <code> [author_id] Key=PRI [book_index] Key=PRI </code> Links: * [http://xataface.com/forum/viewtopic.php?f=4&t=6723 Lookup widget on view with compound primary key] Return to [[fields.ini file]] Key, Views, MySQL Views, Create View, PRI, Primary Keys en http://xataface.com/documentation/how-to/site_with_backoffice_How_to_build_a_site_with_a_backoffice_ 84 A site with a backoffice ==A site with a backoffice== To create a site with a backoffice for the administrator, so that the visitors do not have to log in to read the pages, you add this code in the ApplicationDelegate.php file in the conf directory : <code> function getPermissions(&$record){ if ( isAdmin() ) return Dataface_PermissionsTool::ALL(); else return Dataface_PermissionsTool::READ_ONLY(); } </code> en http://xataface.com/documentation/how-to/site_with_backoffice 85 How to build a site with an optional login form ==How to build a site with an optional login form== To publish a public site with data without any need to login to access, here is the code : <code> function getPermissions(&$record){ if ( isAdmin() ) return Dataface_PermissionsTool::ALL(); else return Dataface_PermissionsTool::READ_ONLY(); } </code> In this way, you still can login to administrate your data. en site_with_backoffice 86 ==How to build a site with an optional login form== To publish a public site with data without any need to login to access, here is the code : <code> function getPermissions(&$record){ if ( isAdmin() ) return Dataface_PermissionsTool::ALL(); else return Dataface_PermissionsTool::READ_ONLY(); } </code> In this way, you still can login to administrate your data. en sql_delegate_method 87 __sql__ Delegate Method return to [[Delegate class methods]] ===Synopsis=== The __sql__ delegate class method can be defined in any delegate class to specify the SQL query that should be used to fetch records for a given table. This method overrides the [[__sql__]] directive of the fields.ini file. This strategy is primarily used to graft columns from another table onto the base table. =====Use Caution===== This is an advanced feature and, if used incorrectly, can muck up your application. Make sure that your SQL query includes a superset of the columns in the base table, and is a row-for-row match for the rows in the base table. I.e. you should never use an internal join. Always use a left join so that all of the rows of the base table are returned even if the join table doesn't have a corresponding row. If you want to simply filter a table's records, and don't need to graft any additional columns onto the table, you should use the [[setSecurityFilters]] method. ===Example=== Given the table foo, its delegate class: <code> class tables_foo { function __sql__(){ return "select f.*, c.category_name from foo f left join categories c on f.category_id=c.category_id"; } } </code> This effectively grafts a column "category_name" onto the foo table based on a join with the categories table. __sql__, SQL queries, delegate class en secure 88 secure fields.ini directive [[fields.ini file]] directive used only with [[container fields]]. If this flag is set, then the field contents will be treated in a secure manner and will obey the application permissions. If this directive is not set, then uploaded files in [[container fields]] are served directly by the web server without considering application permissions. Setting this directive will cause the application use a special get_blob action to serve the uploaded file, and this obeys application permissions. ==Example== Given a field to upload a PDF report, your [[fields.ini file]] section for this field might be something like: <code> [pdf_report] Type=container allowed_extensions="pdf" savepath="uploads" url="uploads" </code> Now if we upload a file named "foo.pdf" in this field, it will be uploaded to: http://www.example.com/path/to/myapp/uploads/foo.pdf Now we change the field definition to use the secure directive: <code> [pdf_report] Type=container allowed_extensions="pdf" savepath="uploads" url="uploads" secure=1 </code> In this case it will still upload files to the ''uploads'' directory, but all of the links generated in the Xataface interface (and via the ''display()'' and ''htmlValue()'' methods) will be for a URL like: http://www.example.com/path/to/myapp/index.php?-action=getBlob&-table=mytable&-field=pdf_report&record_id=10 Which will serve up the PDF file as an attachment. ===Restricting Direct Access to uploads directory=== Note: You still need to restrict access to the uploads directory or it may be possible for users to still guess the absolute URL to files in it. You can restrict access by placing an .htaccess file in the uploads directory (if you are using Apache) with the following contents: <code> deny from all </code> If you are using IIS or another web server you should look into the methods available for you to restrict access to directories. ===HTTP Response Codes=== The [[getBlob action]] will return the following HTTP Response Codes: * '''404''' - If either the record does not exist, or the record's specified container field is empty. * '''403''' - If the current user doesn't have permission to access this record. * '''500''' - If there is another error. The actual error will be written to the error log. secure,fields.ini file en 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 Dynamic_select_boxes 90 ==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> The 2.0 version has a [http://xataface.com/dox/modules/depselect/latest| depselect module] to produce cascading dynamic select boxes very simply. en setSecurityFilters 91 setSecurityFilter() method == Example == In the delegate class for the users table: <code> <?php class tables_users { function init(&$table){ if ( !isAdmin() ){ $table->setSecurityFilter(array('group_id'=>10)); } } } </code> This will only set the filter on non-admin users (assuming that you have defined a function isAdmin() to tell you if the current user is an admin user. en Authenticating_Against_the_PHPBB_Users_table 92 Authenticating Against the PHPBB Users Table Return to [[authentication]] [[toc]] Xataface is able to use the PHPBB users table to authenticate against so that, you can allow your users to log into your Xataface application using the same credentials as they use to access your PHPBB message forum. Achieving this level of integration requires 2 simple steps: # Set up the [[_auth]] section of your [[conf.ini file]] to reference the PHPBB users table and the correct username and password columns. # Specify the correct encryption on the password column. This step will be different for different versions of PHPBB. ==PHPBB 2== PHPBB version 2 and lower simply use MD5 encryption on the password column, which Xataface supports natively via the [[encryption]] directive of the [[fields.ini file]]. Therefore we can set up our Xataface application to authenticate against our PHPBB2 database ('''assuming that our PHPBB is set up in the same database as our Xataface app''') by doing the following: # Set up the [_auth] section of the [[conf.ini file]] as follows:<code> [_auth] users_table = phpbb_users username_column = username password_column = user_password </code> # Set up the user_password field to use md5 encryption in the ''tables/phpbb_users/fields.ini'' file <code> [user_password] encryption=md5 </code> That's it! Now you should be able to log into your Xataface application using the username/password from PHPBB. ==PHPBB 3== PHPBB version 3 and higher uses a custom encryption function for the password column so it is a little more complicated (but not that much). Step one (the [[conf.ini file]]) is the same as for PHPBB version 2 listed above. The 2nd part, however, requires us to implement a custom serialization for the user_password field. So the steps are below: # Set up the [_auth] section of the [[conf.ini file]] as follows:<code> [_auth] users_table = phpbb_users username_column = username password_column = user_password </code> # Implement the user_password__serialize() method in your phpbb_users delegate class (i.e. the ''tables/phpbb_users/phpbb_users.php'' file):<code> <?php class tables_phpbb_users { function user_password__serialize($password){ $itoa64 = './0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz'; $sql = "select user_password from phpbb_users where username='".addslashes($_POST['UserName'])."'"; $res = mysql_query($sql, df_db()); if ( !$res ) throw new Exception(mysql_error(df_db())); $row = mysql_fetch_assoc($res); mysql_free_result($res); $hash = $this->_hash_crypt_private($password, $row['user_password'], $itoa64); return $hash; } /** * The crypt function/replacement */ function _hash_crypt_private($password, $setting, &$itoa64) { $output = '*'; // Check for correct hash if (substr($setting, 0, 3) != '$H$') { return $output; } $count_log2 = strpos($itoa64, $setting[3]); if ($count_log2 < 7 || $count_log2 > 30) { return $output; } $count = 1 << $count_log2; $salt = substr($setting, 4, 8); if (strlen($salt) != 8) { return $output; } /** * We're kind of forced to use MD5 here since it's the only * cryptographic primitive available in all versions of PHP * currently in use. To implement our own low-level crypto * in PHP would result in much worse performance and * consequently in lower iteration counts and hashes that are * quicker to crack (by non-PHP code). */ if (PHP_VERSION >= 5) { $hash = md5($salt . $password, true); do { $hash = md5($hash . $password, true); } while (--$count); } else { $hash = pack('H*', md5($salt . $password)); do { $hash = pack('H*', md5($hash . $password)); } while (--$count); } $output = substr($setting, 0, 12); $output .= $this->_hash_encode64($hash, 16, $itoa64); return $output; } /** * Encode hash */ function _hash_encode64($input, $count, &$itoa64) { $output = ''; $i = 0; do { $value = ord($input[$i++]); $output .= $itoa64[$value & 0x3f]; if ($i < $count) { $value |= ord($input[$i]) << 8; } $output .= $itoa64[($value >> 6) & 0x3f]; if ($i++ >= $count) { break; } if ($i < $count) { $value |= ord($input[$i]) << 16; } $output .= $itoa64[($value >> 12) & 0x3f]; if ($i++ >= $count) { break; } $output .= $itoa64[($value >> 18) & 0x3f]; } while ($i < $count); return $output; } } </code> PHPBB, authentication, security, authentication modules en Authenticating_Against_the_Joomla!_Users_Table 93 Xataface is able to use the joomla users table to authenticate against so that, you can allow your users to log into your Xataface application using the same credentials as they use to access your joomla website. Achieving this level of integration requires 2 simple steps : 1 - Set up the [_auth] section of your conf.ini file to reference the joomla users table and the correct username and password columns. 2 - Create a delegate class for the joomla users table to be able to decrypt the password set in the table. ==Configure the conf.ini file== Joomla users table is named jos_users. So you have to declare this table in the conf.ini file. <code>[_auth] users_table = jos_users username_column = username password_column = password</code> Note that username_column and password_column are very simple... ==Create a delegate class for your users table== Now we have to create a delegate class for the users table to decrypt the passwords set in joomla. Joomla uses a custom md5 encryption. ===Joomla encryption=== When a user is setting a password in joomla, the system does several things : 1 - generate a random key containing alphanumeric characters example : <code>8NdiRqLRKLHaNwudJ3InJknsew9sc7pL</code> 2 - concate the clear entered password with the random key example : <code>password8NdiRqLRKLHaNwudJ3InJknsew9sc7pL</code> 3 - doing a md5 encryption on the result string example : <code>md5(password8NdiRqLRKLHaNwudJ3InJknsew9sc7pL = f2b1fb3996442db549c1ed1a1eebbfe1</code> 4 - concate the md5 string with the random key separated by ":" example : <code>f2b1fb3996442db549c1ed1a1eebbfe1:8NdiRqLRKLHaNwudJ3InJknsew9sc7pL</code> So it's a great encryption but xataface doesn't know how to do that. Here is the utility of the delegate class. We will define a function inside which could compare the entered password in xataface with the joomla stored password. ===Creating the delegate class=== 1 - Add a jos_users directory in your directory table 2 - Create a jos_users.php file inside this new directory ===Creating the decrypt password function=== Before posting this code, I would like to thank fantomasdm who created this function. So here is the code of the function to paste directly in the jos_users delegate class : <code><? class tables_jos_users { function password__serialize($password){ $app =& Dataface_Application::getInstance(); $query = "SELECT id, gid, block, password, usertype FROM jos_users where username='".$_POST['UserName']."'"; $result = mysql_query($query,$app->db()) or die("Query failed" . mysql_error() ); $line = mysql_fetch_array($result, MYSQL_ASSOC); mysql_free_result($result); $arraypass=explode(":", $linea['password']); $key=$arraypass[1]; $ret = md5(trim($password).$key).":".$key; return $ret; } } ?></code> Save your file and test the result. Enjoy ! ;-) joomla authentication md5 en fieldname__validate 94 fieldname__validate Delegate Class Method Return to [[Delegate class methods]] [[toc]] ===Synopsis=== Xataface allows you to add validation on any particular field in table by adding a fieldname__validate method to the table's delegate class of the form: <code> function myfield__validate(&$record, $value, &$params){ if ( $value != 'Steve' ){ $params['message'] = 'Sorry you must enter "Steve"'; return false; } return true; } </code> ===Parameters=== * &$record : A [http://dataface.weblite.ca/Dataface_Record Dataface_Record] object encapsulating the record we are validating. Note that the values of this object correspond with the submitted values from the form, and not necessarily the actual values of the record in the database. * $value : The value that is being inserted. * &$params : An output array that can be used to pass back a message if validation fails. You would set this array's 'message' parameter to be a message. ===Returns=== Returns a boolean value. True if the value is ok and false if validation failed. ===See Also=== * [[validators]] - For simple validation rules you can use the [[validators|validator:VALIDATOR_NAME]] directive of the [[fields.ini file]]. * [http://xataface.com/documentation/tutorial/getting_started/validation Form Validation] - Section on form validation in the Getting Started tutorial. validate, validation, delegate class validation, custom validator en validators 95 validators:NAME fields.ini directive Return to [[fields.ini file]] [[toc]] ===Synopsis=== In the fields.ini file you can specify validation rules to be applied to any field by adding the validators:NAME directive in that field's section of the [[fields.ini file]]. ===Available Validators=== {| class="listing listing2" |- ! Name ! Description ! Value ! Version |- | required | Field is required | 1 | All |- | maxlength | Maximum number of characters allowed. | $length | All |- | minlength | Minimum number of characters allowed. | $length | All |- | rangelength | Range (min and max) characters allows | $min,$max | All |- | email | Input must be syntactically correct email address. | 1 | All |- | emailorblank | Accepts an email address or a blank field. | 1 | All |- | regex | Input must match the provided regular expression. | A regular expression | All |- | lettersonly | Input must contain only letters (i.e. [a-zA-Z] | 1 | All |- | numeric | The input must contain a valid positive or negative integer or decimal number. | 1 | All |- | nopunctuation | The input must not contain any of these characters: <nowiki>( ) . / * ^ ? # ! @ $ % + = , " ' &gt; &lt; ~ [ ] { }.</nowiki> | 1 | All |- | nonzero | The input must not begin with zero. | 1 | All |- | uploadedfile | The element must contain a successfully uploaded file. | 1 | All |- | maxfilesize | The uploaded file must be no more than $size bytes. | $size | All |- |filename | The uploaded file must have a filename that matches the regular expression $file_rx. | $file_rx | All |} ===Examples=== To make a the first_name field required we add the following to the [[fields.ini file]]: <code> [first_name] validators:required=1 </code> '''Note that fields that are declared NOT NULL in the database are required by default.'''. If you wanted to remove the ''required'' validator from a field that is NOT NULL in the database you would add the following to the [[fields.ini file]]: <code> [first_name] validators:required=0 </code> ===See Also=== * [[fieldname__validate]] - For more complex validation you can define the [[fieldname__validate]] method in the [[Delegate class methods|Table Delegate Class]]. * [http://www.devarticles.com/c/a/Web-Graphic-Design/Using-HTML-Quickform-for-Form-Processing/12/ HTML_QuickForm article] going over HTML_Quickform validation. Dataface's forms are built on HTML_QuickForm. * [http://xataface.com/documentation/tutorial/getting_started/validation Form Validation] - Section from getting started tutorial introducing form validation in a tutorial format. validation, form validation, validators,validator:name en validators:VALIDATOR_NAME:message 96 validators:VALIDATOR_NAME:message directive for the fields.ini file Return to [[fields.ini file]] [[toc]] ===Synopsis=== If you want to customize the error message associated with a particular [[validator|validation rule]] you can use the validators:VALIDATOR_NAME:message directive in the fields.ini file. ===Format=== <code> [myfield] validators:VALIDATOR_NAME:message = MESSAGE </code> ===Examples=== If you don't like the default error message that is displayed when you make the first_name field required, you can customize it with your own message. E.g. <code> [first_name] validators:required=1 validators:required:message = "Please enter your first name" </code> ===See Also=== * [[validators]] - The [[fields.ini file]] directive for adding a validation rule to a field. This directive must be used in conjunction with [[validators]]. * [[fieldname__validate]] - For more complex validation rules you can define them in the table delegate class. * [http://xataface.com/documentation/tutorial/getting_started/validation Form Validation] - Section in the Getting Started tutorial on form validation. validation messages,error messages,form validation rules en _auth 97 _auth section of the conf.ini file [[conf.ini file|Return to conf.ini file]] [[toc]] ===Synopsis=== The ''_auth'' section of the conf.ini file includes configuration directives to enable authentication in a Xataface application. For more information about authentication and registration see [[authentication]]. This section may include the following directives: ===Directives=== {| class="listing listing2" |- ! Directive ! Description ! Required ! Default ! Version |- | users_table | The name of the table that contains your user accounts. | Yes | None | 0.6 |- | username_column | The name of the column that stores the username. | Yes | None | 0.6 |- | password_column | The name of the column that stores the password. | Required if using basic authentication. | None | 0.6 |- | auth_type | Specifies the authentication module that is being used. E.g. basic, cas, ldap, http, facebook, etc... | No | basic | 0.6 |- | allow_register | Flag to enable user registration. If this is set to 1, then a ''register'' link will appear below the login form. | No | 0 | 0.8 |- | session_timeout | Number of seconds of inactivity after which the user will be logged out. Note: Arithmetic don't work in the conf.ini, use seconds. | No | 86400 (=> 24*60*60 (24 hours)) | 1.3rc4 |} ===See Also=== * [[authentication]] - Overview of Xataface Authentication * [[conf.ini file]] - Directives available in the conf.ini file. _auth,authentication,conf.ini file,allow_register en registration_form 98 Setting up User Registration [[toc]] ===Synopsis=== Xataface optionally enables you to allow users to register for an account in your application. If your ''users'' table includes a column for email, it will also perform email validation before the account is activated. Before tackling user registration, it is good to have an understanding of Xataface's [[authentication]] and [http://xataface.com/documentation/tutorial/getting_started/permissions permissions] faculties. ===Enabling Registration=== To enable registration, simply add the following to the ''[[_auth]]'' section of the [[conf.ini file]]: <code> allow_register=1 </code> e.g. after adding this, your ''[[_auth]]'' section might look like: <code> [_auth] users_table=users username_column=username password_column=password allow_register=1 </code> After doing this, you'll notice a little ''Register'' link below the login form. [[Image:http://media.weblite.ca/files/photos/Picture%2036.png?max_width=640]] Clicking on this link will produce a registration form for the user which is essentially a "New Record" form on your ''users'' table. [[Image:http://media.weblite.ca/files/photos/Picture%2037.png?max_width=640]] Some features of this registration form include: * Checks to ensure that the username is unique * If the users table contains an ''email'' field, it will use the user-entered address for email validation before activation is complete. ===Setting up Permissions to Support Registration=== '''Xataface <= 1.2.4''': You must ensure that unlogged-in users have permission to add new records to the ''users'' table. This means that your getPermissions() method on the users table should, at least, provide the ''new'' permission. In addition these users must be granted the ''register'' permission in order to be able to register to begin with. '''Xataface >= 1.2.5''': You no longer need to provide the ''new'' permission to allow users to register. You simply need to provide the ''register'' permission. ====Sample Permissions on Users Table==== In the tables/users/users.php file (assuming my ''users'' table is actually named "users") <code> class tables_users { function getPermissions($record){ if ( isAdmin() ) return null; $perms['register'] = 1; return $perms; } } </code> '''Note that this example is only applicable for Xataface 1.2.5 or higher. In Xataface 1.2.4 you needed to provide users with the ''new'' permission rather than the ''register'' permission, which opens up a small security hole since users could potentially just use the "new" action if they new the URL and by-pass the registration and activation email altogether'''. Some notes on this example: * The isAdmin() function is not part of Xataface. It is used as a bit of *magic* here to reduce code. It is supposed to simply return true if the currently logged in user is an admin. Hence if the user is an admin, this method defers to the Application Delegate class's permissions (i.e. this method should not affect administrators). * We are giving all users (logged in or not) the register permission which enables them to register for an account on the system. * Generally you will want to restrict permissions on some of the fields in the users table. E.g. users should not be able to set their role or access level when they register. You can define more fine-grained permissions on these fields using the [[fieldname__permissions]] method of the users table delegate class (per the following example). ====Restricting Permissions on Particular Fields==== You probably don't want users to be able to set their access level when the register for an account, and your "users" table will quite often contain some field like "role" which stores this information. So the previous example is not quite realistic. You will also need to restrict permissions on the "role" field (and any other fields that you want to prevent users from setting themselves. <code> function role__permissions(&$record){ if ( isAdmin() ) return null; return Dataface_PermissionsTool::NO_ACCESS(); } </code> This will cut off the user's ability to set their own role when they register. You will likely want to set the default role value either in the mysql table definition or in the [[beforeInsert]] trigger. ===Email Validation=== As mentioned above, registration works by sending an activation email to the address specified in the user's registration. This email contains a link back to the ''activate'' action of your Xataface application, which will create the user account and log the user in. This implies that your ''users'' table must store an email address for your users. If you add a field named ''email'' to the ''users'' table, Xataface will assume that you mean to use this field as the user's email address, and thus, for email validation. However you can override this functionality and use *any* field as an email field by setting the ''email'' directive of the appropriate field in the [[fields.ini file]] for the ''users'' table. '''Example: Assigning the my_addr field of the users table to be used for email validation''': In the tables/users/fields.ini file: <code> [my_addr] email=1 </code> ====Disabling Email Validation==== 99% of the time, email validation is the preferred way of ensuring that people who register are who they say they are. You may, however, prefer to let users register directly without requiring the email activation step. You can disable email validation by overriding the ''register'' action in the [[actions.ini file]] as follows: In your application's [[actions.ini file]]: <code> [register > register] email_validation=0 </code> After setting this, the user account will automatically be created, and the user logged in upon saving the registration form. ===Triggers: Overriding Registration Workflow=== Xataface provides a number of triggers in the [[Application Delegate Class]] to override and extend the behavior of the user registration and activation process. For a list of available triggers see [[Application Delegate Class#registration]]. ===Preventing Spam with CAPTCHA=== One problem with enabling automatic registration is that it invites SPAM in the form of bots that can learn how to automatically register for user accounts and then leave unwanted input into your application. The Xataface [[reCAPTCHA module]] allows you to avoid these problems to some extent by forcing users who aren't logged in to fill a CAPTCHA field in order to successfully submit the form. This is especially helpful for registration forms. After installing the [[reCAPTCHA module]] the registration form will include a CAPTCHA field like the one depicted below: [[Image:http://media.weblite.ca/files/photos/Picture%2038.png?max_width=640]] For more information about the reCAPTCHA module [[reCAPTCHA module|click here]]. registration form, _auth, authentication en