Xataface svn repository

One good thing you should do if you are planning to develop an application with Xataface is to actually checkout the svn repository of Xataface. The most recent code for Xataface which includes bug fixes and features will be added to this repository. I used tortoiseSVN as my svn client, and to checkout you simply use this address:

http://weblite.ca/svn/dataface/core/trunk

Keeping your database up to date throughout development

A major development issue in any computer project that requires a database is keeping your database structure keep to date with the different versions of the code. Keep database up to date is always a difficult because you cannot simply put it under version (thou technically you can because you can create an sql statement that represents the entire database). But Xataface provides an interesting way to handle this through the use of an Installer.php (make sure it's capital I) class in the conf folder.

The idea behind this is your application will be associated with a version number which you specify in the database. And then Xataface will run the Installer.php file which checks which version is in the database, and then it will call a bunch of functions that update the database table. The functions are named after the version number they should be applied to. So for example:

<?php
class conf_Installer {
function update_582(){
$sql[] = 'ALTER TABLE `webpage_sites` ADD `dynamic` TINYINT(1) AFTER `require_approval`';
$sql[] = 'ALTER TABLE `webpage_sites` ADD `irrelevant_get_params` TEXT NULL AFTER `aliases` , ADD `relevant_get_params` TEXT NULL AFTER `irrelevant_get_params`';
foreach ($sql as $q){
mysql_query($q, df_db());
}
}
?>

What happens is it will see if the database version is 582 or above and then it will apply this change to the database. The this general function format can be used for any version numbers.

To actually setup the database version, we don't actually need to setup a separate database table to handle this. We make a version.txt file in the application and xataface will create a version table in the database for us. The contents of the file will look like this:

0.1 680

The 0.1 really means nothing. It is simply used to note which major release we are on. It is the second number that means something. That is the exact version number that gets stored into the database.

And by setting up these two things, it becomes extremely easy to manage the database in xataface!

SVN committing

This isn't exactly a Xataface related issue, but I found myself continually forgetting about this that I thought it would be good to blog about this so I can remember. When I have ssh'ed onto the server and I need to do a svn commit, I get an error message about not having an editor to input my svn commit message. The following piece of code fixes this:

export EDITOR=vi

Where vi is the editor program we are using. If you have something else installed on your server (and hopefully you do because vi really blows), then you can just use that.

Update: You can actually avoid having to do this by adding that exact line into your .bash_profile file. This file gets executed upon log in and runs a set of commands. So if you do this, it will always just set your editor and you won't have to worry about it anymore.

Testing Xataface on IE6 when you have Vista

So I ran into a pretty annoying problem the other day. I had to test a Xataface application on IE6 with Vista as my OS. Which basically meant I had IE7 preinstalled, and I couldn't install IE6. Ughh...annoying. I don't understand why people still use IE6, but whatever.

The best way to actually shove this is to install a virtual machine with the OS set to XP and then you can use IE6 on it. To do this follow this tutorial.

One thing you need to note is that Virtual PC 2004 does NOT work on Vista. So you actually have to use Virtual PC (VPC) 2007 . This can be found here. The "Internet Explorer 6 Testing VPC Image" is still the same.

Another annoying thing is that VPC 2007 is NOT fully supported with Vista Home edition (UGHHH...why are things to complicated!). And you'll be faced with all these messages not non-compatibility. But you are just limited from some features which I didn't bother looking directly into. But if you just want to test Xataface sites on it, then just ignore the messages and install it.

After you have loaded the VPC image, then the next step is to actually setup internet connection from inside the VPC. If you are using a LAN connection, then do this:

1. Edit


2. Settings


3. Networking


4. Adaptor 1: NAT

Try to connect now, and if you have a firewall on then you will be prompted to allow the VPC to pass it. After you "unblock" it, then everything should work!

If you are using wireless, then use this tutorial.

Adding some text when no block/slot exists

Sometimes you need to add some text to a certain template, but Xataface doesn't have the specific block or slot to use. For example, say you wanted to include some text underneath the password field in the login page for Xataface. You can't do this with blocks or slots since nothing exists underneath that field. You can however do a workaround by using javascript and the DOM concept.

For example:

function block__after_login_form(){
<script language="javascript"><!--
var div = document.createElement('div');
div.className = 'formHelp';
var text = document.createTextNode('Please enter the correct password');
div.appendChild(text);

document.getElementById('Login-Password').appendChild(div);
//--></script>
}

First thing to notice is we are using the block__after_login_form() which simply a block on that template. We are using it to include our javascript of interest. We could have actually used any block.

var div = document.createElement('div');

The first thing we do is create a div element.

div.className = 'formHelp';

Here are just giving it the css class name of formHelp which gives it a nice styling feel. This is the same style used for widget:description values.

var text = document.createTextNode('Please enter the correct password');

And then we create a textnode which contains the text of interest.

div.appendChild(text);

With out div element, we are appending the text node we just created to it.

document.getElementById('Login-Password').appendChild(div);

And finally we add our div element to our element of interest which happens to have the id of "Login-Password" This id has been assigned by Xataface itself.

And if everything works out fine, then you should see the text appear below the password field!

You can find more information about how to manipulate DOM structure using javascript here.

Directly modifying a table's attributes

While using the fields.ini is a good way to set attributes such as widget:label, description, etc sometimes you need more control. This can be accomplished by loading the table in the code and then directly modifying the fields. For example:

$usersTable =& Dataface_Table::loadTable('users');
$myfield =& $usersTable->getField('password');
$myfield['widget']['description'] = "Hello world";

The first line of code is retrieving a reference to the users table which is a Xataface table object. The table object comes with some functions that allow you with. One of them being the getField() function which would then retrieve a reference to the password field variable. From there we can access the widget attributes using arrays.

Using Xataface to create forms

You can leverage off the power of Xataface to create forms allowing users to submit data to your tables. Here is some code to allow you do that, I'll go into more explanation after:

$app =& Dataface_Application::getInstance();
$record =& $app->getRecord();
$form =& df_create_edit_record_form($record, array('FirstName','LastName'));

$form->addElement('hidden','-action','myaction');
if ($form->validate() ){
$res = $form->process(array(&$form, 'save'), true);
// could return false or PEAR_Error to indicate error.
header('Location: '.DATAFACE_SITE_HREF.'?-action=foo&--msg=Success');
exit;
}
$form->display();

The first two lines are basically grabbing a reference to the xataface application and the current record loaded.

$form =& df_create_edit_record_form($record, array('FirstName','LastName'));

This line will create a xataface form object which represents the same table that this record is taken from. It will only display the FirstName and LastName fields though since the second parameter allows you to select which fields to display. Because it is a edit record form, it will fill in the values of the form with the values from the record that was sent in through the parameter. You can alternatively use the df_create_new_record_form() to create a new form entirely.

$form->addElement('hidden','-action','myaction&#

This line adds a hidden element to the form and then sets the name of the hidden element to be -action. It is basically used to allow the form to figure out what action to take after it has been submitted. Generally, we set the action to be the same action as the current page and then allow the form to be validate (explained below)

if ($form->validate() ){
$res = $form->process(array(&$form, 'save'), true);
// could return false or PEAR_Error to indicate error.
header('Location: '.DATAFACE_SITE_HREF.'?-action=foo&--msg=Success');
exit;
}

The form first gets validated for valid values. And then if it returns true, it will then process the form and basically save the data to the database. From there, we need to redirect the user to the next location. We always put an exit statement after the header() to make sure the code stops after the redirect. Because should the redirect for some reason fail, we don't want the user to be see the form again.

$form->display();

Finally, if the form was not validated (ie. not submitted before, or values wrong) we need to display form which is what this line does.

And there you go! That's how you can use Xataface to help you create forms!

Using Xataface to search for NULL

If there is a row in a table that contains a NULL value, you can use Xataface to search specifically for that record but it's not as trivial as searching for NULL. You have to set it to an equal sign which will basically look for exact matches to nothing. For example:

$temp_types = df_get_records_array('n1_tire_types', array('-limit'=>200, 'parent_id' => "="));

Will look for columns in the n1_type_types table with a parent_id of empty or NULL.

Secure Display

If you are using Xataface as your backend management, and also as a front end (through the use of actions and templates) this can save you lots of time. However, sometimes you set permissions on records that you don't want users seeing if they are in the backend. For example, the application could prevent any users not logged in from seeing the backend by returning:

return Dataface_PermissionsTool::NO_ACCESS();

However this could have adverse effects as in the front end some records are no longer viewable because of this. One way to solve this is to set in each of your smarty templates this small block of code which basically causes all records to ignore all permissions:

{php}
$pt =& Dataface_PermissionsTool::getInstance();
$pt->setContext($pt->PUBLIC_CONTEXT());
{/php}

output cache

One of the things you can do on a live xataface site is turn on caching to allow the server to just the information in RAM rather than continue to hit the database for information each time. You can do this by simply entering this in the conf.ini:

[_output_cache]
enabled=1

But there comes a problem sometimes where you need the data to appear right away and not have the server continue to use the cache (at least until the server refreshes the cache). If you ever need to do this, you can enter this into manually just modify the url query to include this:

&--refresh-apc=1

This cause the server to automatically hit the database to refresh the cache. A pretty nice hack.