valuelists.ini_file 5 valuelists.ini_file ==valuelists.ini file Reference== [[toc]] The valuelists.ini file stores value lists that can be used as [[vocabulary|vocabularies]] for select lists, checkbox groups, and other widgets the provide the user with options to choose from. Each table can have an associated valuelists.ini file located in its [[table configuration directory]]. E.g. for a table named "people" its valuelists.ini file will be stored in "tables/people/valuelists.ini". In addition you can define an application-wide valuelists.ini file in the root of your application's directory, whose valuelists can be used by any table. ===Syntax=== The valuelists.ini file uses [[INI file syntax]], where a valuelist is defined by a single section of the INI file. E.g. <code> [colors] r=Red b=Blue g=Green </code> This example would define a single valuelist named "colors" with 3 values: r,g, and b (with corresponding labels "Red", "Green", and "Blue). The values (the left of the equals sign) are stored in the database, while the labels are rendered on screen for the user's convenience. ===Dynamic Valuelists=== It is often advantageous to load valuelists from the database rather than store them directly in the valuelists.ini file. The __sql__ directive allows you to specify an SQL query which selects up to 2 columns (the first is the id and the second, the label). E.g. <code> [colors] __sql__ = "select colorCode, colorName from colors" </code> ===Defining Valuelists in a Delegate Class=== If you require more flexibility with the definition of your valuelists than can be gained from the valuelists.ini file, you can define your valuelist using PHP inside a delegate class. Essentially you just create a method that returns an associative array, where the keys are the IDs that are stored in the database, and the values are the values that are visible in the select list. e.g. In either the application delegate class or a table delegate class: <code> function valuelist__colors(){ return array( 'r'=>'Red', 'g'=>'Green', 'b'=>'Blue' ); } </code> This method is called each time the valuelist is about to be used, so if your method performs any sort of intensive processing, it is a good idea to use a caching scheme so that it only runs the critical code once per request. For example, you could use a static variable as follows: <code> function valuelist__colors(){ static $colors = -1; if ( !is_array($colors) ){ $colors = array(); $res = mysql_query("select colorCode, colorName from colors", df_db()); if ( !$res ) throw new Exception(mysql_error(df_db())); while ($row = mysql_fetch_row($res) ) $colors[$row[0]] = $row[1]; } return $colors; } </code> In this example the database query is only executed once per request to load the $colors variable. The rest of the time it simply loads the cached value from $colors. valuelists, dynamic valuelists, programmatically defined valuelists 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 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 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 widget:editor 35 widget:editor ==widget:editor fields.ini directive== Return to [[fields.ini file]] [[toc]] The widget:editor directive is applicable in the [[fields.ini file]]. It specifies the type of HTML editor that should be used. This directive is only used when [[widget:type]] is set to [[widget:type htmlarea|htmlarea]]. Xataface currently supports FCKEditor, TinyMCE, and NicEdit. ===Allowed Values=== {| class="listing listing2" |- ! Value ! Description ! Version |- | fckeditor | Use [http://www.fckeditor.net/ FCKEditor]. This is the default value. | all |- | tinymce | Use [http://tinymce.moxiecode.com/ TinyMCE editor]. | 0.6 |- | nicedit | Use [http://www.nicedit.com/ NicEdit]. | 1.0.5 |} ===Examples=== ====Example 1: Using FCKEditor==== Given a field 'content' that you wish to be able to edit with FCKEditor, you would have the following section in your [[fields.ini file]]: <code> [content] widget:type=htmlarea widget:editor=fckeditor </code> Note that since FCKEditor is the default editor, the above would give the same result as: <code> [content] widget:type=htmlarea </code> ====Example 2: Using TinyMCE==== Further from example 1, if we wanted to use TinyMCE editor, we would change our directive to: <code> [content] widget:type=htmlarea widget:editor=tinymce </code> ====Example 3: Using NicEdit==== Further from example 1: <code> [content] widget:type=htmlarea widget:editor=nicedit </code> ==Enabling Image Uploads== By default image uploads are disabled in these WYSIWYG editors. ===Enabling Image Uploads in FCKEditor=== # Create a directory named ''uploads'' inside your application directory. e.g.<code> cd /path/to/myapp/uploads </code> # Make the ''uploads'' directory writable by the webserver. e.g. <code> chmod 777 /path/to/myapp/uploads </code> # Edit the ''lib/FCKeditor/editor/filemanager/connectors/php/config.php'' file inside your ''xataface'' directory so that:<code> $Config['Enabled'] = true ; $Config['UserFilesPath'] = '/url/to/myapp/uploads/' ; // The path portion of the URL to your uploads directory. // e.g. if your uploads directory is accessible at // http://example.com/myapp/uploads, then this value should // be /myapp/uploads/ $Config['UserFilesAbsolutePath'] = '/path/to/myapp/uploads/' ; // The absolute file system path to your uploads directory. // e.g. if your uploads directory is located at // /home/myhome/www/myapp/uploads, then this value should be // /home/myhome/www/myapp/uploads </code> # Now when you click on the "Add Image" link in your HTML editor, it will allow you to upload images and browse existing uploaded images. en 0 widget:type 4 widget:type ==widget:type Directive Reference== The widget:type directive in the [[fields.ini file]] specifies the type of widget that should be used to edit a particular field in HTML forms. Xataface uses [http://pear.php.net/package/HTML_QuickForm/ HTML_QuickForm] for its form generation so theoretically any widget supported by HTML_QuickForm should work with Xataface. ===Available Widget Types=== {| class="listing listing2" |- ! Name ! Description ! Version |- | [[advmultiselect]] | Two select lists with add/remove buttons. Selected items appear in the right select list. Options may be selected from the left select list. | 1.0 |- | [[autocomplete]] | An autocomplete. text field. This is not to be confused with the [[yui_autocomplete]] widget. The main difference is that this widget does not provide a drop-down list of possibilities, it just tries to complete what the user is typing inside the text field based on a valuelist. | all |- | [[calendar]] | A DHTML pop-up calendar to select the date. [[Image:http://media.weblite.ca/files/photos/calendar_widget.png?max_width=400]] | 0.5.3 |- | [[checkbox]] | A checkbox or checkbox group. Example 1: Checkbox as boolean on Tinyint field. [[Image:http://media.weblite.ca/files/photos/checkbox_widget.png?max_width=400]] Example 2: Checkbox group to allow multiple selections. [[Image:http://media.weblite.ca/files/photos/checkbox-group_widget.png?max_width=500]] | all |- | [[date]] | Select lists for month, year, day, hour, etc... | all |- | [[file]] | A file widget (default type for [[container]] fields and [[blob]] fields. [[Image:http://media.weblite.ca/files/photos/file_widget.png?max_width=400]] | all |- | [[grid]] | A grid widget for editing multiple rows of related records inside the edit form. Supports adding/removing/reordering. As of version 1.2.5, file uploads are not supported in the grid widget. [[Image: http://media.weblite.ca/files/photos/grid_widget.png?max_width=500]] | 1.0 |- | [[group]] | A compound widget for editing multiple fields but storing the data in a single XML field. [[Image:http://media.weblite.ca/files/photos/group_widget.png?max_width=400]] | all |- | [[hidden]] | A hidden field | all |- | [[htmlarea]] | A WYSIWYG (What you see is what you get) HTML editor. This defaults to [http://www.fckeditor.net/ FCKeditor], but [http://tinymce.moxiecode.com/ TinyMCE] is also supported. [[Image:http://media.weblite.ca/files/photos/htmlarea_widget.png?max_width=400]] | all |- | [[lookup]] | A field that allows users to look-up a record from another table. THis is a good alternative to a select list. It doesn't use a vocabulary, so this is appropriate when vocabularies would be unpractical (for large vocabularies). You do, however need to specify the widget:table directive for the field so that the lookup knows from which table to load the records. [[Image:http://media.weblite.ca/files/photos/Picture%2023.png?max_width=640]] | 1.2 |- | [[password]] | A password field. [[Image:http://media.weblite.ca/files/photos/password_widget.png?max_width=400]] | all |- | [[select]] | A select list. Example 1: A single select. [[Image:http://media.weblite.ca/files/photos/select_widget.png?max_width=400]] Example 2: A multi-select. To use a multi-select, add repeat=1 to your fields.ini. [[Image:http://media.weblite.ca/files/photos/multi-select_widget.png?max_width=500]] | all |- | [[table]] | A compound widget for editing tabular data. This widget dictates the storage format as XML. [[Image:http://media.weblite.ca/files/photos/table_widget.png?max_width=400]] | all |- | [[text]] | A text field [[Image:http://media.weblite.ca/files/photos/text_widget.png?max_width=400]] | all |- | [[textarea]] | A text area (multi-line text field) [[Image:http://media.weblite.ca/files/photos/textarea_widget.png?max_width=400]] | all |- | [[time]] | A select list of times separated by a specified interval (default 30 minutes). | 0.7 |- | [[yui_autocomplete]] | An autocomplete widget ported from the [http://developer.yahoo.com/yui/autocomplete/ Yahoo UI Library]. [[Image:http://media.weblite.ca/files/photos/yui_autocomplete.png?max_width=400]] | 1.0 |} en 0 widget:type_textarea 60 widget:type_textarea en 0 Writing_Custom_Authentication_Plugins 22 Writing_Custom_Authentication_Plugins ==Writing a Custom Authentication Plugin for Xataface== [[toc]] Xataface has a pluggable [[authentication]] framework that allows you to easily write your own custom [[authentication]] modules to tie in with other systems. Several plugins have already been created including: * [[CAS Authentication Module|Yale CAS]] * [[LDAP Authentication Module|LDAP]] * [[Facebook Authentication Module|Facebook]] * [[HTTP Authentication Module|HTTP]] ===Example: Creating a custom authentication plugin=== Before we begin, a couple of conventions: # '''%XATAFACE_ROOT%''' refers to your Xataface installation directory. This is where all of the Xataface files are located includeing dataface-public-api.php # '''%SITE_ROOT%''' refers to your Xataface application's installation directory. This is where your conf.ini file, index.php, and other application files are stored. ====About our plugin==== Our plugin will be the simplest, most useless authentication plugin you can imagine. It simply checks an array of usernames and passwords to see if the password that the user supplied is valid. ====Creating our plugin==== # Create the '''%XATAFACE_ROOT%/modules/Auth''' directory if it doesn't exist already. This directory will store all of our Xataface authentication plugins. #Create the '''%XATAFACE_ROOT%/modules/Auth/XDB''' directory if it doesn't exist already. This directory will house all of the scripts and files associated with our custom plugin. #Create a new PHP file named '''XDB.php''' inside our '''XDB''' directory that we just created, with the following contents:<code> class dataface_modules_XDB { var $passwords = array( 'steve' => 'stevespass', 'mike' => 'foo' ); function checkCredentials(){ $auth =& Dataface_AuthenticationTool::getInstance(); $creds = $auth->getCredentials(); if ( @$this->passwords[$creds['UserName']] == $creds['Password'] ){ return true; } else { return false; } } } </code> # Now, change the '''[_auth]''' section of the conf.ini file to let Xataface know that we want to use our custom module:<code> [_auth] auth_type=XDB </code> # Try to log into your application. You'll notice that the only username/password combinations that are accepted are the ones that we specified in our '''$passwords''' array in our module. This is just a simple example, but you can see how this can be expanded to provide more complex modules. ===checkCredentials() not enough?=== Some authentication plugins will need more control than simply checking credentials. Some plugins may want to make use if their own login forms, or redirect to other sites to handle the authentication. Xataface's [http://dataface.weblite.ca/Dataface_AuthenticationTool authentication tool] is up to the task, as virtually all parts of the login/logout process can be overridden and customized in your module. The previous example shows how the getCredentials() method can be overridden, but there are other methods that can be implemented to customize the login process as well. e.g. * showLoginPrompt() - This method is called when it is time to display the login prompt for the user. It could also be made to redirect to another site that has a login prompt. * logout() - This is called when the user tries to log out. If there are any special cookies of variables that need to be cleaned up to facilitate a successful logout, you could implement this method. * [http://dataface.weblite.ca/getLoggedInUser getLoggedInUser()] * [http://dataface.weblite.ca/getLoggedInUsername getLoggedInUsername()] * getCredentials() - Handles the obtaining of credentials from the request or from the environment. * authenticate() - Handles the whole login process ===See Also:=== * [[Application Delegate Class]] for before/after login/logout triggers that may be more appropriate in some circumstances than creating a custom authentication plugin. * [[authentication|Xataface Authentication]] en 0 modules 30 Xataface Modules [[toc]] Xataface provides a number of hooks that allow developers to create modules to extend its functionality. This page lists a handful of the currently available modules. * [[ShoppingCart|Shopping Cart]] - Converts your application into a shopping cart. * [[Filemaker]] - Export record sets as Filemaker XML. * [[DataGrid|Data Grid]] - Editable Datagrid. * [[Email]] - Convert your database into a email list. Send email to any found set. * [[reCAPTCHA module]] - A reCAPTCHA module to add CAPTCHA support to your Xataface forms. * [[XataJax]] - Platform for building Web 2.0 AJAX applications with Xataface. Will be a standard component for Xataface starting with version 1.3. ==Module Installation== You can add modules in either: # DATAFACE_PATH/modules directory (since 1.0) # DATAFACE_SITE_PATH/modules directory (since 1.3) Modules in the DATAFACE_SITE_PATH directory will supersede modules in the DATAFACE_PATH/modules directory (since 1.3). To activate a module for your application you also need to add an entry to the [[_modules]] section of your [[conf.ini file]]. Each module will come with its own installation instructions. ==Authentication Modules== Modules to add alternative authentication methods are added to the modules/Auth directory. ==Developing Your Own Modules== See [[Module Developers Guide]]. modules, captcha en 0 xataface_templates 23 xataface_templates ==Xataface Templates== [[toc]] Xataface uses the [http://smarty.php.net Smarty Template Engine] to power all of its templates. Templates are stored in the one of the following locations: * %XATAFACE_ROOT%/Dataface/templates * %SITE_ROOT%/templates Where %XATAFACE_ROOT% is the Xataface directory (includes files such as dataface-public-api.php), and %SITE_ROOT% is the path to your application. You may also have subdirectories within these templates directories. ===Cascading Templates=== Xataface uses a simple cascading technique for deciding which template to use. If there are templates in the %SITE_ROOT%/templates and %XATAFACE_ROOT%/Dataface/templates directories with the same name, then Xataface will use the one in the %SITE_ROOT%/templates directory. In this way, you are able to override any of Xataface's core templates by adding one of the same name to your %SITE_ROOT%/templates directory. The most common template to override is the Dataface_Main_Template.html template which defines the look and feel for the entire application (e.g. header, footer, etc...). Hence, if you wanted to customize the look & feel of your application, you would likely start by copying %XATAFACE_ROOT%/Dataface/templates/Dataface_Main_Template.html into the %SITE_ROOT%/templates directory and make modifications to it as desired. ===Useful Smarty Tags introduced by Xataface=== In addition to the standard set of Smarty tags, Xataface templates provide some of its own. ==Xataface Templates== Xataface uses the [http://smarty.php.net Smarty Template Engine] to power all of its templates. Templates are stored in the one of the following locations: * %XATAFACE_ROOT%/Dataface/templates * %SITE_ROOT%/templates Where %XATAFACE_ROOT% is the Xataface directory (includes files such as dataface-public-api.php), and %SITE_ROOT% is the path to your application. You may also have subdirectories within these templates directories. ===Cascading Templates=== Xataface uses a simple cascading technique for deciding which template to use. If there are templates in the %SITE_ROOT%/templates and %XATAFACE_ROOT%/Dataface/templates directories with the same name, then Xataface will use the one in the %SITE_ROOT%/templates directory. In this way, you are able to override any of Xataface's core templates by adding one of the same name to your %SITE_ROOT%/templates directory. The most common template to override is the Dataface_Main_Template.html template which defines the look and feel for the entire application (e.g. header, footer, etc...). Hence, if you wanted to customize the look & feel of your application, you would likely start by copying %XATAFACE_ROOT%/Dataface/templates/Dataface_Main_Template.html into the %SITE_ROOT%/templates directory and make modifications to it as desired. ===Useful Smarty Tags introduced by Xataface=== In addition to the standard set of Smarty tags, Xataface templates provide some of its own. {| class="listing listing2" |- ! Name ! Description ! Version |- | [[templates:tags:use_macro|use_macro]] | Include another template with the option to override certain sections. | 0.6 |- | define_slot | Marks a section that can be overridden by other templates that include this one via the use_macro tag. | 0.6 |- | fill_slot | Overrides content in a template that has been included via the use_macro tag. | 0.6 |- | block | Marks an insertion point where content can be inserted by delegate classes and modules. | 0.6 |- | load_record | Loads a [http://dataface.weblite.ca Dataface_Record] object from the database to be used in the template. | 0.6 |- | group | Groups an array of records together based on a field value. | 0.6 |- | img | Displays a thumbnail of an image. | 0.6 |- | actions | Loads an associative array of actions defined in the actions.ini file, based on certain criteria. | 0.6 |- | actions_menu | Displays a menu of actions based on certain criteria. | 0.6 |- | record_actions | A specialization of the actions_menu tag. This displays a menu of actions only in the record_actions category. | 0.6 |- | record_tabs | A specialization of the actions_menu tag. This displays a menu of actions only in the record_tabs category. | 0.6 |- | result_controller | Displays the paging controls for the current table's records. Use this for any listing of records. | 0.6 |- | result_list | Displays the result list (from the list tab) for the current request. | 0.6 |- | related_list | Displays the related records list for the current request. | 0.6 |- | bread_crumbs | Displays the bread crumbs for the current request. | 0.6 |- | search_form | Displays the find form for the current table. | 0.6 |- | language_selector | Displays a menu to select the user's preferred language. | 0.6 |- | next_link | Displays a link to the next XXX records. | 0.6 |- | prev_link | Displays a link to the previous XXX records. | 0.6 |- | jump_menu | Displays the select list of the records found in this found-set so that the user can jump directly to any record. | 0.6 |- | limit_field | Displays a text field for the user to select the number of records to display per page. | 0.6 |- | result_index | Displays the index of pages (1 to XXX) for this query. | 0.6 |- | summary_list | Displays a list of records in the current found set using a summary format rather than the regular table format. | 0.6 |- | sort_controller | Displays a control to sort the results on any column. | 0.6 |- | glance_list | Displays a simple, brief list of records matching certain criteria. | 0.6 |- | record_view | Loads structured data for a record as required for the view tab. | 0.6 |- | feed | Generates a link to an RSS feed based on certain criteria. | 0.6 |- | translate | Display a section of text in the user's selected language. (i18n). | 0.6 |- | if_allowed | The contents of this block are shown only if the user has certain permissions. | 0.6 |- | editable | Make a section of the page editable using AJAX. | 0.6 |- | abs | Convert a URL into an absolute URL. | 0.6 |} ===Useful Template Variables=== Xataface makes certain variables available to every template: {| class="listing listing2" |- ! Name ! Description ! Version |- | $ENV.REQUEST | Reference to the $_REQUEST array (HTTP Request parameters, both GET and POST) | 0.6 |- | $ENV.SESSION | Reference to the $_SESSION array (the session variables) | 0.6 |- | $ENV.DATAFACE_PATH | The file system path to the Xataface directory (i.e. the directory containing all of the Xataface files such as dataface-public-api.php). | 0.6 |- | $ENV.DATAFACE_URL | The URL to the Xataface directory. | 0.6 |- | $ENV.DATAFACE_SITE_PATH | The file system path to your application directory. (i.e. the directory containing your conf.ini and index.php files). | 0.6 |- | $ENV.DATAFACE_SITE_URL | The URL to your application directory. | 0.6 |- | $ENV.DATAFACE_SITE_HREF | The URL to your application's script. This differs from the $ENV.DATAFACE_SITE_URL variable in that this also includes the script name. | 0.6 |- | $ENV.SCRIPT_NAME | Same as $ENV.DATAFACE_SITE_HREF | 0.6 |- | $ENV.APPLICATION | A reference to the application's conf array (i.e. the parsed contents of the conf.ini file). | 0.6 |- | $ENV.APPLICATION_OBJECT | A reference to the Dataface_Application object for the application. | 0.6 |- | $ENV.SERVER | A reference to the $_SERVER array. | 0.6 |- | $ENV.QUERY | A reference to the current query (i.e. Dataface_Application::getInstance()->getQuery()) | 0.6 |- | $ENV.action | The name of the current action as specified by the -action REQUEST parameter. | 0.6 |- | $ENV.table | The name of the current table as specified by the -table REQUEST parameter. | 0.6 |- | $ENV.table_object | A reference to the current table. | 0.6 |- | $ENV.relationship | The name of the current relationship as specified by the -relationship REQUEST parameter. | 0.6 |- | $ENV.limit | The value of the -limit REQUEST parameter. This is the number of records to show per page. | 0.6 |- | $ENV.start | The value of the -start REQUEST parmeter. This is the starting point in the result set which is currently being displayed. | 0.6 |- | $ENV.resultSet | A reference to the [http://dataface.weblite.ca/Dataface_QueryTool Dataface_QueryTool] object for this result set. | 0.6 |- | $ENV.record | A reference to the [http://dataface.weblite.ca/Dataface_Record Dataface_Record] object that is matched by the current query. | 0.6 |- | $ENV.mode | The name of the current mode. e.g. find, list, browse | 0.6 |- | $ENV.language | The 2-digit ISO language code that is currently selected as the user's preferred language. | 0.6 |- | $ENV.prefs | A reference to the preferences array ($conf['_prefs']) | 0.6 |- | $ENV.search | The value of the current full-text search (i.e. the search that was entered into the upper right search field. | 0.6 |} ==Smarty Plugins== One of the most powerful features of [http://www.smarty.net Smarty] is its pluggable architecture. You can easily add your own custom plugins to a registered "plugins" directory to add functions, modifiers, blocks, and other features to your templates. Prior to Xataface 2.0, you Smarty plugins could only be placed in the ''lib/Smarty/plugins'' directory of the Xataface distribution folder. This is not very conducive to Xataface updates, though. In general it is best practice to not change anything inside the xataface directory. Most other configuration and extensions can be handled by making changes to your application's directory which override corresponding functionality in Xataface. As of Xataface 2.0, you can create a directory named ''plugins'' to your application directory, Smarty knows to look in this directory for plugins. For versions of Xataface prior to 2.0, you can make a small modification to the SkinTool to also add support as desribed in [http://xataface.com/forum/viewtopic.php?f=4&t=6722 this post]. ===Example Plugin=== The following is an example Smarty plugin adapted from [http://www.smarty.net/docs/en/plugins.functions.tpl this page] but modified slightly to work in Xataface. It is a simple "eightball" plugin that adds a tag {eightball} to Xataface that you can use in any of your templates. Whenever this tag is rendered it outputs one of a set of predefined strings randomly. # Add a ''plugins'' directory to your application directory. i.e. ''path/to/app/plugins'' # Add a file inside this ''plugins'' directory called ''<nowiki>function.eightball.php</nowiki>'' with the following content:<code> <?php /* * Smarty plugin * ------------------------------------------------------------- * File: function.eightball.php * Type: function * Name: eightball * Purpose: outputs a random magic answer * ------------------------------------------------------------- */ function smarty_function_eightball($params, Dataface_SkinTool $template) { $answers = array('Yes', 'No', 'No way', 'Outlook not so good', 'Ask again soon', 'Maybe in your reality'); $result = array_rand($answers); return $answers[$result]; } </code> # If you compare this function to the original example in [http://www.smarty.net/docs/en/plugins.functions.tpl the smarty tutorial] you'll notice that the 2nd parameter has been changed to type ''Dataface_SkinTool'' from ''Smarty_Internal_Template''. If you don't make this change, you will get a fatal error when you try to use the tag. This function defines an ''{eightball}'' tag that can be added to any Smarty template in Xataface. # Next we'll create a template that uses this tag. If your application doesn't have a ''templates'' directory, create one now (i.e. path/to/app/templates). # Add a file inside your templates directory called ''testing.html'' with the following content:<code> The eight ball says {eightball} </code> # Now we need to display this template somewhere in our interface. In this case, we'll choose the ''before_record_content'' block. (This will render the template before the main section of the view tab). Add the following method to your [[Application_Delegate_Class]]:<code> function block__before_record_content(){ df_display(array(), 'testing.html'); } </code> # Now if you load your application in a web browser and navigate to the details view for a record, you should see something like the following: <nowiki><img src="http://media.weblite.ca/files/photos/Screen_Shot_2012-04-16_at_12.33.01_PM.png?max_width=640"/></nowiki> ===See also:=== * [http://www.xataface.com/documentation/tutorial/getting_started/changing-look-and-feel Changing the Look & Feel of Xataface] (From the Getting Started Tutorial) * [http://www.xataface.com/documentation/tutorial/customizing-the-dataface-look-and-feel Cusomizing the Xataface Look & Feel] Tutorial templates, plugins, smarty en 0 _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 __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 __global__ 106 __global__ section for the fields.ini file Return to [[fields.ini file]] [[toc]] ===Synopsis=== The fields.ini file supports a __global__ section that applies to all fields in the current table. This is particularly useful for setting up default functionality that you wish to see on all fields except a few. For example you may wish to have all fields hidden from list view by default, and only explicitly enable a few. Same for CSV export or the details form. ===Example 1: Hiding All Fields from List View=== In the fields.ini file: <code> [__global__] ;; hide all of the fields from list view visibility:list=hidden [first_name] ;; show the first name in list view visibility:list=visible [last_name] visibility:list=visible ;;.... etc.... </code> In the above example we used the __global__ section to declare that we want all fields to be hidden from list view by default. Then we explicitly showed first_name and last_name in list view. In this case only first_name and last_name will appear in the list view. ==See Also== *[[fields.ini file]] *[[visibility:list]] __global__, fields.ini, visibility:list en __prefs__ 9 __prefs__ ==__prefs__ fields.ini Section== A global section of the [[fields.ini file]] that sets the preferences for the given table and its records. E.g. <code> [__prefs__] hide_posted_by=1 ; Hides the "Posted by" text in glance lists (e.g. related records in the view tab). hide_updated=1 ; Hides the "Updated" text in glance lists (e.g. the related records in the view tab). </code> ===Available Preferences=== Ultimately, all of the preferences available at a global level should be available here, however currently this is not the case and only selected preferences are available at the table level. {| class="listing listing2" ! Name ! Description ! Version |- | [[hide_posted_by]] | HIdes the ''posted_by'' text in glance lists. E.g. In the view tab of a record, the related records are shown in the left column. This will hide the ''posted_by'' text next to each related record. | 1.0b4 |- | [[hide_updated]] | Hides the ''updated'' text in glance lists. E.g. In the view tab of a record, the related records are shown in the left column. This will hide the ''updated'' text next to each related record. | 1.0b4 |- |} en 0 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