xi / ajax-bundle
Xi Ajax Bundle for basic ajax functionality with forms and elements. Includes customizable loading animations and error handler stack
Installs: 6 700
Dependents: 2
Suggesters: 0
Security: 0
Stars: 6
Watchers: 3
Forks: 2
Open Issues: 1
Language:JavaScript
Type:symfony-bundle
Requires
- symfony/dependency-injection: >=2.3.0
- symfony/form: >=2.3.0
- symfony/framework-bundle: >=2.3.0
This package is not auto-updated.
Last update: 2024-10-26 12:52:08 UTC
README
This bundle provides basic ajax functionality for your Symfony2 project. You can use it in your forms and any other elements that you wish to bind to send data asyncronously. It also gives use a good indication what's going on by customizable loading indicator and if you have problems in your backend it manages to fail gracefully with notification to user.
Requirements:
Installing
composer.json
"require": { ... "xi/ajax-bundle": "2.3.x-dev" }
AppKernel.php
<?php $bundles = array( ... new Xi\Bundle\AjaxBundle\XiAjaxBundle(), );
base.html.twig -example
Here is an example how you could load your JavaScript files using assets. Because ajax functionalities are in different files you can deside yourself which components you wish to load.
<script src="//ajax.googleapis.com/ajax/libs/jquery/1.7.2/jquery.min.js"></script> {% javascripts filter="?yui_js" output="js/main.js" '@YourOwnBundle/Resources/js/jquery.form.js' '@XiAjaxBundle/Resources/coffee/ajax-abstract-logic.coffee' '@XiAjaxBundle/Resources/coffee/ajax-loader.coffee' '@XiAjaxBundle/Resources/coffee/ajax-form.coffee' '@XiAjaxBundle/Resources/coffee/ajax-element.coffee' '@YourOwnBundle/Resources/coffee/main.coffee' %} <script src="{{ asset_url }}"></script> {% endjavascripts %}
AjaxAbstractLogic
This is the base class for ajax logics. You won't use this directly. You can of course extend this if you want to do your own custom ajax logic.
AjaxForm
The template includes AjaxForm functionality that helps you to make ajax functionality to your forms.
- Install jQuery.form as AjaxForm uses this.
- Make sure that you initialize AjaxForm in your CoffeeScript file:
new App.AjaxForm.Default '.ajax-form'
- The first argument is required. It specifies the forms you would like to ajaxify.
- Make a form with class named after your identifier:
<form class="ajax-form" ... >
- You can make your own instances of AjaxForm. Just extend the abstract base class.
class YourNamespace.AjaxForm.YourName extends App.AjaxForm.Abstract
- Implement backend logic for form submitting.
- You can change the action of the form if submit button has a data-action parameter so you can have several ways to submit the form that have different actions
<?php namespace My\ProjectBundle\Controller; use Xi\Bundle\AjaxBundle\Controller\JsonResponseController; class MyController extends JsonResponseController { public function saveAction() { $form = ... if ($form->bind($this->getRequest())->isValid()) { // Form is valid. Do something. // Redirects automatically to given route. return $this->createJsonSuccessRedirectResponse('my_route_name'); } // Form is invalid. Return form failure JSON response, which // AjaxForm automatically errorizes for you. return $this->createJsonFormFailureResponse($form); } }
App.FormErrorizer.Default
This is the default form errorizer that creates messagebox above or below (configurable) to failed form element. Messages stays in place until you submit that form again unless you manualy define fadeout time in constructor.
AjaxElement
The template also includes AjaxElement functionality that helps you to bind ajax functionality to any element. Of course you would mostlikely use it in anchors.
- Make sure that you initialize AjaxElement in your CoffeeScript file:
new App.AjaxElement.Default '.ajax-link'
- The first argument is required. It specifies the elements you would like to ajaxify.
- Make a form with class named after your identifier:
<a class="ajax-form" href="your action"... >
- You can make your own instances of AjaxElement. Just extend the abstract base class.
class YourNamespace.AjaxElement.YourName extends App.AjaxElement.Abstract
- Implement backend logic for your action.
<?php namespace My\ProjectBundle\Controller; use Xi\Bundle\AjaxBundle\Controller\JsonResponseController; class MyController extends JsonResponseController { public function someAction($someParameter) { if ($someParameter) { // Do something. For example reload the page. return $this->createJsonSuccessReloadResponse(); } else { // Parameter was invalid. return $this->createJsonFailureResponse('Some parameter was false...'); } } }
App.ElementErrorizer.Default
This is the default Element errorizer. It just creates a box with message next to your activated ajax element. Message stays for 2 seconds and then disappears.
Be adviced that you need some styles to for the box to show up:
.errorized-element { position: absolute; z-index: 10000; padding: 5px 10px; background: red; border-radius: 4px; -webkit-border-radius: 4px; -moz-border-radius: 4px; font-size: 14px; } .fatal-error-modal { z-index: 9999; background-color: #000; opacity: .70; top: 0px; position: absolute; display: block; }
Backend logic for ajax functions
Json Success Response
Just tells that everyting went well and our script may remove the loading animation. No real feedback is given user.
<?php $this->createJsonSuccessResponse('your response text')
Json Success Redirect Response
Simple redirect request for javascript. Very usable in your backend save actions.
<?php $this->createJsonSuccessRedirectResponse('your_route_name', array('some_id' => 1))
Json Success Reload Response
Sometimes you just want to reload the page. For example if you are using common functionality in different context you may not want some fixed route to be redirected. Instead simple page reload will do fine.
<?php $this->createJsonSuccessReloadResponse()
Json Failure Response
Something went wrong. But we are trying to recover from it. Message is passed to errorhandlers and its up to them how the error is presented to user.
<?php $this->createJsonFailureResponse('something went wrong...')
Json Form Failure Response
When form is invalid you wish to inform user about it. This function sends form errors to errorhandlers in nice little packet
<?php createJsonFormFailureResponse(Form $form)
Json success with content
To use JSON success with content functionality you must define your own callback in your javascript file.
The following example contains returnCallbackAction
that returns content of some
template file. It also returns javascript callback to be called yourOwnCallback
Example:
<?php public function returnCallbackAction() { return $this->createJsonSuccessWithContent( $this->renderView('YourBundle:SomeName:fileToBeRendered.html.twig'), 'yourOwnCallback' ); }
In javascript side you must extend your own presentation of ajaxform and add
yourOwnCallback
there. In this case yourOwnCallback
content is the template
file you rendered in your controller.
The following example is written in Coffeescript.
class App.AjaxForm.Customized extends App.AjaxForm.Default yourOwnCallback: (content) -> $('#your-container').html(content)
Development & testing
Install required test libraries with
npm install .
Run tests
cd Tests && ./run.sh