Introduction to the Xataface API

Back to the wiki

Synopsis

Xataface is provides an API to help in developing your own custom actions. This API includes objects and functions to more easily interact with the database (i.e. search, edit, delete, and save records), build forms, use templates, and more. This section of the wiki endeavors to highlight some of the more useful and commonly used aspects of the API.

The dataface-public-api.php Facade

Much of the functionality provided by the Xataface API is wrapped up easy-to-use functions which are made available in the dataface-public-api.php script, which is always present in a Xataface application (it is loaded at the beginning of your index.php file).

Some Common Tasks

Loading a Single Record from the Database

// Load record from 'people' table matching person_id=10
$record = df_get_record('people', array('person_id'=>10)); 

// Load record from people table with first_name 'John' and last_name 'Smith' 
$record2 = df_get_record('people', array('first_name'=>'=John', 'last_name'=>'=Smith'));

// $record and $record2 are Dataface_Record objects.
echo "Loaded Person: ".$record->val('person_id').
      " named ".$record->val('first_name').' '.$record->val('last_name');

In the above examples we load a Dataface_Record object and use the val() method to display particular field values.

The 2nd arguments of df_get_record() is an array which serves as a query. See URL Conventions for more examples of the types of queries that you can provide here.

Loading a set of records from the Database

//  Load the first 30 canadians from the people table
$people = df_get_records_array('people', array('nationality'=>'=canadian'));
foreach ( $people as $person){
    // $person is a Dataface_Record object
    echo "<br>Person ".$person->val('person_id')." is named ".$person->val('first_name');
}

Caveat: Note that when loading records using df_get_records_array() it only loads a preview of each record for memory's sake. A preview of the record is the same as a full record except that all fields are truncated to be less than 255 characters. If you have long text fields that you need to load, then these will be truncated. There are a few different solutions if you need to load the entire contents of a long field, including:

• Use df_get_record instead. (This is only preferable if you are only loading a single record).
• Use the struct fields.ini file directive on the field to designative the field contents as a 'stucture' that should never be truncated.
• Use the extended form of df_get_records_array() with the 5th parameter (preview) set to false. E.g.

  $people = df_get_records_array('people',array(), null, null, false);

Editing and Saving a Record

$person = df_get_record('people', array('person_id'=>10));

// Using setValue() to set a single field value.
$person->setValue('first_name', 'Peggy');

// Using setValues() to set multiple field values at once
$person->setValues(array('first_name'=>'Peggy', 'last_name'=>'Sue'));

// Commit the changes to the database
$person->save();