# Data manipulation

xCRUD use loadable libraries for data manipulation. You can use static functions in the classes, methods, objects, or simply a set of procedural functions. You need to specify the path to your library functions, and xCRUD connects itself. xCRUD will call own functions.php file when path is not defined. xCRUD instance will be always available in your function as a last parameter.

INFO

callable - [String] method to call. For class methods, use an array, e.g. array('class', 'method').

# $postdata

The object, which represented xCRUD's form data sent to server side. It has the following methods

  • $postdata->get( field ) - returns value of a field or FALSE if field is not exist.
  • $postdata->set( field, value ) - sets new value in a field or creates new field in $postdata. Returns nothing. You no need to use unlock_field() method anymore.
  • $postdata->to_array() - returns all data in array.
  • $postdata->del( field ) - removes field from dataset. Be careful, this can make errors in application.

# before_insert (callable, path)

Allows you to prepare the data before inserting it into the database. Takes an callable in first parameter and the library path in second. Your function should take postdata object in the first parameter, xCRUD's instance in second and no need to return anything.

// function in functions.php
function hash_password($postdata, $xcrud){
    $postdata->set('password', sha1( $postdata->get('password') ));
}

// creating action
$xcrud->before_insert('hash_password'); // automatic call of functions.php
//or
$xcrud->before_insert('hash_password', 'functions.php'); // manualy load

# before_update (callable, path)

Allows you to prepare the data before updating the records in the database. Takes a callable as the first parameter and the library path in second. Your function should take an array of data in the first parameter and the same return. As well as optionally the primary key in the second parameter.

// function in functions.php
function hash_password($postdata, $primary, $xcrud){
    $postdata->set('password', sha1( $postdata->get('password') ));
}

// creating action
$xcrud->before_update('hash_password');

# after_insert (callable, path), after_update (callable, path)

Allow you to pass data and primary key after upgrading to the custom function. The syntax is the same as in before_update (), except that the function is not obliged to return something.

# before_remove (callable, path), after_remove (callable, path)

Sends to user-defined function only the primary key record to be deleted in the first parameter. The syntax is the same as in previous examples. User-defined function is not obliged to return something.

// function in functions.php
function delete_user_data($primary, $xcrud){
    $db = xCRUD_db::get_instance();
    $db->query('DELETE FROM gallery WHERE user_id = ' . $db->escape($primary));
}

// creating action
$xcrud->before_remove('delete_user_data');

# column_callback (column, callable, path)

Allows you to define custom layer for your column data.

$xcrud->column_callback('name','add_user_icon');

functions.php

<?php
function add_user_icon($value, $fieldname, $primary_key, $row, $xcrud)
{
   return '<i class="icon-user"></i>' . $value;
}
?>

# $row

Full current row.

# field_callback (field, callable, path)

Allows you to define custom layer for your edit field.

$xcrud->field_callback('name','nice_input');

functions.php

<?php
function nice_input($value, $field, $priimary_key, $list, $xcrud)
{
   return '<div class="input-prepend input-append">' 
        . '<span class="add-on">$</span>'
        . '<input type="text" name="'.$xcrud->fieldname_encode($fieldname).'" value="'.$value.'" class="xcrud-input" />'
        . '<span class="add-on">.00</span>'
        . '</div>';
}
?>

# $list

All fields data

# fieldname_encode()

This encodes field name in compatible format.

You can use data-required and data-pattern attributes, and unique class.

IMPORTANT

You need to use xCRUD-input class for your custom inputs to make its usable by xCRUD.

# replace_insert(callable, path), replace_update(...), replace_remove(...)

Replaces standsrt xCRUD actions (insert, update, remove) by custom function. Each of this methods passes in the the target function its parameters.

Target function for replace_remove()

function remove_replacer($primary_key, $xcrud){ ... }

Target function for replace_insert()

function insert_replacer($postdata, $xcrud){ ... }

Target function for replace_update()

function update_replacer($postdata, $primary_key, $xcrud){ ... }

$xcrud - xCRUD current instance object.

IMPORTANT

replace_insert() and replace_update() methods must return value of primary key!

# call_update( postdata, primary_key )

You can call xCRUD update method in your replace_insert(), replase_update(), replace_remove() target functions:

$xcrud->call_update($postdata, $primary_key);

# Upload callbacks

# before_upload(callable, path)

Runs when files was sent to a server, but not processed yet.

# after_upload(callable, path)

File was uploaded and moved to deinstanation folder (but not resized yet, if image).

# after_resize(callable, path)

File was already resized. Available only for images.

Callback function example

function file_callback($field,$filename,$file_path,$config,$xcrud){
    ...
}

Parameters

  • $field - full field name (table and culumn with dot separator)
  • $filename - name of the file (not available for before_upload())
  • $file_path - full file path with file name (not available for before_upload())
  • $config - array with parameters from change_type() method (4th parameter).
  • $xcrud - xCRUD instance

# Other callbacks

# before_list(callable, path)

Can run before grid will be displayed.

// function in functions.php
function before_list_callback($grid_data, $xcrud){
    print_r($grid_data);
}

# before_create(callable, path) , before_edit(...), before_view(...)

Can run before details view will be displayed.

// function in functions.php (before edit/view)
function before_details_callback($row_data, $primary, $xcrud){
     echo $row_data->get('username'); // like 'postdata'
}
// function in functions.php (before create, there is no primary)
function before_details_callback($row_data, $xcrud){
     echo $row_data->get('username'); // like 'postdata'
}

# Database instance

In all external files you can use xCRUD database instance:

$db = xCRUD_db::get_instance();
$db->query(...) // executes query, returns count of affected rows
$db->result(); // loads results as list of arrays
$db->row(); // loads one result row as associative array
$var = $db->escape($var); // escapes variable, ads single quotes
$db->insert_id(); // returns last insert id

# Upload Callback

# Control file type with upload callback (quick sample):

$xcrud->after_upload('after_upload_example');

functions.php

function after_upload_example($field, $file_name, $file_path, $params, $xcrud){
    $ext = trim(strtolower(strrchr($file_name, '.')), '.');
    if($ext != 'pdf' && $field == 'uploads.simple_upload'){ // you can use other check-in
        unlink($file_path);
        $xcrud->set_exception('simple_upload','This is not PDF','error');
    }
}

# Additional variables

These methods allow you to send custom data in xCRUD's templates or in calback functions.

# set_var( var_name, value )

Set user variable

# get_var( var_name )

Get user variable

# unset_var( var_name )

Unset user variable

# Interactive ajax callbacks

You can easy create some actions with callback on server side in xCRUD's grid (see example)

First you must create callback (like other callbacks) with method 'create action()'.

# create_action( action_name, callable, [path] )

Parameters

  • action_name - name of your action
  • callable - name of your callback (function or method)
  • path - (optional) path to your file with function, default is 'functions.php'.
$xcrud->create_action('my_action','my_function'); 

Then, create function in your functions.php (or you can use other file)

function my_functions($xcrud){
    // some manipulations
} 

Finally, create button or link (or any) with specific class and data attributes. Simpliest button will be:

<button class="xCRUD-action" data-task="action" data-action="my_action">GO!</button> 

This is required. You can define any other data attributes and all of them will be sent with action. To receive them in callback function you must call get() method with your attribute name in parameter (without data- prefix):

function my_functions($xcrud){
    $myvalue = $xcrud->get('myvalue'); // data-myvalue attr.
    // some manipulations
}  

# Returning errors from callback function

You can do you own validation or something more in any callback function during saving and return user back to form.

# set_exception( [fields] , [text], [message_type] )

Parameters

  • fields - (Optional) highlighted fields in form,
  • text - (Optional) error message,
  • message_type - (Optional) type of error message (error, note, success, info), just css class for message box, default is 'error'.
// function in functions.php
function hash_password($postdata, $primary, $xcrud){
    $pass = $postdata->get('password');
    if(preg_match('/[a-zA-Z]+/u',$pass) && preg_match('/[0-9]+/u',$pass)){
        $postdata->set('password', sha1( $pass ) );    
    }
    else{
        $xcrud->set_exception('password','Your password is too simple.');
    }
}
Last Updated: 3/11/2021, 5:43:48 PM