- Subscribe on the client and publish on the server, and execute functions bound to elements fast and easy, within their own contexts.
- Declarative and unobstrusive HTML instead of imperative Javascript
- AJAX file uploads for good browsers with no effort, just make the form pheryfied
- Really small footprint, no external dependencies beside jQuery
- Coded with performance and security in mind
- Code, server and client side, completely commented, all methods have docs
- Javascript config locking and Object.freeze to make it harder for tampering
- The same way you write jQuery in Javascript, you write it in PHP
- Turns static Javascript app code into a dynamic language with a chainable query builder style
- Unit tested, mocha for the javascript and PHPUnit_Selenium for PHP
- Support for old, new and upcoming jQuery functions out of the box, since nothing is hard coded
- You may nest PheryResponses the way you would with jQuery
- You may set Javascript callbacks directly from PHP
- You can call jQuery plugin functions directly from PHP (think colorbox for example)
- Built-in CSRF mechanism that makes each AJAX request signed
- Inline conditional execution using
unlessorincase - Access or call any Javascript code on the page, set/unset variables, add functions to the page on-the-fly
- Plays really well as the transport for client-side frameworks and libraries as such AngularJS, Ember.js, Knockout.js, ExtJS, Backbone
Check the a lot of examples and code at http://phery-php-ajax.net/demo.php
This library is PSR-4 Compatible
The main goal of this library is to make jQuery (and Javascript), be completely dynamic instead of static and unchangeable code, returning commands on-the-fly from the server and execute them in order on the client, while still manipulating the DOM and dealing with callbacks.
This library unleashes everything you expect from an AJAX library, with nested responses, merging and unmerging responses, direct access to the DOM element that is making the AJAX call. It's loosely based on jquery-ujs for Rails concept.
It's a straightforward and powerful AJAX library with direct integration and mapping of all jQuery functions in PHP, the mapping is extended to custom functions set by $.fn, can create elements just like $('<div/>') does, as phery.js creates a seamless integration with jQuery functions, through AJAX to PHP functions, as you can call a PHP function using AJAX
All jQuery functions listed in here are available to call directly from the PheryResponse class: http://api.jquery.com/ including any new versions of jQuery that comes out, its compatible with jQuery forever, since there are no hardcoded jQuery functions in the PHP code. No need to update phery.js, as it will continue to work with future versions of jQuery automatically (unless jQuery change anything in core that breaks any existing function).
phery.js uses HTML5 data attributes to achieve this, and no additional libraries (besides jQuery, since it's a plugin) are needed, even for Internet Explorer. Links and forms will still be able to send GET/POST requests and function properly without when no javascript isn't enabled, because it doesn't use obtrusive techniques and relies on event delegation.
Strict standards for PHP 5.3+ and advised to use jQuery 1.8+. Being just one PHP file, and one javascript file, it's pretty easy to carry around or to implement in PHP auto-load scenarios, plus it's really FAST! Average processing time is around 2ms with vanilla PHP, according to Firebug and in the demo page
The magic_quotes_gpc directive is DEPRECATED in 5.3 and REMOVED in 5.4, since you are always 100% responsible for the security of your data, so escape your text accordingly to avoid SQL injection or XSS attacks.
All AJAX requests are sent as POST only, so it can still interact with GET query strings, like paginations and such (?p=1 / ?p=2 / ...).
The code is mostly commented using phpDoc and jsDoc, for a steep learning curve, using doc-enabled IDEs, like Netbeans, Aptana, Phpstorm and Eclipse based IDEs. Also, most of the important and most used functions in jQuery were added as phpDoc (from http://api.jquery.com/), as a magic method of the PheryResponse class .
- PHP 5.3.3+
- jQuery 1.8+
- Firefox 3.6+, IE 8+, Chrome 12+, Safari 5+, Opera 10+
- Mocha unit tests for the Javascript side running against multiple versions of jQuery on the repo
- PHPUnit_Selenium test cases for Javascript/PHP testing sources on the repo
Version 2.4.0 isn't a drop-in replacement because of some changes, so you might need to update your code
- All the calls to
PheryResponse::factory()->this()must be called toPheryResponse::factory()->this - All the calls to
PheryResponse::factory()->jquery()->somemethod()must be called toPheryResponse::factory()->jquery->somemethod() - If you are using jQuery >=1.9, some functions were removed from the jQuery core, so fix your code accordingly
- If you found yourself adding
data-remotemanually to HTML elements like<a data-remote="remote">stuff</a>, you have to fix it manually or use the prefered wayPhery::link_to, since thedata-remoteis nowdata-phery-remote - The same with
data-confirm, you have to fix it manually or use the prefered wayPhery::link_to, since thedata-confirmis nowdata-phery-confirm
http://phery-php-ajax.net/docs/
Install Phery with Composer:
composer require phery/pheryIt's really simple as:
<?php
require_once 'vendor/autoload.php';
use Phery\Phery;
Phery::instance()
->set(array(
'function_name' => function($data){
return
PheryResponse::factory()
->jquery('<div/>', array('text' => 'text content'))
->appendTo('body')
->call('func', 'list', true);
}
))->process();
?>
<!doctype html>
<html>
<head>
<script src="//ajax.googleapis.com/ajax/libs/jquery/1/jquery.min.js"></script>
<script src="phery.js"></script>
<script>
function func(name, override){
/* function */
}
</script>
</head>
<body>
<?php echo Phery::link_to('Click me', 'function_name'); ?>
</body>
</html>When clicking a link with data-phery-remote, it will automatically call the "function_name" callback, that will return a response and apply everything automagically
Complete class declarations and functions at http://phery-php-ajax.net/docs/
There is an special global setting to make phery.js to not expose information about your server on exceptions, that is a static configuration Phery::$expose_paths, which is set to false by default.
If you want to know exactly which file is generating the exception, use Phery::$expose_paths = true;
Phery - The main class, that should be reused everywhere (singleton style), but you can create many instances just fine
<?php
Phery::instance($config)->(...);
?>Add a callback that will execute in all functions that are registered using Phery::instance()->set(), and can be any number of callbacks,
useful when you're going to execute the same task for all AJAX requests.
<?php
function pre_function_one($ajax_data, $callback_specific_data, $phery_instance)
{
// Trim the data, assuming every item is a string, and not an array of array
return array_map('trim', $ajax_data);
}
function pre_function_two($ajax_data, $callback_specific_data, $phery_instance)
{
// Remove empty
return array_filter($ajax_data);
}
function post_function($ajax_data, $callback_specific_data, $answer, $phery_instance)
{
Database::insert('table', $ajax_data); // key/value pairs for e.g.
// $answer can be a PheryResponse
if ($answer instanceof PheryResponse)
{
$answer->alert('Ive been post processed!');
}
return true;
}
Phery::instance()->callback(array(
'before' => array('pre_function_one', 'pre_function_two'),
'after' => array('post_function')
));
?>Add any additional data, that will be accessible to either process functions or callback
<?php
Phery::instance()
->set(array(
'delete' => 'process_delete'
))
->callback(array(
'before' => 'callback_function'
))
->data(1, 'string', array('named'=>'argument'), new myClass)
->process();
function callback_function($ajax_data, $parameters)
{
// Since we are not using named parameters, it needs to be accessed through ordinal indexes
if ($parameters[0] === 1)
{
$ajax_data['new_stuff'] = $parameters[3]->execute($parameters[1]);
}
return $ajax_data;
}
function process_delete($delete, $parameters)
{
$id = process($delete['new_stuff']);
$parameters[3]->clear();
Database::delete($id);
return PheryResponse::factory()->alert('Deleted');
}
?>Encode arguments that phery can understand (json_encode'd) that goes inside data-phery-args.
Doing it by hand can have some unwanted side effects, since the JSON must be perfectly made
<a data-phery-args="<?=Phery::args(array('id' => 1));?>" data-phery-remote="remote">Click me</a>Returns a boolean, checks if it's a AJAX request (checks for X-Requested-With header).
Set $is_phery to true to check specifically for phery.js call
<?php
if(Phery::is_ajax()){
var_dump($_POST);
} elseif (Phery::is_ajax(true)){
Phery::respond(PheryResponse::factory());
exit;
}
?>Public static function that throws a exception and return a PheryResponse with the exception.
May be registered as a handler using set_error_handler('Phery::error_handler', E_ALL); for example
Public static function that should be used only with register_shutdown_function('Phery::shutdown_handler');
having no other useful meaning
Static function that makes it easy to return a PheryResponse anywhere.
function my_own_error_handler(){
Phery::respond(PheryResponse::factory()->exception('ERROR!'));
exit;
}Set up the rendering functions for phery.view() on Javascript side. Automates the rendering of partials, and you may apply transitions between pages. Ajaxifying your website reduces the round trip by 60% less total content size, even less with GZIP
<?php
Phery::instance()->views(array(
'#container' => function($data, $params){
ob_start();
switch ($_GET['page']){
case 'home':
case 'about':
case 'services':
include $_GET['page'].'.php';
}
return
PheryResponse::factory()
->render_view(ob_get_clean());
}
))->process();
?>Takes just one parameter, $last_call, in case you want to call process() again later, with a different set. last_call won't allow the process to return until you call it again or exit the code inside a callback function.
<?php
$phery = Phery::instance();
$phery->set(array('function' => array('class', 'funct')));
$phery->process(false);
// ...
// continue execution
$phery->set(array(
'function2' => array('class' => 'funct2')
))
->callback(array(
'post' => 'function'
))
->process();
// PHP 'exit' is called, from this point and beyond won't get executed unless it doesnt map to any AJAX calls
$i += 10;
?>Set configuration for the current instance of phery. Passed as an associative array, and can be passed when creating a new instance.
-
exit_allowed=>trueDefaults to true, stop further script execution. Set this to false on frameworks that need to do proper cleanup and/or event triggering -
exceptions=>falseThrow exceptions on errors -
set_always_available=>falseBy default, the function Phery::instance()->set() will only register functions when the current request is an AJAX call, to save resources. In order to use Phery::instance()->get_function() anytime, you need to set this config value to true -
error_reporting=>false|E_ALL|E_DEPRECATED|...Error reporting temporarily using error_reporting(). 'false' disables the error_reporting and wont try to catch any error. Anything else than false will throw a PheryResponse->exception() with the message, code, line and file -
csrf=>falseEnable CSRF protection, uses PHP sessions. The meta tag MUST be inside the head of your page using<?php echo Phery::instance()->csrf(); ?> -
return=>falseSetting this to true will makePhery::instance()->process()method return the answer (and won't exit the code, overridesexit_allowed), so you may do your cleanups and set the answer where you may please
Singleton static method, ensures just one instance of phery.js, this is prefered over creating multiple instances
Register the functions that will be triggered by AJAX calls. The key is the function alias, the value is the function itself.
<?php
function outside($ajax_data, $callback_data){
return PheryResponse::factory();
}
class classy {
function inside($ajax_data, $callback_data){
return PheryResponse::factory();
}
static function inside_static($ajax_data, $callback_data){
return PheryResponse::factory();
}
}
$class = new classy();
Phery::instance()->set(array(
'alias' => function(){
return PheryResponse::factory();
},
'outside' => 'outside',
'class' => array($class, 'inside'),
'class' => 'classy::inside_static',
'namespaced' => 'namespaced\function'
));
?>Callback/response function comprises of:
<?php
function func($ajax_data, $callback_data, $phery_instance){
// $ajax_data = data coming from browser, via AJAX
//
// $callback_data = can have anything you specify, plus additional information, like **submit_id** that
// comes automatically from the AJAX request, containing the ID of the calling DOM element, if has an id="" set
//
// $phery_instance = the current instance of Phery
//
return PheryResponse::factory(); // In most cases, you'll want to return a PheryResponse object
}
?>Unset any previously function set with Phery::instance()->set()
Create a new token inside PHP session to prevent CSRF attacks, and return as a <meta> tag.
Need to enable CSRF setting with config()
<head>
<?php echo Phery::instance()->csrf(); ?>
</head>Creates a new instance of phery.js, that is chainable
<?php
Phery::factory(array('exceptions' => true))
->set(array('alias' => 'func'))
->process();
?>Phery::link_to($title, $function, array $attributes = array(), Phery $phery = null, $no_close = false)
Helper static method to create any element with AJAX enabled. Check sources, phpDocs or an IDE code hinting
for a better scoop and detailed info http://phery-php-ajax.net/docs/class-Phery.html#_link_to
When creating this element, if you use data-phery-related, you can merge multiple forms in one AJAX call
<?php echo Phery::link_to('link title', 'function_name', array('class' => 'red', 'href' => '/url')); ?>You may create a non-clickable container that hold many elements that may serve as a template.
Using link_to as the following:
<?php echo Phery::link_to('link title', 'function_name', array('class' => 'red', 'href' => '/url'), null, true); ?>
<span class="name"></span>
<button></button>
</div>Helper static method to open a form that will be able to execute AJAX submits.
Check sources, phpDocs or an IDE code hinting for a better scoop and detailed info
http://phery-php-ajax.net/docs/class-Phery.html#_form_for
When creating this element, if you use data-phery-related, you can merge multiple forms in one AJAX call
<?php echo Phery::form_for('/url-to-action/or/empty-means-current-url', 'function_name', array('class' => 'form', 'id' => 'form_id', 'submit' => array('disabled' => true, 'all' => true))) ?>
<input type="text" name="text">
<input type="password" name="pass">
<input type="submit" value="Send">
</form>Helper static method to display a select element that make AJAX calls on change.
http://phery-php-ajax.net/docs/class-Phery.html#_select_for
When creating this element, if you use data-phery-related, you can merge multiple forms in one AJAX call
<?php echo Phery::select_for('function_name', array(1 => 'true', 2 => 'hello', 3 => 'control'), array('selected' => 2)) ?>Helper static method that returns the first non null/false/0 item (taken from MYSQL COALESCE). Notice that depending on error reporting, some notices will be THROWN, to make sure use @ in front of the variable
<?php echo Phery::coalesce($undeclared_variable, UNDECLARED_CONSTANT, $data['no-index'], 10) // return 10 ?>Check the code completion using an IDE for a better view of the functions, read the source or check the examples
Any jQuery function can be called through PheryResponse, even custom ones, defined through $.fn.extend or $.function
Since version 2.0, you may nest PheryResponses, and the this property was added, to access the calling element (or form)
directly from PHP
http://phery-php-ajax.net/docs/class-PheryResponse.html
<?php
function func($data, $params, $phery)
{
$user = ORM::factory('user', $data['id'])
->values($data)
->update();
return
PheryResponse::factory('#name')
/* Set the HTML of the #name */
->html('<p>'.$user->name.'</p>')
->show('fast')
/* Call a jQuery plugin, same as $('.slider').slider(...) */
->jquery('.slider')
->slider(array(
'value' => 60,
'orientation' => "horizontal",
'range' => "min",
'animate' => true
))
/* Creating elements on-the-fly, same $('<p/>') */
->jquery('<p/>', array('class' => 'attention', 'text' => 'Attention!'))
->appendTo('header .messages')
/* Nesting responses */
->add(PheryResponse::factory('p')->effect('highlight'))
/* Apply to both p that was created and existing p's on the page */
->addClass('changed');
}
?>A few special attributes:
- Responses can be serialized and saved on the database without any special effort
- You may pass functions and nest many responses, either as setters or getters (check the
demo.phpfile) - The method chaining nature of the response make it easy to return, in any order, everything you need
- You can execute next-in-chain methods conditionally using
unlessandincase(act asif notandif) ->this->refer to the calling DOM element, like doing$(this).->window->translates to$(window).->document->translate to$(document).->jquery->translate to$.->anyobj->makes you able to access ANY global object and call methods on it. For example$r->my_obj->execute('param1');will do awindow.my_obj.execute('param1');. It's a shortcut to thePheryResponse->access()methodPheryResponse->callandPheryResponse->applysets the context (this) of the called function to the passed object, for examplePheryResponse->call(array('obj', 'method')), thethisinside method isobj
This class allows you to pass a string that will be made into an anonymous function, useful for jQuery functions that needs a callback. You may bind parameters and variables that will be replaced inside the function, like:
PheryFunction::factory('function(){ alert(":msg"); }')->bind(':msg', $msg);Another example:
<?php
function remote()
{
return
PheryResponse::factory()
->this
->animate(
array('opacity' => 0.3),
1500,
PheryFunction::factory('function(){ alert("done animating!"); }')
);
}
Phery::instance()->set(array(
'remote' => 'remote'
))->process();PheryException - Exceptions that are thrown by phery, when enabled to do so, with some descriptive errors
Check the code completion using an IDE for a better view of the functions, read the source or check the examples http://phery-php-ajax.net/demo.php
There are three jQuery helper selectors: :phery-remote, that return elements if they have phery remote functions attached,
:phery-confirm if the element got any confirmation before click/submit
and :phery-view, to determine if the calling element belongs to the view
You may check elements that have phery.js enabled using
$('.widget:eq(0)').is(':phery-remote');or selecting all the elements for a class
$('.widget:phery-remote:visible').phery('remote'); // call their remote functionsOr combine them in the remotes function, to execute them in order
// call their remote functions in order
phery.remotes($('.widget:phery-remote:visible')).done(function(){
// do your thing
});Generate an object serialized with unlimited depth from forms. Opts can be defined as:
disabled: boolean, process disabled form elements, defaults to falseall: boolean, include all elements from a form, including null ones, assigning an integer to the item, defaults to falseempty: boolean, setting to false will skip empty fields (won't be submitted), setting to true will submit empty key:values pairs, including non checked radio and checkboxes, this overrides "all" setting, defaults to truefiles_apart: boolean, Return an object comprising of{'files': {}, 'inputs': {}}, so form inputs doesn't get mixed with file inputs
This function can also be called directly on select, input (all types) and textarea DOM elements, and the transformations will happen automatically
$('form').serializeForm({'disabled':true,'all':true,'empty':false});- A form like:
<form>
<input name="field[gender]" type="text" value="male">
<input name="field[name]" type="text" value="John Doe">
<input name="field[info][date]" type="date" value="12/12/1983">
<input name="breakfast" type="text" value="eggs & bacon">
<select name="select" multiple>
<option selected value="1">1</option>
<option selected value="2">2</option>
<option value="3">3</option>
</select>
<input type="file" name="file">
</form>- will generate an object like:
{
"field":{
"gender":"male",
"name":"John Doe",
"info": {
"date":"12/12/1983"
}
},
"breakfast":"eggs & bacon",
"select":[
1, 2
],
"file": [object File]
}- if the
files_apartis set to true :
{
"inputs": {
"field":{
"gender":"male",
"name":"John Doe",
"info": {
"date":"12/12/1983"
}
},
"breakfast":"eggs & bacon",
"select":[
1, 2
]
},
"files": {
"file": [object File]
}
}An helper function that has been long missing from jQuery, to simply reset a form and remove all values from it. Can reset multiple forms at once
Returns functions associated with phery.js and the element, they extend the $.fn part of jQuery
Trigger the AJAX call, can pass an additional object. Executes the phery.js data associated with the element. Returns the jQuery AJAX object. The data that is passed to the function will overwrite the variables in the object if the have the same name.
$(el).phery().remote();
// or $(el).phery('remote');An element created with
<?php echo Phery::link_to('Click me', 'function', array('args' => ('id' => 1, 'append' => true)); ?>When calling e.g: $('a').phery('remote', {'append': false});, the append setting will be rewritten, so be careful
when passing temporary arguments to the phery('remote') function. All arguments passed using this function
are temporary, they don't get stored in the element, even if the value already exists in the element.
If this function is called without any arguments, will return all phery data associated with the current element.
$(el).phery('data');Trigger the exception handler on the element. Returns the current jQuery elements.
$(el).phery().exception('Exception!', {'data': true});
// or $(el).phery('exception', 'Exception!', {'data': true});Append arguments to the current element. The initial value will decide how the parameters will behave in the future.
These changes are not temporary, they last as long the DOM element is on the page
This function return the phery() of the element, so you may chain remote()
// If the element had {'undo':1}, after the call, it will have {'undo': 1, 'data': true}
$(el).phery().append_args({'data': true}).remote();
// or $(el).phery('append_args', {'data': true});Set arguments to the current element. Overwrites any data previously set.
It cannot use single values, any string, number, etc will become a [value]
It's better to always pass preferably an object, or at least an array.
These changes are not temporary, they last as long the DOM element is on the page
This function return the phery() of the element, so you may chain remote()
$(el).phery().set_args({'data': true}).remote();
// or $(el).phery('set_args', {'data': true});Get data arguments of the current element.
console.log($(el).phery().get_args());
// or console.log($(el).phery('get_args'));Add phery.js to the selected element, set the AJAX function name and you may pass arguments. Returns the current jQuery elements.
$('a.ajaxify-me').phery().make('test', {'loaded':true});
// or $(el).phery('make', 'test', {'loaded': true});It will make the a call test with arguments {loaded: true}
Clean up the element, and remove it from the DOM. It removes all data before so it won't memory leak on IE
$(el).phery().remove();
// or $(el).phery('remove');Returns boolean if there's already an AJAX call going on. You may prevent double form submissions for example checking if element is in progress, returning false if there's already another in progress
$('form').on('phery:before', function(){
var $this = $(this);
if ($this.phery('inprogress')){
return false; // will cancel the new action
}
});You may disabled it automatically per element, when creating the element with Phery::link_to or Phery::form_for
passing array(only => true) or you may set it programatically using el.phery('data', 'only', true);
Notice that animations and asynchronous functions won't count as "in progress".
Subscribe to a topic and receive data from the server (or other part of the client code through publish)
Internally, it uses jQuery.Callbacks, so they will fire in order they were added.
var fn = {
'login': function(login, message){
// true / 'message'
}
};
$(el).phery('subscribe', fn);
// remove it
$(el).phery('subscribe', fn, true);if you set the remove argument to true, the callback will be removed
Publish a message on the topic with arguments (that are optional). The args passed must be an array (think jQuery trigger)
$('#login').phery('publish', 'login', [true, 'message']);Executes the phery.remote on only one element from the jQuery element stack and returns a promise (like phery.remote does)
$(el).phery('one', {id: 1}).then(
function(){
alert('success!');
},
$(el2).phery().one
); //executes the phery.remote on el2 only if the ajax on el failsRemove phery.js AJAX functions on the select elements. Setting the unbind parameter to true will also unbind the phery.js events that were previously set Returns the current jQuery elements.
$(el).phery().unmake();
$(el).phery('unmake');Create a subscription without attaching to any DOM elements. Takes almost the same parameters as phery.remote
var triggery = phery.subscribe('reset', {
'subscription1': function(){
// do your stuff
},
'subscription2': function(data){
// json data ;)
}
}, {id: 1}, {target: '/ajax/'});
phery.timer(triggery, 100); // poll every 100 milisecondsMake an ajax call automatically every miliseconds. It uses setTimeout instead of setInterval, returns two functions
to start or stop the timer. You can't pass a phery.remote() call directly to this function, it need to be either
a DOM element or in form of an array that you would pass in phery.remotes
var call1 = phery.remote('remote1', null, null, false);
var call2 = phery.remote('remote2', null, null, false);
var timer = phery.timer(call1);
var timer2 = phery.timer(call2, 1000);
timer2.stop();
timer.start(1000);
phery.timer([
['remote1'],
['remote2']
], 1000);Broadcast a topic to all elements that has this topic subscribed. The args must be passed as an array.
phery.broadcast('reset', ['param1','param2']);Call a series of AJAX calls in order, waiting for the last call to finish.
Returns a promise for all the queued calls, so you can watch it with progress, and use then (or a chain of then).
Calls will be made in sequence regardless if they were successiful or not
An array of array of arguments, the same you'd call phery.remote with.
phery.remotes([
['function',{args:1}], //same as phery.remote('function', {args: 1});
['function2'], // same as phery.remote('function2');
['function3', null, {target:'/target'}] // same as phery.remote('function3', null, {target: '/target'});
]);You may also pass a jQuery set of phery.js-ready elements
phery.remotes($('.containers:not(.loaded)'));This isn't the same as doing $('.containers:not(.loaded)').phery('remote'), because in that case
elements will be called at once, asynchronously, with no progress or any feedback.
Also you may observe the progress of the functions using the progress as part of the promise:
phery.remotes($('.containers:not(.loaded)')).progress(function(jqxhr){
//'this' is the current element or item in the array
//'jqxhr' is the current AJAX jqXHR object from jQuery.
// you may watch the progress of each jqxhr in case of multiple uploads
});Calls an AJAX function, pass some args if needed (pass null for no arguments) and the callback, containing a function(data){}
Usage:
phery.json('remotefunc', {id: 4, first: true}, function(data){
console.log(data);
});It's a shorthand for the following code:
var el = phery.remote(remote, null, {'temp':true}, false);
el.on('phery:json', function(event, data){
return cb(data);
});
if (args !== undefined && args !== null) {
el.phery('remote', args);
} else {
el.phery('remote');
}Shorthand for phery.remote('function', null, attrs, false) to create reusable AJAX elements with their own element that isn't bound to the DOM (but may eventually be appended to the DOM)
function_name: string, name of the alias defined inPhery::instance()->set()inside PHPattr: object, set any additional information about the DOM element, usually for setting another href to it. eg:{href: '/some/other/url?p=1'}
var element = phery.element('function');
element.phery('remote', {id: 1});
element.on('phery:json', function(data){
console.log(data);
});
element.subscribe('hello', function(){
alert('Hello');
});Calls an AJAX function directly, without binding to any existing elements, the DOM element is created and removed on-the-fly
If directCall is false, it will return a jQuery a element, if not, it will return an jqXHR object
function_name: string, name of the alias defined inPhery::instance()->set()inside PHPargs: object or array or variable, the best practice is to pass an object, since it can be easily accessed later through PHP, but any kind of parameter can be passed, from strings, ints, floats, and can also be null (won't be passed through ajax)attr: object, set any additional information about the DOM element, usually for setting another href to it. eg:{href: '/some/other/url?p=1'}direct_call: boolean, defaults to true, setting this to false, will return the created DOM element (invisible to the user) and can have events bound to it, but will be removed right after the response is processed
phery
.remote('remote', {'key':'value'}, {'href': '/new/url'}, false)
.on({
'phery:done': function(){
$('body').append($(this));
}
})
.phery('remote');When setting direct_call to false, the returned element can be reused many times, using phery('remote'), to explicitly remove it, you need
to call phery('remove')
If you wish to remove it as soon as the call ends, pass in the attr parameter, the temp option:
phery.remote('remote', {'id': 1}, {'temp': true}, false).phery('remote');If direct_call is undefined or true (the default) the element is removed and cleaned after each remote call.
Global events will always trigger, and they first come empty and do nothing.
It's mainly useful to show/hide loading screens, update statuses, put an overlay over the page, or interact with other libraries.
Not to confuse with the document event bubble of these events.
Please notice that when setting views, phery remote elements inside a view that doesn't do navigate_to calls, will have
side effects for events that propagated from the children elements, so when you set an event, like beforeSend on your view
if you execute any other phery event that isn't the selector for your in-view link, the beforeSend of the child element
will propagate to the view container, and will trigger it's event.
These events are triggered globally, independently if called from an existing DOM element or through phery.remote()
The event.target points to the related DOM node (that was clicked, or the form that was submitted), if any.
When calling phery.remote, the event.target will be the detached DOM element that were created on-the-fly
to make the AJAX call, and isn't appended to the page.
You may check if the element is temporary using if (event.$target.phery('data', 'temp')){ /* is temp */ }
Also, phery provides a shortcut to the event jQuery element through event.$target, that is the same as doing $(event.target),
but it's ready to use.
before:function (event)Triggered before everything, happens right afterphery.remote()call. Issuing anevent.stopImmediatePropagation()after returning false inside thebeforecallback, will make it so thealwaysevent won't trigger.after:function (event)Triggered after all the data was parsed.beforeSend:function (event, xhr)Triggered before sending the data through AJAX, Useful to add any CSRF protections heredone:function (event, data, text, xhr)Triggered just before the answer from the response was received successfully and will start to process the data. Returning false halts the processing, make sure to return truealways:function (event, xhr)Triggered after the data was processed. and is triggered if there was no error.fail:function (event, xhr, status, error)When an error happens when requesting to the provided URL. It won't be triggered if the PHP code fails to executeexception:function (event, exception)Will be called if any problem happens while processing data, or executing jquery callsjson:function (event, obj)Returns the json object sent from PHPprogress:function (event, progress)File upload progress (not available in <= IE9). Can be accessed through the promiseprogress(callback)tooparams:function (event, params)Pass extra params to the request. Won't overwrite existing params for security reasons
phery.on('before', function(){
$('#loading').fadeIn();
});
phery.on('always', function(){
$('#loading').fadeOut();
});
//or
phery.on({
'before': function(){
$('#loading').fadeIn();
},
'always': function(){
$('#loading').fadeOut();
}
});Remove a global event bound
phery.off('always');Reset the configuration to the defaults, see phery.config()
Wrapper for the console.log(), but keeps a local history, if you enable it in
phery.config()
Config the page to render AJAX partial views
phery.view({
// Any selector, prefered to be a ID
'#container': {
// Optional, function to call before the
// HTML was set, can interact with existing elements on page
// The context of the callback is the container
'beforeHtml': function(data){
$('#menu a').removeClass('selected').filter('.' + data.class).addClass('selected');
},
// Optional, function to call to render the HTML,
// in a custom way. This overwrites the original function,
// so you might set this.html(html) manually.
// The context of the callback is the container
'render': function(html, data){
/* this refers to the container, in this case #container */
html = html.replace(' ass ', ' a** ');
this.html(html);
document.title = data.title;
},
// Optional, function to call after the HTML was set,
// can interact with the new contents of the page
// The context of the callback is the container.
'afterHtml': function(data, passdata){
if (window.history) {
window.history.pushState(data, data.title, data.url);
}
},
// Optional, defaults to a[href]:not(.no-phery,[target],[data-phery-remote],[href*=":"],[rel~="nofollow"]).
// Setting the selector manually will make it 'local' to the #container, like '#container a'
// Links like <a rel="#nameofcontainer">click me!</a>, using the rel attribute will trigger too
'selector': 'a',
// Optional, array containing conditions for links NOT to follow,
// can be string, regex and function (that returns boolean, receives the url clicked, return true to exclude)
'exclude': ['/contact', /\d$/, function]
// any other phery event, like beforeSend, params, etc
}
});Retrieve the data and functions associated with the container with:
// return the instance of PheryView associated with the container
phery.view('#container')
// contains the data associated with the container, like every configuration (this is a clone of original data from 'view.phery')
phery.view('#container').data;
// Call the path to render a URL in the container
phery.view('#container').navigate_to('url/to/somewhere');
// Contains the container $(DOM) itself, got all the jquery functions on it
phery.view('#container').container;
// Check if the url is excluded, per config, returns true if excluded
phery.view('#container').is_excluded_url('url/path');Example:
/* Setup automatic view rendering using ajax */
phery.view({
'#container':{
/* We want only the links inside the container to be ajaxified */
'selector':'a',
/* Enable the browser history, and change the title */
'afterHtml': function(data, passdata){
document.title = data.title;
if (window.history) {
/* Good browsers get history API */
if (typeof passdata['popstate'] === 'undefined'){
window.history.pushState(data, data.title, data.url);
}
}
},
/* phery:params let us add params, that ends in callback params and wont get mixed with arguments */
'params':function (event, data) {
// from which location we are getting the call, PHP knows nothing about it
data['origin'] = window.location.href;
}
}
});
/* Good browsers get back/forward button ajax navigation ;) */
window.onpopstate = function(e){
phery.view('#container').navigate_to(document.location.href, null, {'popstate': true});
};and the PHP side:
<?php
Phery::instance()->views(array(
'#container' => function ($data, $param){
$render = pseudo_controller();
return
PheryResponse::factory()
->render_view($render['html'] . $param['menu'], array('title' => $render['title']));
}
))->process();The current configuration options that are available in phery. Reminding that additional configurations and modifications on the AJAX calls can be done using $.ajaxSetup()
The options can be set using the key:value in the key parameter, or using a string and value. Each option can be accessed using dot notation inside the string
phery.config({
'cursor': false,
'enable.per_element.events': false
});
phery.config('debug.display.config', true);Locks the configuration, so that nobody can change the configuration again using phery.config()
Works as an extra safety measure against people messing with your project settings
phery.config({
'cursor': false,
'enable.per_element.events': false
}).lock_config();cursor(true / false, defaults to true): Change the cursor to wait/busy on any ajax calldefault_href(string / false, defaults to false): Set a common url to all calls, being able to override this to anyhrefproperty attached to the elementajax.retries(int, defaults to 0): Number of retries on error before returning the error callbackenable.log(true / false, defaults to false): Enable displaying of exceptions or errors, for debugging purposesenable.autolock(true / false, defaults to false): Locks the config for the instance after the window has completly loaded, making it impossible to make changes to it, as an extra safety measure against tampering, and works the same way as callingphery.lock_config()but on$(window).on('load').enable.log_history(true / false, defaults to false): Keep the log of errors that can be accessed throughphery.log()enable.only(true / false, defaults to false): Make all AJAX calls, per element, be called one at a time. Multiple clicks or form submissions won't make new AJAX until the last one is done. This option can be set using$(el).phery('data', 'only', true);or creating the element using<?php Phery::link_to('Clicky', 'function', array('only' => true)); ?>ordata-phery-only="1"enable.php_string_callbacks(true / false, defaults to false): jQuery functions likeanimateoreachthat take callbacks, can have the callback defined as a string inside PHP if this is enabled. You may also create a function that will have the current calling element as context (thethiskeyword)enable.per_element.events(true / false, defaults to true): Enablephery:*events on each elementenable.clickable_structure(true / false, defaults to false): Enable clicking on HTML structural elements, like DIV, HTML, etc. They are disabled by default, but can be enabled manually and locally per element usingdata-phery-clickable="1"to the tag, or using$('div').phery('data', 'clickable', 1)
inline.enable(true / false, defaults to false): Enables phery.js to load responses inline, usingphery.load('<?=PheryResponse::factory()->render(); ?>');or ready-to-use string<?php PheryResponse::factory()->inline_load(true); ?>will generate thephery.loadstring automatically.inline.once(true / false, defaults to false): Make it so it can only be loaded once on page load, and won't be able to call it again later, for security reasons.
debug.enable(true / false, defaults to false): enable verbose to keep track of each step defined below. Don't enable it in production since it's really verboselydebug.display.events(true / false, defaults to true): display events debugdebug.display.remote(true / false, defaults to true): display remote callsdebug.display.config(true / false, defaults to true): display config changes
If you specify a string, it will be appended phery.config('delegate.confirm', 'focusin') becomes ['click','focusin'], passing a array, it wil be rewritten
phery.config('delegate.confirm', ['focusin']) becomes ['focusin']
delegate.confirm(selector =>[data-phery-confirm]:not(form)) (string, defaults to ['click']): Confirm alertdelegate.form(selector =>form[data-pheryremote]) (string, defaults to ['submit']): Form submissiondelegate.select_multiple(selector =>select[data-phery-remote][multiple]) (string, defaults to ['blur']): Event onselect multipleelementdelegate.select(selector =>select[data-phery-remote]:not([multiple])) (string, defaults to ['change']): Event onselectelementdelegate.tags(selector =>[data-remote]:not(form,select)) (string, defaults to ['click']): Clicks on elements, likeA
Per element events are the same from global events. Refer to phery.on above for description for each event.
They can be disabled using phery.config('enable.per_element.events', false); since they are enabled by default
These events will bubble to the document DOM, so you may catch them using, for example:
$(document).on('phery:json', 'a.special', function(e, json){
// e.target is the current 'a' DOM node, and e.$target is the current $(node)
// this will only trigger for "a" DOM elements that have the .special class
});
// this can be done using phery.on as well
phery.on({
'json': function(e, json){
if (e.$target.is('a.special')) {
}
}
});phery:before:function (event)phery:beforeSend:function (event, xhr)phery:done:function (event, data, text, xhr)phery:always:function (event, xhr)phery:fail:function (event, xhr, status, error)phery:after:function (event)phery:exception:function (event, exception)phery:json:function (event, obj)phery:params:function (event, obj)
$('form').bind({
// Enable them again
'phery:always': function(){
$(this).find('input').removeAttr('disabled');
},
// Disable form elements
'phery:before': function(){
$(this).find('input').attr('disabled', 'disabled');
}
});Released under the MIT license