viewable_editable_fields 180 How to make a field editable for some users and only viewable for some other users If we want only some users to edit a field and some other users only to view that field, then we need to define a '''fieldX__permissions()''' method for that field which gives desired permissions for specific users. One solution is as below. ==permissions.ini== <code> [Field Viewer] view=1 edit=0 new=0 [Field Editor extends Field Viewer] new=1 edit=1 </code> ==TableX.php (Delegate class of TableX)== <code> function fieldX__permissions(&$record) { $user=&Dataface_AuthenticationTool::getInstance()->getLoggedInUser(); if($user) { if($user->val('usernameField')=="UserX") $role='Field Viewer'; else if($user->val('usernameField')=="UserY") $role='Field Editor'; return Dataface_PermissionsTool::getRolePermissions($role); } return Dataface_PermissionsTool::NO_ACCESS(); } </code> en 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 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 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 XataJax 113 Introduction to XataJax [[toc]] Xataface 1.3 comes with a new module [[XataJax]] which comes installed standard. [[XataJax]] serves as a foundation for Javascript/AJAX powered Xataface applications and will hopefully usher in a new fresh generation of Xataface powered applications. ===Features=== Xataface provides pieces of infrastructure: # [[XataJax Compiler|A Javascript/CSS Compiler & Linker]] # A Javascript component library & API ====The Javascript/CSS Compiler & Linker==== Web 2.0 and HTML 5 is a great platform for application development, but it presents a challenge when it comes to developing large-scale, robust applications. It can be difficult to manage applications that consist of dozens or even hundrends of javascript libraries, some of which depend on each other. The XataJax compiler provides a solution to this problem by providing a just-in-time compilation of all of the javascripts that are necessary to service a particular request. It doesn't actually compile your Javascript into machine code, it just aggregates and minifies all of the javascript code together into a single file at runtime so that you don't have to worry about figuring out exactly which libraries you need to import in each template. This has 2 key benefits: 1. Load time. By having all of the scripts grouped into a single file, it is much quicker for the client to load the your scripts. 2. Code organization. Since the compiler will automatically resolve the script dependencies, you can keep your code nicely organized, which produces a far more maintainable source code base. ====The Javascript Component Library & API==== The 2nd part of the XataJax module is a new API that will help you develop rich Web 2.0 applications that interact with your database. The will allow you to build forms more dyanmically with Javascript, or load, update, and delete records directly using a javascript API. The goal is to eventually expose all important Xataface functionality via the XataJax API. Additional modules may build on top of this API to produce alternative dynamic interfaces for Xataface using existing web UI component libraries like JQueryUI or Sencha. XataJax, Ajax, Web 2.0 en XataJax_Compiler 114 Introduction to the XataJax Compiler Return to [[XataJax]] '''DISCLAIMER''': This page introduces features that require Xataface 1.3 or higher. At present (Jan. 2011) only Xataface 1.2.6 has been released to the public. [[toc]] ===Synopsis=== The XataJax compiler is a Javascript CSS compiler and linker that comes with the [[XataJax]] module and will be a standard part of Xataface starting in version 1.3. It provides a mechanism to process and compile (or so to speak) all of the javascripts required for a page request at the time that the page is requested. This results in a more scalable, manageable javascript and CSS source base - and in improved performance for your applications. ===Compiler Directives=== {| class="listing listing2" |- ! Name ! Description ! Version |- | [[xatajax include directive|include]] | Includes another javascript file inside the current one in place of this directive. Sample code:<code>//include <myscript.js></code> | XataJax 0.1 Xataface 1.3 |- | [[xatajax require directive|require]] | Includes another javscript file inside the current one only if that file hasn't already been included. Sample code: <code>//require <myscript.js></code> | XataJax 0.1 Xataface 1.3 |- | [[xatajax require-css directive|require-css]] | Includes a CSS script in the CSS file. This will will search in the [[Dataface_CSSTool]] include path for the script. Sample code: <code>//require-css <mystyles.css></code> | XataJax 0.1 Xataface 1.3 |- | [[xatajax load directive|load]] | Loads the specified Javascript file in a separate script tag. This enables you to reference other scripts without including them in the same bundle, allowing for more effective caching. Sample code: <code>//load <myscript.js></code> | XataJax 0.1 Xataface 1.3 |} ===How it Works=== The XataJax compiler works similar to a regular code compiler. It provides 4 server-side directives to allow you to express dependencies between scripts and stylesheets: # '''include''' : Includes another javascript file inside the current script in place of the '''include'' directive. # '''require''' : Includes another javascript file inside the current script (if it hasn't already been included) - i.e. if a script is included twice with a require directive, it will only actually be included once. # '''load''' : Registers a dependency to another script, but doesn't include it in the same bundle. This may be used if your script requires code from another javascript, but you don't want it all to be bundled into the same javascript file. This may help with caching in certain cases. # '''require-css''' : Registers a dependency to a CSS file. If your script depends on a CSS file, then it can be registered in this way. ===Brief Example=== ''scriptA.js'': <code> //require <scriptB.js> alert('You are in script A'); </code> ''scriptB.js'': <code> alert('You are in script B'); </code> If you loaded ''scriptA.js'', it would actually result in the following javascript being executed: <code> alert('You are in script B'); alert('You are in script A'); </code> Notice that it included ''scriptB.js'' inside script A before the alert of script A. That is why script B's alert comes first. Note that this example won't work if you simply try to load scriptA.js directly in Apache. These directives are only evaluated if the scripts are served by Xataface. Here is a simple Xataface action that demonstrates how to use this in your Xataface script. ====Creating a custom action==== In your application directory, create an ''actions'' directory if you don't already have one. Then create a single file named ''hello.php'' with the following content: <code> class actions_hello { function handle($params){ $jsTool = Dataface_JavascriptTool::getInstance(); $jsTool->addPath('js', DATAFACE_SITE_URL.'/js'); $jsTool->import('scriptA.js'); echo '<html><head></head><body>'.$jsTool->getHtml().'</body></html>'; exit; } } </code> '''About this code:''' <code>$jsTool = Dataface_JavascriptTool::getInstance();</code> We start by obtaining an instance of the JavascriptTool. This is the object that does all of the magic of compiling your scripts and managing dependencies. <code>$jsTool->addPath('js', DATAFACE_SITE_URL.'/js');</code> This line adds the ''js'' directory to the tool's include path, and specifies (with the 2nd parameter) the URL to reach this directory also. The JavascriptTool works like most source code compilers. You need to give it the path where it can expect to find its libraries and scripts. Only paths that you add here will be searched for javascripts. You can add as many paths as you like. By default it will have the DATAFACE_PATH/js and the XATAJAX_PATH/js directories in the include path so you can directly reference any scripts in those directories always. <code> $jsTool->import('scriptA.js');</code> This is where we declare that we want to use ''scriptA.js'' in the current request. This line then assumes that the scriptA.js file is located in one of the directories of the current include path. In our case we make sure that it resides in the DATAFACE_SITE_PATH/js directory. <code>echo '<html><head></head><body>'.$jsTool->getHtml().'</body></html>';</code> On this line we simply output the HTML script tags that the javascript tool generates linking to our resulting script. Now we can test our our action by going to the page index.php?-action=hello. If everything worked correctly you should see the appropriate alert dialogs appear - first telling you you're in Script B, then telling you you're in Script A. If it doesn't work, you should check your javascript error logs to see what went wrong. '''NOTE:''' - This simple example actually shows you the step of writing out the HTML tags explicitly with the getHtml() method. If you are using a standard Xataface template that is based on the Dataface_Main_Template.html template, then this step is unnecessary because the XataJax module will automatically include this HTML just before the closing </body> tag in your pages. XataJax, compiler, javascript, css, compiler en _auth 97 _auth section of the conf.ini file [[conf.ini file|Return to conf.ini file]] [[toc]] ===Synopsis=== The ''_auth'' section of the conf.ini file includes configuration directives to enable authentication in a Xataface application. For more information about authentication and registration see [[authentication]]. This section may include the following directives: ===Directives=== {| class="listing listing2" |- ! Directive ! Description ! Required ! Default ! Version |- | users_table | The name of the table that contains your user accounts. | Yes | None | 0.6 |- | username_column | The name of the column that stores the username. | Yes | None | 0.6 |- | password_column | The name of the column that stores the password. | Required if using basic authentication. | None | 0.6 |- | auth_type | Specifies the authentication module that is being used. E.g. basic, cas, ldap, http, facebook, etc... | No | basic | 0.6 |- | allow_register | Flag to enable user registration. If this is set to 1, then a ''register'' link will appear below the login form. | No | 0 | 0.8 |- | session_timeout | Number of seconds of inactivity after which the user will be logged out. Note: Arithmetic don't work in the conf.ini, use seconds. | No | 86400 (=> 24*60*60 (24 hours)) | 1.3rc4 |} ===See Also=== * [[authentication]] - Overview of Xataface Authentication * [[conf.ini file]] - Directives available in the conf.ini file. _auth,authentication,conf.ini file,allow_register en _output_cache 45 The Xataface Output Cache <nowiki><div class="portalMessage">Note: There was a bug in the output cache affecting Xataface version 1.0 to 1.3rc1. If you are using a version of Xataface older than 1.3rc2 then you should either disable the output cache, or replace the Dataface/OutputCache.php file with one from a newer version.</div></nowiki> [[toc]] Xataface does quite a bit of heavy lifting on each page request. If your application is getting a lot of traffic that is slowing your server down, you may want to look at enabling the Xataface output cache. ===Features=== * Improve speed of application dramatically - especially for seldom updated sites. * Supports multiple languages. * Supports multiple users (each user has own cache). * Provides GZIP compression for improved performance. ===How it works?=== When you receive a request, Xataface will return a cached version of the page if the page has been accessed before. If the page doesn't yet exist in the cache it generates the page, saves it to the cache and outputs it to the user transparently. The cache is completely transparent to your users. ===Where is the cache stored?=== Xataface creates a table called ''__output_cache'' that stores all of the cached content for your application. This table stores both a GZIPed and regular version of each page. If the user's browser supports GZIP compression, Xataface will automatically return the GZIP version. This results in further performance improvements. ===What if I make changes to the database?=== Xataface records which tables were in use when a page is cached. If any of those tables are modified after the page is cached, Xataface will mark that cached page as ''out of date'' and regenerate it the next time that it is requested. ===What if I make changes to my configuration files and templates?=== The output cache will have to be manually cleared if you make any changes to your source files (e.g. PHP, templates, and INI files). Clearing the cache is as easy as deleting or emptying the ''__output_cache'' table. ===How do I enable the Cache?=== Add the following to your [[conf.ini file]]: <code> [_output_cache] enabled=1 </code> ===How do I disable the Cache?=== Simply comment out or remove the ''[_output_cache]'' section of your [[conf.ini file]]. E.g. <code> ;[_output_cache] ; enabled=1 </code> ===Configuration Options=== The following directives can be added to the ''[_output_cache]'' section of your [[conf.ini file]] to customize how your output cache works. {| class="listing listing2" |- ! Name ! Description ! Version |- | lifeTime | Number of seconds before cached page is considered ''out of date''. | 0.7 |- | tableName | The name of the table to store the cached pages. Default '__output_cache'. | 0.7 |- | ignoredTables | A comma-delimited list of tables that don't affect the output cache (i.e. these tables can be changed without causing the output cache to be refreshed. | 0.7 |- | observedTables | A comma-delimited list of tables that should affect the status of the output cache for every page (whether the table is explicitly used by the page or not). This is a useful way to tell Xataface to refresh your cache. | 0.7 |- | exemptActions | A comma-delimited list of actions that are exempt from the output cache (and thus should not be cached). | 0.7 |} output cache 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 __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