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: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: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: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: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 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 checkbox 69 checkbox ==The checkbox widget== In the [[fields.ini file]] you can specify a field to be edited using a checkbox widget by setting [[widget:type]] to [[checkbox]]. A checkbox widget can function in 2 different ways depending on the parameters that you assign to the field. [[toc]] ===Example 1: A TinyInt (boolean) field=== Suppose our table has a tinyint field named "Active" which specifies whether the record is currently in use. This field will store a value of either 0 or 1. So we configure this field in our [[fields.ini]] file to use a checkbox widget as follows: <code> [Active] widget:type=checkbox </code> Results: [[Image:http://media.weblite.ca/files/photos/Picture%2024.png?max_width=640]] ===Example 2: A repeating field (multiple checkboxes for one field=== Checkboxes can store multiple values in a single field by setting the [[vocabulary]] directive and applying it to a varchar or text field. In this case there will be one value saved per line. In this example, suppose we have a varchar field named '''categories''' which uses the '''categories''' [[valuelist]] to specify the different categories that can be checked at any given time. Our [[valuelists.ini file]] might look like: <code> [categories] __sql__ = "select id,name from categories" </code> And our [[fields.ini file]] looks like: <code> [categories] widget:type=checkbox vocabulary=categories </code> * Note that you don't need to name the field the same as the valuelist. It just worked out this way. Now if we save a record with categories 1, 3, and 5 checked, then the categories column of our row in the database will store something like: <code> 1 3 5 </code> i.e. one category id per line. Note that using this method, your database will not be normalized because you are storing multiple values in a single field. However in many applications this is sufficient. Results: [[Image:http://media.weblite.ca/files/photos/Picture%2025.png?max_width=640]] ===Example 3: Using a "Categories" relationship=== """(Note: This example requires Xataface version 1.2 or higher)""" Example 2 above shows how we can easily add and remove a record from multiple categories using checkboxes. However it required multiple pieces of information to be stored in a single database field which may or may not be advantageous for your database design. If you're looking for a more normalized database schema you would probably design your database as follows for this case: # Books table - Stores all of the books. # Categories table - Stores all of the categories # Book_Categories table - Stores mapping of books to categories. With out table structure we will first want to define a relationship from Books to Categories to reflect the connection between books and categories. The [[relationships.ini file]] for this might look like: <code> [categories] Books.Book_ID="$Book_ID" Book_Categories.Category_ID=Categories.Category_ID </code> And our [[fields.ini file]] for the Books table might look like: <code> [categories] widget:type=checkbox transient=1 relationship=categories </code> * Note that there is no need for our field to be named the same as our relationship. It just turned out this way. Also note that we used the transient=1 flag here because the Books table no longer has a categories field in the database. This field is defined purely for the benefit of the edit form so that we will get a checkbox group to select the book's categories. Results: [[Image:http://media.weblite.ca/files/photos/Picture%2025.png?max_width=640]] ==Related Parameters== # [[vocabulary]] - Assigns a valuelist to be used as the options for this checkbox group. # [[repeat]] - A boolean value indicating whether this field should be treated as a 'repeating field'. A repeating field is one with multiple checkboxes. By default the checkbox widget operates as a single checkbox that controls a boolean value. # [[relationship]] - (Only applicable to [[transient]] fields). If the [[relationship]] directive is set then this field can be used to add/remove records from a relationship. en 0 relationship 68 The relationship fields.ini directive [[fields.ini file|Return to fields.ini file directives]] [[toc]] ===Synopsis=== Certain types of widgets (e.g. grid (v1.0) and checkbox (v1.2)) support the relationship directive which allows them to effectively add/remove records from a specified relationship. This directive only works with transient fields. ===Example 1: Checkboxes to add/remove categories=== (Note: This example requires Xataface 1.2 or higher to work) Suppose we have a database that keeps track of courses and the branch of research that they belong to. A course can be part of multiple branches. We want to be able to select the branches that a particular course belongs to on the edit form for that course using checkboxes. Table Structure: <code> courses: course_id : int (primary key) course_title : varchar branches: branch_id : int (primary key) branch_name : varchar branch_description: text course_branches: course_id : int branch_id : int </code> Relationship definition: (from the tables/courses/[[relationships.ini file]]): <code> [branches] course_branches.course_id="$course_id" course_branches.branch_id=branches.branch_id </code> Field definitions: (from tables/courses/[[fields.ini file]]): <code> [branches] transient=1 relationship=branches widget:type=checkbox </code> Things to notice: # This is a many-to-many relationship (hence the need for the course_branches join table. # The [branches] field is a transient field. # The relationship directive from the [[fields.ini file]] references our branches relationship that was defined in the [[relationships.ini file]]. # You can call the field anything that you like. There is no need for it to have the same name as the relationship. It just turned out that way in this example. ===Example 2: Using a grid widget=== Let's modify example 1 slightly to use a grid widget instead of checkboxes. The grid widget will allow us edit the records in a relationship using dynamic table. It automatically uses the correct widget for each column of the table according to the definition in the target table's [[fields.ini file]]. Most of the definition can remain the same. We only change the [[fields.ini file]] directive: <code> [branches] transient=1 relationship=branches widget:type=grid widget:columns="branch_name,branch_description" </code> In this case we are able to edit the branch name and description in each row of the grid. ===See Also=== * [[grid|The grid widget]] * [[checkbox|The checkbox widget]] * [[relationships.ini file|The relationships.ini file]] * [[fields.ini file|The fields.ini file]] grid widget, relationship, checkbox en 0 grid 67 grid ==widget:type = grid== Suppose we have two tables, tbl_organisation and tbl_individuals, in the edit view for a record in the organisations table (tbl_organisations) we also want to be able to view and edit the individuals within this organisation we can use widget:type=grid In the /tables/tbl_organisation/fields.ini we create a transient field by adding: <code> [Individuals] widget:label = "Individuals" transient=1 relationship=individuals widget:type=grid widget:columns="ind_firstname,ind_lastname,ind_tel" </code> The above assumes we have a relationship entry in our /tables/tbl_organisation/relationships.ini that looks like this: <code> [individuals] __sql__ = "SELECT * FROM tbl_individual WHERE org_id='$org_id'" </code> The fields.ini will show the three columns shown in widget:columns from the table tbl_individual Correct permissions need to be set to enable editing and deletion etc of these records. en 0 table 66 table When using widget:type table, it will store the data as XML. So the field type must be TEXT (or varchar... but text is better). You can decide which columns you want in the table by creating sub-fields in your fields.ini file as follows: Suppose you want a column called 'name' and a column called 'url' <code> [myfield] widget:type=table [myfield:name] [myfield:url] </code> Now when you access the stored value using the Dataface API, the value of myfield will be stored as an array of associative arrays. e.g. <code> foreach ( $record->val('myfield') as $vals){ echo $vals['name'].' -- '.$vals['url']; } </code> en 0 LDAP_or_Active_Directory 65 How to authenticate users with LDAP or Active Directory [[toc]] It is often easier to use the existing LDAP or Active Directory to authenticate users in Xataface than to create a new password for every user in the table users. ===In the conf.ini=== In the conf.ini file, in the [auth] part, you need to add your LDAP or AD configuration data : <code>[_auth] auth_type=ldap users_table = xata_users username_column = id ldap_host = "xxx.xxx.xxx.xxx" ldap_port = "389" ldap_base = "OU=blabla,DC=blablabla"</code> Here in the table users, you need the login but the password can be just ''PASS'', because the password will be fetched into the LDAP base. You need to add the [http://weblite.ca/svn/dataface/modules/Auth/ldap/trunk/ auth module] in the conf/modules directory. ===See Also=== * [[authentication]] - Overview of Authenthentication features in Xataface LDAP,Active Directory,Authentication en 0 How_to_authenticate_users_with_LDAP_or_Active_Directory 64 How_to_authenticate_users_with_LDAP_or_Active_Directory ==How to authenticate users with LDAP or Active Directory== en 0 How_to_granulate_permissions_on_each_field 63 How_to_granulate_permissions_on_each_field ==How to granulate permissions on each field== To reach this aim, there is the method fieldname__permissions to place into the delegate class of the table. ===Getting the role=== First it is necessary to know the user's role. For this, the method getUser() is added in the class : <code>function getUser(&$record){ $auth =& Dataface_AuthenticationTool::getInstance(); $user =& $auth->getLoggedInUser(); return $user; }</code> ===Setting up the permissions for each field=== Next, the permissions are built for each column or field where they are needed, like in this example where the method name is formed with the field name, followed by 2 underscores then by ''permissions'' : <code>function fieldname__permissions(&$record){ $the_user =$this->getUser($record); $user=$the_user->val('identifiant'); if ( !$user) return Dataface_PermissionsTool::NO_ACCESS(); if ( $user=='demande' ){ return Dataface_PermissionsTool::ALL(); } elseif ($user=='admin'){ return Dataface_PermissionsTool::ALL(); } else { return Dataface_PermissionsTool::READ_ONLY(); } }</code> === Also See === * [[viewable_editable_fields]] - How to make a field editable for some users and only viewable for some other users * [[no_access_text]] - Replace the default NO ACCESS permission text with another text. * [[__field__permissions]] - Returns the default permissions for a field of a given record. * [[Delegate_class_methods#toc5|Permissions]] - other Delegate class methods en 0 Customizing_the_look_and_feel_of_a_row_or_a_cell 62 Customizing_the_look_and_feel_of_a_row_or_a_cell ==How to customize the look and feel of elements in the list view== ===Create a method in a delegate class=== In the delegate class, the method ''css__tableRowClass'' is implemented, like in this example : <code>class tables_journal_interventions { function css__tableRowClass(&$record){ if ( !$record->val('fermeture')){ return 'intervention_close'; } else return ''; } } </code> Here the function tests a condition : is there a value in the field ''fermeture'' ? ===Add the class in a CSS stylesheet=== Now the class is created in a CSS stylesheet. <code>td.intervention_close { background-color: #FFE6E6 !important; } </code> This is a class for each cell, the <td> tag. The ''!important'' attribute is added to be sure that this information has precedence over all the others. It is better to add this class in a [http://xataface.com/documentation/how-to/custom_javascripts custom CSS stylesheet]. ===Remarks=== Beware that some versions of IE don't respect the background-color property on the <tr> tag, so it is probably better to write: <code> tr.intervention_close td { background-color: #FFE6E6; }</code> i.e. to apply the background color to the individual cells. en 0 lookup 61 The Lookup Widget Return to [[widget:type]] page to see list of all widget types. Back to [[fields.ini file]] to see other fields.ini directives. [[toc]] ===Synopsis=== The lookup widget allows users to look a record from another table to insert into the field. It is like a select widget except that it doesn't use a vocabulary. Instead you just specify a table on which it should search using the widget:table directive. In order to use the lookup widget to edit a field, you should set the [[widget:type]] directive of the [[fields.ini file]] for the field to '''lookup''. I.e. <code> [fieldname] widget:type=lookup widget:table=mytable </code> '''Note that the lookup widget requires the [[widget:table]] directive to be set to the target table of the lookup or it will not work properly.''' ===Required Directives=== The following [[fields.ini file]] directives are required to accompany the field definition if a lookup widget is used: {| class="listing listing2" |- ! Name ! Description ! Version |- | widget:table | The name of the table in which the lookup widget should look up related records. | 1.0 |} ===Optional Directives=== The following additional optional directives may be used to customize the behaviour of the lookup widget: {| class="listing listing2" |- ! Name ! Description ! Version |- | widget:filters:-limit | Sets the number of records that are shown by default in the lookup widget. Default is 30 if this is omitted. E.g.<code>widget:filters:-limit=100</code> to show 100 records at a time. | 1.0 |- | widget:filters:-sort | Specifies the columns to sort the results on. E.g. <code>widget:filters:-sort=category_name asc, year desc</code> | 1.0 |- | widget:filters:* | Any valid Xataface directive can be used to filter the results by specifying widget:filters:param (where "param" is a valid Xataface GET parameter, which could include a column name to filter results on, or other filter directives). <code>widget:filters:country=Canada</code> To only show results with Country=Canada. | 1.0 |- | widget:filters:*=$* | Dynamic filters. Causes the options in the record browser to be filtered on the value of another field in the form. e.g. <code>widget:filters:country_id="$country_id"</code> would show only results with records having country_id matching the value of the 'country_id' field in the current form. | 1.3.1 |} See [[URL Conventions]] for an overview of the types of GET parameters Xataface can take. Any GET parameters that manipulate a query can be used with the widget:filters:* directive to modify the query results that are shown in the lookup widget. ===Example=== In this example we have a field named appointee that is supposed to reference the contacts table. So in the [[fields.ini file]] we would have: <pre> [appointee] widget:type=lookup widget:table=contacts </pre> Initially we just have a little find icon next to the field. If the user clicks it, a dialog pops up enabling them to search for the contact that they want: [[Image:http://media.weblite.ca/files/photos/Picture%2023.png?max_width=640]] ===Additional Tips=== Although the lookup widget does not use a vocabulary as indicated in the Synopsis above, it is still useful to define a vocabulary in the fields.ini file for this field. The reason is because the lookup widget is only used with the edit action, where you are inserting or editing data into the field. However, it is not used to the display the data in the view or list actions. Therefore, you must still have a vocabulary defined to properly display these values. In order to customize the display of the lookup widget's select list, you must edit the delegate class for the table which is referenced by the widget:table directive. There are two important points to note: # The items in the selection list are formatted based on the getTitle(&$record) delegate class function if it is defined. However, ... # The Search box will search on text in VARCHAR and TEXT fields. If you need to search for data in numeric fields, you can create a grafted field using a function such as CONCAT() to display numbers as text. Links: * [http://xataface.com/forum/viewtopic.php?f=4&t=6723 Lookup widget on view with compound primary key] lookup widget, widget:filters, widget:-filters:limit, widget:table en 0 widget:type_textarea 60 widget:type_textarea en 0 no_access_text 59 no_access_text Whenever the NO_ACCESS permission is given for a field, normally the text NO ACCESS appears. But we might want to display another text. Here is an example of the text subscribe is used instead of NO ACCESS whenever the NO_ACCESS permissions is given. <code>function no_access_text(&$record){ return "Subscribe"; } </code> en 0 Selected_Records_Actions 58 Selected_Records_Actions ==Creating a Custom ''Selected Records'' Action== [[toc]] If you view the ''list'' tab in any of your Xataface applications, you'll notice that there is a checkbox next to each row of the list, and there are a number of actions listed at the bottom of the list that you can perform on the selected records. Xataface comes pre-built with only a few of these actions: # Delete selected # Update selected # Copy selected However it is quite easy to add your own actions here that are performed on selected records. This article describes exactly how to do this. ===What is a ''Selected Record'' action?=== A ''Selected Record'' action is no different than any other action in Xataface, except that it is meant to act on the records that have been selected in the list tab. ==Example Action: Approve Records== Consider a news site where news stories are automatically imported into the database en masse, but each news story has a field ''approved'' to indicate whether the store has been approved to appear on the site yet. The usage pattern of this application involves a lot of looking through lists of news stories and approving them. Therefore it would be convenient if the user could just select the rows that he wants to approve and click a button to approve them all. Out of the box Xataface would allow the user to select the records, click ''update selected records'', then update them all via the ''update selected records'' form. But avoiding this extra step will improve usability greatly. ===Step 1: Design the Action=== First we need to specifically decide how our action will work. In this case, the flow goes as follows: # User selects the news items they want to approve. # User clicks the ''Approve Selected'' button. (to be created) # Our action approves the selected records. # User is automatically redirected back to the list tab with a message stating how many records were successfully approved, and whether there were any errors. ===Step 2: Gather Our Tools=== Before we actually create the action, let's look at a few tools that we'll be using from the Xataface framework to make this happen. # In the [[actions.ini file]], the ''[[selected_result_actions]]'' category is reserved for actions that act on selected records of the list tab. E.g.<code> [delete_selected] ... category=selected_result_actions ... </code> # The [http://dataface.weblite.ca/df_get_selected_records df_get_selected_records()] function returns an array of [http://dataface.weblite.ca/Dataface_Record Dataface_Record] objects that represent the rows that were selected to initiate the action. E.g.<code> $app =& Dataface_Application::getInstance(); $query =& $app->getQuery(); $records = df_get_selected_records($query); foreach ($records as $record){ ... } </code> # The [http://dataface.weblite.ca/checkPermission Dataface_Record::checkPermission()] method allows us to see if the current user has access to a specific permission on the given record. We'll use this method to ensure that the user has permission to approve the news record. E.g.<code> if ( !$record->checkPermission('edit', array('field'=>'approved')) ){ return PEAR::raiseError("You don't have permission to edit the approved field for this record."); } </code> # The Xataface will pass the redirect URL where your action should send the user upon completion of the action as the ''--redirect'' attribute of the ''POST'' variables. This value is base64_encoded so you'll need to decode it before redirecting. E.g.:<code> if ( @$_POST['--redirect'] ) $url = base64_decode($_POST['--redirect']); $url .= '&--msg='.urlencode($updated.' records were deleted.'); header('Location: '.$url); exit; </code> ===Step 3: Create the Action=== We will call our action ''approve_news'' so we'll place it in the ''actions/approve_news.php'' file of our application: <code> <?php class actions_approve_news { function handle(&$params){ // First get the selected records $app =& Dataface_Application::getInstance(); $query =& $app->getQuery(); $records =& df_get_selected_records($query); $updated = 0; // Count the number of records we update $errs = array(); // Log the errors we encounter foreach ($records as $rec){ if ( !$rec->checkPermission('edit'), array('field'=>'approved')) ){ $errs[] = Dataface_Error::permissionDenied( "You do not have permission to approve '". $rec->getTitle(). "' because you do not have the 'edit' permission."); continue; } $rec->setValue('approved', 1); $res = $rec->save(true /*secure*/); if ( PEAR::isError($res) ) $errs[] = $res->getMessage(); else $updated++; } if ( $errs ){ // Errors occurred. Let's let the user know. // The $_SESSION['--msg'] content will be displayed to the user as a message // in the next page request. $_SESSION['--msg'] = 'Errors Occurred:<br/> '.implode('<br/> ', $errs); } else { $_SESSION['--msg'] = "No errors occurred"; } $url = $app->url('-action=list'); // A default URL in case no redirect was supplied if ( @$_POST['--redirect'] ) $url = base64_decode($_POST['--redirect']); $url .= '&--msg='.urlencode($updated.' records were deleted.'); // Redirect back to the previous page header('Location: '.$url); exit; } } </code> ===Step 4: Add the action to your actions.ini file=== The actions.ini file allows us to specify how and where this action is used, and by whom. We can specify permissions that are required to perform the action, conditions that are required to display the action, confirmation messages that are to be displayed to the user when they are about to perform the action, and more. Our [[actions.ini file]] entry looks like: <code> [approve_news] label="Approve" description="Approve selected records" permission = edit category=selected_result_actions confirm="Are you sure you want to approve the selected records?" icon="${dataface_site_url}/images/approve.gif" condition="$query['-table'] == 'news'" </code> This should be fairly straight forward. The only special items here are the ''category'' and ''confirm'' directives. The ''condition'' directive tells Xataface that this action should only be shown for the ''news'' table. The ''confirm'' directive defines a confirmation message that should be displayed to the user when they attempt to approve records. The ''icon'' directive allows you to specify the path to an icon to display for the action. In our case we have an icon located in the images directory of our application. ===Step 5: Trying it out=== Now when we go to the ''list'' tab of the ''news'' table there is an ''Approve'' button along the bottom where it says "With Selected". You we can click on this button to approve any of the selected rows. en 0 Creating_a_Dashboard 57 Creating_a_Dashboard ==Creating a Dashboard for your Users== [[toc]] Xataface allows you to build powerful data-driven applications quickly, but these applications may be daunting to your users if they don't know what they can do with the application. Most applications provide some sort of dashboard or control panel with some introductory instructions and links to commonly used actions in the application. This makes the application more intuitive for users so that they can start using it right away, even without instruction from the developer. ===Characteristics of a Dashboard=== # Should be the default page when someone visits the application. # Should be customized to show menus and content that are relevant to the current user. (i.e. different users may see different links and content on their dashboard). # Should contain at least some basic instructions so that the user understands what the application does when he visits the dashboard for the first time. # Should contain links to frequently used actions. ===Strategies: 8 ways to skin the cat=== There are many viable strategies for adding a dashboard to your Xataface application. This article presents only one. It has been chosen because it satisfies all of the desired characteristics of a dashboard listed above, and it is easy to implement. This strategy involves the following components: # Create a dummy ''dashboard'' table. # Create a dashboard action and associated template. # Make sure our dashboard action is the default action for our application (more complex than just using the [[default_action]] directive in the [[conf.ini file]]. ==Our Sample Application== Consider our sample application, a publications management system for professors and research groups at a university. It allows users to manage their publications using either BibTex format or a web-based form, and embed those publications into their webpage in a slick sortable format. Currently, when the user accesses the application for the first time, they are shown the ''list'' tab of the ''bibliographies'' table. This isn't all that informative and it may not be obvious to the user that their first step should be to create a new bibliography via the ''new record'' button. Ideally we would like the user to go directly to a dashboard page with options to: # Add New Bibliography # Edit an Existing Bibliography # Embed a Bibliography into their Webpage And we want some basic instructions so that the user knows what to do when they first access the page. ==The Steps== To create this dashboard we will follow the steps listed below (and mentioned above in the ''strategies'' section. ===Step 1: Create a dummy ''dashboard'' table=== This may seem unorthodox but it just happens to make our lives easier in the long run. By creating a dummy table we are able to cause that table to be listed first in the ''_tables'' section of the [[conf.ini file]] and thus be the default table when users visit our application. <code> CREATE TABLE dashboard ( dashboard_id int(11) not null auto_increment primary key ); INSERT INTO dashboard values (1); </code> ===Step 2: Make ''dashboard'' table default=== We now modify the conf.ini file to list the ''dashboard'' table first: <code> [_tables] dashboard=Dashboard bibliographies=Bibliographies </code> ===Step 3: Create a Dashboard action and associated template=== This is the step where we actually create our dashboard action. There are three parts to this story: ====Creating Action PHP Class==== The actual action will be located in the ''actions/dashboard.php'' file of our application, and looks like: <code> <?php class actions_dashboard { function handle(&$params){ $bibs = df_get_records_array('bibliographies', array()); df_display(array('bibliographies'=>$bibs), 'dashboard.html'); } } </code> All this does is loads the ''bibliographies'' records owned by the current user. Elsewhere we are using security filters so that the user can only see ''his'' bibliographies, which is why we don't need to specify any query here in the ''df_get_records_array'' function. It then passes those bibliographies to the ''dashboard.html'' template that we create next. ====Creating the Action's Template==== The template for our action is located in the ''templates/dashboard.html'' file: <code> {use_macro file="Dataface_Main_Template.html"} {fill_slot name="main_column"} <h1>Welcome to the BibTeX Publication Management System (BPMS)</h1> <p>This system allows you to manage your publications and publish them on the web. Some common actions you may perform with this system include: <ul> <li><img src="{$ENV.DATAFACE_URL}/images/add_icon.gif"/> <a href="{$ENV.DATAFACE_SITE_HREF}?-table=bibliographies&-action=new"> Create New Bibliography</a> </li> <li><img src="{$ENV.DATAFACE_URL}/images/edit.gif"/> Edit existing bibliography: <select onchange="window.location.href=this.options[this.selectedIndex].value"> <option value="">Select ...</option> {foreach from=$bibliographies item=bibliography} <option value="{$bibliography->getURL('-action=edit')}"> {$bibliography->getTitle()} </option> {/foreach} </select> </li> <li><img src="{$ENV.DATAFACE_URL}/images/file.gif"/> Embed your bibliography in a webpage: <select onchange="window.location.href=this.options[this.selectedIndex].value"> <option value="">Select ...</option> {foreach from=$bibliographies item=bibliography} <option value="{$bibliography->getURL('-action=view')}#embed"> {$bibliography->getTitle()} </option> {/foreach} </select> </li> </ul> {/fill_slot} {/use_macro} </code> A few key things to notice in this template: # It extends the ''Dataface_Main_Template.html'' template placing its content in the ''main_column'' slot. This allows our action to still display within the header and footer of our application. # It makes use of the {$ENV.DATAFACE_SITE_URL} and {$ENV.DATAFACE_SITE_HREF} variables to refer to the site's base url and create links to the desired common actions. # It provides a direct link to the ''new bibliography record'' form. # It uses some slick javascript combined with select lists to allow the user to select any of his current bibliogaphies and edit them, or embed them into a webpage. ====Adding entry to the actions.ini file==== Currently our dashboard action has no permissions attached to it so users can see it whether they are logged in or not. In this particular application we want to require users to log in, and we have set permissions for all logged in users to NO_ACCESS(). Unfortunately this permission setting is only helpful if our action requires a particular permission to access it. We'll require the 'view' permission for this action, by adding the following to the actions.ini file: <code> [dashboard] permission=view </code> ===Step 4: Specify permissions=== We still want to specify permissions for our ''dashboard'' table to ensure that only logged in users can access the dashboard. So we create a delegate class for the ''dashboard'' table at ''tables/dashboard/dashboard.php'' with the following contents: <code> <?php class tables_dashboard { function getPermissions(&$record){ if ( getUser() ){ return Dataface_PermissionsTool::ALL(); } return null; } } </code> '''Note that we have defined the getUser() function elsewhere as a means of obtaining the current user and checking if a user is indeed logged in.''' Notice that this [[getPermissions]] method returns all permissions only if the user is logged in. Otherwise it returns null, which means that it should use the same permissions as the rest of the application as defined in the [[Application Delegate Class]]. ===Step 6: Make ''dashboard'' the default action for the ''dashboard'' table=== Now we just have one more detail that needs to be taken care of. We want the ''dashboard'' action to be the default action for the ''dashboard'' table only. By default we would see the ''list'' action which isn't helpful at all, so we will want to add a rule in our application delegate class to ensure that the user only sees our custom ''dashboard'' action if they access the ''dashboard'' table. We define a beforeHandleRequest() method in our conf/ApplicationDelegate.php (the application delegate class) file for this purpose: <code> <?php class conf_ApplicationDelegate { ... function beforeHandleRequest(){ ... $app =& Dataface_Application::getInstance(); $query =& $app->getQuery(); if ( $query['-table'] == 'dashboard' and ($query['-action'] == 'browse' or $query['-action'] == 'list') ){ $query['-action'] = 'dashboard'; } } ... } </code> This simply checks to see if the table is ''dashboard'' and changes the current action to ''dashboard'' if so. ===Step 7: Try it out=== At this point, we are ready to try out our new dashboard to see how it works. When we load our application it should now go to the dashboard action that we created. We should also see ''Dashboard'' listed as the first table in the tables menu. This dashboard presents a major improvement to our application as it is now much more user friendly. <nowiki> <img src="http://media.weblite.ca/files/photos/pub-dashboard.png?max_width=640"/> </nowiki> dashboard en 0 struct 56 struct en 0 blob 55 blob en 0 Email 54 Email ==Xataface Email Module== [[toc]] The Xataface Email module allows you to convert your database into a mailing list so that you can easily send email to any found set of records, as long as the records contain an email address to send to. ==Features== * Send email to any found set. * Mail merge macros * HTML Email support (uses NicEdit WYSIWYG editor for email editing). * Opt out support (allows recipients to opt out of your mailing list). ==Requirements== * Xataface 1.0+ * MySQL 4.1+ * PHP 5+ ==Download== https://sourceforge.net/project/platformdownload.php?group_id=253820 ==Installation== # Download and extract Email directory so that it is located inside the xataface/modules directory (i.e. xataface/modules/Email) # Add the following to the ''[_modules]'' section of your application's conf.ini file:<code> modules_Email="modules/Email/Email.php" </code> # Configure the [email] action in your application's actions.ini file. See the section called 'Configuration' for configuration details. # Add a line to your crontab file to send out pending email periodically. The line should look like:<code> * * * * * /usr/bin/php <cronpath> <indexpath> <indexurl> mail where <cronpath> is the absolute path to the cron.php script. <indexpath> is the absolute path to your application's index.php script. <indexurl> is the absolute url to your application's index.php script. For example: * * * * * /usr/bin/php /var/www/xataface/modules/Email/cron.php \ /var/www/myapp/index.php \ http://example.com/myapp/index.php \ mail </code> If you want to see what this line should be like for your server, you can simply point your browser to the email_install action of your application (i.e. http://example.com/yourapp/index.php?-action=email_install) and it will generate this line to copy and paste into your crontab. Note that the /usr/bin/php portion of this line may vary according to your environment. It represents the path to your PHP binary. # That's it! You're ready to send email. See the ''Usage'' section to see how to send email from your application. ==Configuration== Though the email action may work out of the box, you will likely have to configure it to work the way you want. Some examples of things you will want to configure include: # Limit the email action to only be available for certain tables. # Apply permissions to the action so that only administrators can send email. # Set the name of the column that contains email address (default is 'email'). # Change the name of the table that is used to store sent email messages. ===Overriding the ''[email]'' action=== The first thing you need to do to configure the email action is override it in your appliation's actions.ini file. You can do this by adding the following to your [[actions.ini file]]: <code> [email > email] </code> Now any directives you add in this section will override the email action. ====Examples:==== =====Limiting email action to certain tables===== In your appliation's [[actions.ini file]]: <code> [email > email] condition="$query['-table'] == 'Pledge' or $query['-table'] == 'User'" </code> =====Limiting email action by permission===== By default your users require the ''email'' permission in order to have access to the email form. This permission is not included with any roles by default so you'll need to extend any roles that you want to have access to the email access and explicitly add the ''email'' permission. The exception to this rule is if you have assigned your users the ''Dataface_PermissionsTool::ALL()'' permissions in your ''getPermissions()'' method. Suppose you want the ''READ ONLY'' role to have access to the email action, you could add the following to your application's [[permissions.ini file]]: <code> [READ ONLY extends READ ONLY] email=1 </code> =====Changing the name of the email address column===== By default, the Email module will try to guess which column contains the email address for a table. Generally it looks for a column named ''email''. You can override this setting to explicitly tell the module which column contains the email address by overriding the ''email_column'' directive of the ''email'' action in your application's [[actions.ini file]]: <code> [email > email] email_column = "emailAddress" </code> =====Changing the name of the table that stores the sent email==== Xataface automatically stores each sent email for your records. By default it stores these emails in a table named ''newsletters''. You can override this table name with the ''email_table'' directive in your application's [[actions.ini file]]. This table will be automatically created by Xataface when email is sent out. <code> [email > email] email_table = "newsletters" </code> =====Altogether===== <code> [email > email] condition="$query['-table'] == 'Pledge' or $query['-table'] == 'User'" permission=email email_column = "emailAddress" email_table = "newsletters" </code> ==Usage:== ===Sending Email to All Records of a Table=== # Navigate to a table for which your email module is enabled, and click on the ''list'' tab. # Click on the "Email" icon in the upper right corner. This should display an email form.<nowiki> <img src="http://media.weblite.ca/files/photos/email_icons.png"/> </nowiki> # Fill in the email form and press Save.<nowiki> <div><img src="http://media.weblite.ca/files/photos/email_form.png?max_width=500"/></div> </nowiki> # You should receive a message saying that the email has been queued for delivery. Your cron script will automatically begin sending emails the next time around. So make sure that you have yoru cron script set up properly. ===Opting Out of the Email List=== If you have received an email that was sent via the email module you can easily opt out of the mailing list by clicking on the link at the end of the email. This link will bring you to a webpage that asks you to confirm that you no longer wish to receive email from this list. ==Using a View to add Email Action to Related Record List== You can simulate a many-to-many [[relationships.ini file|relationship]] in a mysql view by creating a view with all possible combinations. e.g. If you have a Many to Many [[relationships.ini file|relationship]] between books and authors your [[relationships.ini file|relationship]] from the books table might be something like: <code> [authors] __sql__ = "select * from authors a inner join book_authors ab on a.author_id=ab.author_id where ab.book_id='$book_id'" </code> And your relationship from the authors table would be something like: <code> [books] __sql__ = "select * from books b inner join book_authors ab on b.book_id=ab.book_id where ab.author_id='$author_id'" </code> Now if our goal was to be able to send email to all authors of a particular book (i.e. send to the authors relationship), we could create a view: <code> create view book_authors_maillist as select * from authors a inner join book_authors ab on a.author_id=ab.author_id </code> This view can now be used in xataface like a regular table (if you add a [[fields.ini file]] for it and [[Key|mark the primary key columns]]). If you wanted to find all authors for a certain book you would just do: index.php?-action=list&-table=book_authors_maillist&book_id=10 So you could easily create an action in the [[actions.ini file]] that would like to the mail action on the book_authors_maillist table with the parameters you wanted. e.g. <code> [related_authors_mail] category=related_list_actions url="{$site_href}?-action=email&-table=book_authors_maillist&book_id={$record->val('book_id')}" icon="{$dataface_url}/images/mail_icon.gif" url_condition="$record" condition="$query['-table']=='books' and $query['-relationship'] == 'authors'" permission="email" </code> This action would send mail to only the authors related to the current books. It would be made available in the icons in the upper right on the related list view of only the authors of a book. ===Mail Merge=== The 'Embed Macro' shown above the email form lists the fields which may be included in the email. Say you have a field called 'email_firstname'. You would type this into the message area like this: %email_firstname% When the email is sent, this is substituted for the record of that recipient. Eg. Dear %email_firstname% would be received by email as Dear Tom If the particular record of the field you are merging is blank, then (in this case) the first name will not be shown. Email,Email module,Sending Email,Maillist en 0 fieldname__permissions 53 fieldname__permissions ==fieldname__permissions() method== [[toc]] The fieldname__permissions() methods will allow you to define custom permissions on a particular field in the [[delegate class]]. For example to specify permissions on a field named ''foo'' you would define the ''foo__permissions()'' method, and to define permissions on a field named ''role'' you would define the ''role__permissions()'' method. ==Example #1== (Note this example needs to be refined to be more clear) <code> function approval_level__permissions(&$record){ return array('edit'=>0); //this is will merge with what the permissions for the normal record } </code> Here we are targeting the ''approval_level'' field of the [[delegate class]]. The permissions method takes a return value an array of permissions. So for example: <code> $permissions['new'] = 0; $permissions['edit'] = 0; </code> Would be an example of an array of permissions which the key being the permission name and the value being a boolean to specify whether they have (1) or don't (0) have permissions to that field. We don't have to specify a complete array of permissions (ie. permission of edit, new, readonly, etc, etc), but rather only the ones we want specifically. The reason being that the permissions array in the return value gets merged with the permissions that this record normally gets from the record permissions. So if the record normally gives the permissions new=0, edit=1. Then the return value from approval_level will merge with the original permissions to produce an array like this: <code> $permissions['new'] = 0; $permissions['edit'] = 1; </code> === Also See: === * [[How_to_granulate_permissions_on_each_field]] * [[__field__permissions]] en 0 How_to_Add_Custom_Sections_to_View_Tab 52 How_to_Add_Custom_Sections_to_View_Tab ==How to Add Custom Sections to the View tab== [[toc]] The ''View'' tab is intended to give the user a detailed view of the contents of a record. By default it shows the values of each non-empty field grouped into their appropriate field groups. It also shows the most recent 5 related records from each relationship in the record. You can also add your own sections by implementing the [[section__xxx]] method of the delegate class. ==Example 1: A "Hello World" Section== We'll start by adding a simple section that simply displays "Hello World" to the user. In the delegate class for your table, add the following method: <code> function section__hello(&$record){ return array( 'content' => 'Hello World!!!', 'class' => 'main' ); } </code> Now if you reload our application and click on the "View" tab for any of the records in the database, you'll notice a section labelled ''hello'' with the text ''Hello World!!!'' in it. Let's dissect the above code so that we can better understand what is going on here. # The function ''section__hello()'' defines a section named ''hello''. If you wanted to define a section named ''foo'' you would call the function ''section__foo()'' # This function returns an array with the keys ''content'', and ''class''. # The ''content'' key points to the actual HTML content of the section. In this case it is simply the text ''Hello World!!!''. # The ''class'' key defines where the section should be displayed. It accepts values of ''left'' and ''main'' only. If it is set to ''left'', then the section will be displayed in the left column. A value of ''main'' indicates that it should be displayed in the main column. ===Customizing the Section Label=== ''hello'' is a boring label, so let's add our own custom label by adding the ''label'' key to the array returned by our method: <code> function section__hello(&$record){ return array( 'content' => 'Hello World!!!', 'class' => 'main', 'label' => 'Message of the Day' ); } </code> Now if you load the view tab of your application, you'll notice that the section has a heading "Message of the Day". ===Customizing the Section Order=== A section can also specify an ''order'' attribute to define the order in which this section should appear. It defaults to 0 which may cause the section to appear at the top of the view tab. You can push it to the bottom of the view tab by assiging a higher number to the ''order'' attribute: <code> <code> function section__hello(&$record){ return array( 'content' => 'Hello World!!!', 'class' => 'main', 'label' => 'Message of the Day', 'order' => 10 ); } </code> Now if you reload the view tab you'll notice that the section has moved to the bottom of the page. en 0 fieldgroup_template 51 fieldgroup_template ==Using a custom template for a field group on the edit form== [[toc]] Xataface allows you to partition your fields into ''groups'' so that similar fields are grouped together on the edit form. The default layout of the fields remains simply vertical, but you can customize this layout (on a per-group basis) by creating a custom template and then assigning this template to the field group with the ''template'' directive. ===Example=== For example, in your [[fields.ini file]] if you wanted to group your address fields together you might have: <code> [fieldgroup:address] label="Address Information" template="AddressInformationGroup.html" [address_1] group=address [city] group=address [state] group=address </code> Then you would add the a template named ''AddressInformationGroup.html'' to your application's ''templates'' directory to display how the fields are laid out: <code> <table width="100%"> <tr><th>Address 1:</th> <td>{$elements.address_1.html}</td> <th>City:</th> <td>{$elements.city.html}</td> <th>State:</th> <td>{$elements.state.html}</td> </tr> </table> </code> This would display all of the fields in this group in a single row (horizontally) instead of vertically. Note that this is an over-simplified example that doesn't take account for display error messages, required notices, grouped fields, and other information that you can obtain from the {$elements} array. en 0 __field__permissions 50 __field__permissions This method can be used to set the default permissions for all fields in a designated table, when specified in that table's delegate class. It comes in handy in situations when you want to deny access to all fields except for those designated, rather then specifying each field to deny individually. For example, to revoke edit permissions from all fields but one, the user must first have edit permissions to the table overall, otherwise the Edit tab/action will not appear. Then, use this __field_permissions method to revoke edit permissions from all fields. Finally, use the fieldname__permissions method (see below) to allow access to only those fields needed. === Also See: === * [[How_to_granulate_permissions_on_each_field]] * [[fieldname__permissions]] en 0 Troubleshooting 49 Troubleshooting ==Xataface Troubleshooting== This document is intended to help Xataface developers through some of the most common issues. [[toc]] ==All I get is a blank white screen!== The most common issue mentioned in the forums is that an application comes up with a blank white screen in the web browser. This can happen for a number of reasons but the most common reason is because PHP has encountered a fatal error and your PHP installation is not set up to display errors. The first step to troubleshooting this problem must be to find out what the error is. You can do that in one of the following ways: # Check your Apache error log if you know where it is. One common location on many linux installations is <code> /var/log/httpd/error_log </code> but your system may have it located elsewhere. If you cannot find your error log, continue to the next option. # Turn on the ''display_errors'' flag in your ''php.ini'' file. I.e., in your ''php.ini'' file, find where it says <code> display_errors Off </code> and change it to <code> display_errors On </code>. After this is done, restart your apache webserver. If you don't know where your ''php.ini'' file is located see the section later in this document on locating your ''php.ini'' file. If you don't have access to your php.ini file, move on to the next option. # In your application's ''.htaccess'' file, add the following directives to enable displaying errors:<code> php_flag display_errors on </code> . Note that this method will only work if your apache config file allows you to override these values at the directory level. If you still get a blank white screen after this, continue to the next option. # At the beginning of your application's index.php file, add the following:<code> <?php error_reporting(E_ALL); ini_set('display_errors', 'on'); </code> . Note that if the error occurs in the parsing or compiling of your PHP files you will still get a blank screen. But this will at least display runtime errors on the page. Once you can see the error messages that caused the blank white screen you are in a much better position to solve the problem. ==Locating your php.ini file== Locating your ''php.ini'' file is actually quite easy. The quickest way is to create a php script with the following contents: <code> <?php phpinfo(); </code> then navigate to this page in your web browser. This look at the line where it says the ''php.ini file''. It will list the path there. en 0 tab 48 tab ==tab directive of the fields.ini file== [[toc]] The ''tab'' directive of the [[fields.ini file]] specifies which tab of the record edit form a field should be displayed on. Xataface supports multiple tabs on the edit form by way of this ''tab'' directive. If no fields contain the ''tab'' directive then all fields are displayed in a single tab (named ''__main__''). ==Example 1: Placing address info on separate tab== Consider the following ''people'' table: <code> CREATE TABLE `people` ( person_id int(11) not null auto_increment primary key, first_name varchar(32) not null, last_name varchar(32) not null, address varchar(100), city varchar(100), province varchar(100), country varchar(100), postal_code varchar(20) ) </code> We want to split the fields into two tabs: * Personal Info * Address Info ===Splitting form into tabs=== We'll do this in two steps. We use the ''tab'' directive to assign all address-related fields to the ''address_info'' tab. In the tables/people/fields.ini file: <code> [address] tab=address_info [city] tab=address_info [province] tab=address_info [country] tab=address_info [postal_code] tab=address_info </code> Now, when we load the edit form of the ''people'' table, we see two tabs: * __main__ * address_info <nowiki> <img src="http://media.weblite.ca/files/photos/Picture 9.png?max_width=640"/> <img src="http://media.weblite.ca/files/photos/Picture 10.png?max_width=640"/> </nowiki> ''__main__'' is the name assigned to the default tab (for all fields that don't have a tab defined explicitly. ===Customizing the tab labels=== Next we will customize the tab labels by adding the following to the beginning of the [[fields.ini file]]: <code> [tab:__main__] label="Personal Information" [tab:address_info] label="Address Information" </code> <nowiki> <img src="http://media.weblite.ca/files/photos/Picture 11.png?max_width=640"/> <img src="http://media.weblite.ca/files/photos/Picture 12.png?max_width=640"/> </nowiki> ===Reordering the tabs=== If we want to reorder the tabs so that the ''address_info'' tab comes first, we would just reorder the definitions of the tabs: <code> [tab:address_info] label="Address Information" [tab:__main__] label="Personal Information" </code> <nowiki> <img src="http://media.weblite.ca/files/photos/Picture 13.png?max_width=640"/> </nowiki> ===Try This Example App=== You can try this tiny sample application out [http://dev.weblite.ca/tab_test here]. en 0 visibility:fieldName 47 visibility:fieldName ==Example== <code>visibility:ConferenceID = hidden</code> This will make the ConferenceID in the relationship list view disappear. en 0 widget:atts 46 widget:atts ==widget:atts Directive Reference== The widget:atts directive in the fields.ini file allows any arbitrary HTML attributes to be added to any of the fields. It may also be used to specify javascript event handler functions that the widget should call upon the specified event. In particular, here are some examples of possible widget:atts directives: ===Available Widget Event Handlers=== {| class="listing listing2" |- ! name ! description ! version |- | [[field_size|widget:atts:size]] | This directive sets the length of the input area a text box field, but it does not limit the number of characters that can be entered. For example: <nowiki><br/>widget:atts:size = 50</nowiki> | ? |- | [[field_maxlength|widget:atts:maxlength]] | This directive limits the maximum number of characters that can be entered into a text box field. For example: <nowiki><br/>widget:atts:maxlength = 25</nowiki> | ? |- | [[field_style|widget:atts:style]] | This directive specifies the style (font-size, font-family, etc.) for the field. For example: <nowiki><br/>widget:atts:style = "font-size: 24pt; font-family: Apple Chancery"</nowiki> | ? |- | [[field_rows|widget:atts:rows]] | This directive specifies the number of rows for a text area field to display. For example: <nowiki><br/>widget:atts:rows = 10</nowiki> | ? |- | [[field_cols|widget:atts:cols]] | This directive specifies the number of columns for a text area input field (1 character = 1 column). For example: <nowiki><br/>widget:atts:cols = 10</nowiki> | ? |- | [[field_javascript_onchange|widget:atts:onchange]] | This directive will cause the specified javascript function to be called with the value of the field whenever its value is changed (i.e. when you change the field and tab out of it). For example: <nowiki><br/>widget:atts:onchange = "doJsFunction();"</nowiki> | ? |- | [[field_javascript_onclick|widget:atts:onclick]] | This directive will cause the specified javascript function to be called with the value of the field whenever it is clicked. For example: <nowiki><br/>widget:atts:onclick = "doJsFunction();"</nowiki> | ? |} ===Helpful tutorials=== See the bottom of this page in the Getting Started tutorial for more details on the basic directives above: [http://xataface.com/documentation/tutorial/getting_started/customizing Customizing Field labels, descriptions, and widgets] This tutorial talks about how to use the javascript directives: [http://xataface.com/documentation/how-to/custom_javascripts] en 0