Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Browse files

Adding doc

  • Loading branch information...
commit 85f131d58db8272e5864608f922814694106503e 1 parent 965c2d8
Philippe Gaultier authored
Showing with 356 additions and 31 deletions.
  1. +260 −0 doc/javascript.txt
  2. +96 −31 doc/sweekit.txt
View
260 doc/javascript.txt
@@ -0,0 +1,260 @@
+## Javascript functions
+
+Package dependancies are automatically resolved.
+
+### sweelix
+
+Core package, this package define the base namespace jQuery.sweelix and
+a basic module system.
+
+No usefull function is exported
+
+### debug - depends on sweelix
+
+Debugging package for js. This is a simple console wrapper. Once module
+is inited, following methods are added to the jQuery.sweelix object :
+
+log, debug, info, warn, error, assert, dir, trace, count, group, groupEnd
+
+ // .. js code
+ jQuery.sweelix.log('Loging info in the console');
+ // .. js code
+
+If the debug is activated, the console will display the string "Loging info in the console".
+If debug is deactivated, the console will remain empty
+
+In order to be able to use the debug module you have to add SwClientScriptBehavior
+and configure it
+
+1. Configure application to enable debugging
+
+ // App config code
+ 'clientScript' => array(
+ 'behaviors' => array(
+ 'sweelixClientScript' => array(
+ 'class' => 'ext.sweekit.behaviors.SwClientScriptBehavior',
+ 'config' => array(
+ 'debug' => array(
+ 'debug' => true, // default false - (de)activate debug
+ 'method' => 'log', // default 'log' - default console method used when logging
+ 'fallback' => false, // default false - if console is not available use alerts
+ ),
+ )
+ ),
+ ),
+ ),
+
+2. Use debugging functions in the code
+
+ // View code
+ // register debug module
+ <?php Yii::app()->clientScript->registerSweelixScript('debug'); ?>
+ // perform some debugging
+ <script type="text/javascript">
+ jQuery(document).ready(function(){
+ jQuery.sweelix.log('Document is ready, starting js');
+ // ... js code
+ });
+ </script>
+
+### callback - depends on debug and sweelix
+
+Callback system. This system allow the developer to register and raise
+events
+
+In order to be able to use the debug module you have to add SwClientScriptBehavior
+and configure it
+
+1. Configure application to enable debugging and callback
+
+ // App config code
+ 'clientScript' => array(
+ 'behaviors' => array(
+ 'sweelixClientScript' => array(
+ 'class' => 'ext.sweekit.behaviors.SwClientScriptBehavior',
+ 'config' => array(
+ 'debug' => array(
+ 'debug' => true, // default false - (de)activate debug
+ 'method' => 'log', // default 'log' - default console method used when logging
+ 'fallback' => false, // default false - if console is not available use alerts
+ ),
+ 'callback' => array(
+ 'globalCblName' => 'swlx', // default 'swlx' - default namespace of registered events
+ 'top' => true, // default true - if true, event are always re-routed to top window
+ ),
+ )
+ ),
+ ),
+ ),
+
+2. Use callback functions in the code
+
+ // View code
+ // register callback module
+ <?php Yii::app()->clientScript->registerSweelixScript('callback'); ?>
+ // perform some regisration
+ <script type="text/javascript">
+ jQuery(document).ready(function(){
+ jQuery.sweelix.register('myRegisteredEvent', function(params){ alert('my event was raised with myParam value : '+params.myParam); });
+ // ... js code
+ });
+ </script>
+ // ...
+ <a href="#" onclick="jQuery.sweelix.raise('myRegisteredEvent', {'myParam':2})">Raise the event</a>
+
+
+### ajax - depends on callback, debug and sweelix
+
+Ajax system allow the developper to perform easy ajax requests
+
+1. Configure application to enable debugging, callback and ajax
+
+ // App config code
+ 'clientScript' => array(
+ 'behaviors' => array(
+ 'sweelixClientScript' => array(
+ 'class' => 'ext.sweekit.behaviors.SwClientScriptBehavior',
+ 'config' => array(
+ 'debug' => array(
+ 'debug' => true, // default false - (de)activate debug
+ 'method' => 'log', // default 'log' - default console method used when logging
+ 'fallback' => false, // default false - if console is not available use alerts
+ ),
+ 'callback' => array(
+ 'globalCblName' => 'swlx', // default 'swlx' - default namespace of registered events
+ 'top' => true, // default true - if true, event are always re-routed to top window
+ ),
+ // ajax module has no configuration vars
+ )
+ ),
+ ),
+ ),
+ //...
+
+2. Use ajax functions in the code (view)
+
+ // View code
+ /**
+ * "Pure" js code
+ */
+ // register ajax module
+ <?php Yii::app()->clientScript->registerSweelixScript('ajax'); ?>
+ // perform some regisration
+ <script type="text/javascript">
+ var parameters ={
+ 'targetUrl' : 'http://www.myurl.com?r=site/cool',
+ 'data' : {}, // data to post
+ 'mode' : '', // can be replace or empty
+ 'targetSelector' : '#myDiv'
+ };
+ </script>
+ // ...
+ <a href="#" onclick="jQuery.sweelix.raise('ajaxRefreshHandler', parameters)">Raise the event</a>
+ // ...
+ <div id="#myDiv">
+ This div should be updated
+ </div>
+
+ /**
+ * Sweeml code
+ */
+ <?php echo CHtml::link('Raise the event','#', array(
+ 'onclick'=> Sweeml::raiseAjaxRefresh('#myDiv', array('site/cool')),
+ )); ?>
+ // ...
+ <div id="#myDiv">
+ This div should be updated
+ </div>
+
+
+3. Respond to call in controller
+
+ // Controller code
+ public function actionCool() {
+ // ... controller code
+ if(Yii::app()->getRequest()->getIsAjaxRequest() === true) {
+ // render partial html
+ $this->renderPartial('_htmlPartialView');
+ } else {
+ // render full html
+ $this->render('htmlFullView');
+ }
+ }
+
+### shadowbox - depends on callback, debug and sweelix
+
+Shadowbox system allow easy lightbox management
+
+1. Configure application to enable debugging, and callback
+
+ // App config code
+ 'clientScript' => array(
+ 'behaviors' => array(
+ 'sweelixClientScript' => array(
+ 'class' => 'ext.sweekit.behaviors.SwClientScriptBehavior',
+ 'config' => array(
+ 'debug' => array(
+ 'debug' => true, // default false - (de)activate debug
+ 'method' => 'log', // default 'log' - default console method used when logging
+ 'fallback' => false, // default false - if console is not available use alerts
+ ),
+ 'callback' => array(
+ 'globalCblName' => 'swlx', // default 'swlx' - default namespace of registered events
+ 'top' => true, // default true - if true, event are always re-routed to top window
+ ),
+ )
+ ),
+ ),
+ ),
+ //...
+
+2. Use shadowbox functions in the code (view)
+
+ // View code
+ /**
+ * "Pure" js code
+ */
+ // register ajax module
+ <?php Yii::app()->clientScript->registerSweelixScript('shadowbox'); ?>
+ // perform some regisration
+ <script type="text/javascript">
+ var parameters ={
+ content: 'http://www.example.com/?r=site/lb',
+ player: "iframe",
+ title: "Lightbox",
+ height: 350,
+ width: 350
+ };
+ </script>
+ // ...
+ <a href="javascript:void(0);" onclick="jQuery.sweelix.raise('shadowboxOpen', parameters)">Open the shadowbox</a>
+ // ...
+ <a href="javascript:void(0);" onclick="jQuery.sweelix.raise('shadowboxClose')">Close shadowbox</a>
+
+ /**
+ * Sweeml code
+ */
+ <?php echo CHtml::link('Open the shadowbox','#', array(
+ 'onclick'=> Sweeml::raiseOpenShadowbox(array('site/lb'), array(
+ 'title' => 'Lightbox',
+ 'height' => 350,
+ 'width' => 350,
+ )),
+ )); ?>
+ <?php echo CHtml::link('Close shadowbox','#', array(
+ 'onclick'=> Sweeml::raiseCloseShadowbox(),
+ )); ?>
+
+ // ...
+ // or using js in url
+ <?php echo CHtml::link('Open the shadowbox',
+ Sweeml::raiseOpenShadowboxUrl(array('site/lb'), array(
+ 'title' => 'Lightbox',
+ 'height' => 350,
+ 'width' => 350,
+ ))
+ ); ?>
+ <?php echo CHtml::link('Close shadowbox',Sweeml::raiseCloseShadowboxUrl()); ?>
+
+
+
View
127 doc/sweekit.txt
@@ -3,6 +3,43 @@
This toolkit was written to ease javascript access during our developments.
In order to not create conflict, Sweekit classes are prefixed with _Sw_
+## Samples - because it's always easier to understand what can be done
+
+### Callback system
+
+As an example, you have created an online shop and in several places, the cart is updated.
+If in the header there is a widget which shows the number of products, this widget
+should be updated when the cart is updated.
+
+Using the callback system you can :
+
+Register an event in the widget using Sweeml
+
+ <?php Sweeml::registerEvent('updateCart', "function(data){jQuery('#cart.nb').html(data+' products');}"); ?>
+ <div id="cart">0 product</div>
+
+Whereever the cart is updated you can raise an event.
+
+ <script type="text/javascript">
+ function refreshCart() {
+ // perform ajax call to refresh info
+ jQuery.ajax({
+ url : 'http://targeturl',
+ success : function(nbOfProducts) {
+ // nbOfProducts is an integer with the number of products in cart
+ <?php echo Sweeml::raiseEvent('updateCart', nbOfProducts); ?>
+ }
+ });
+ }
+ </script>
+ <a href="#" onclick="refreshCart()">refresh cart</a>
+
+### All in one
+
+
+
+
+
## Sweeml
Sweeml override the original CHtml helpers and add several functionnalities
@@ -40,10 +77,20 @@ Parameters
* $action (string) action to execute when event is raised, this is pure javascript code
* $context (string) context if needed, else will be in registered in global context
-#### Ajax oriented method
+### Ajax helpers
+
+#### Ajax request using callback system
Produce an ajax call to $url and perform the update/replace
-of the target
+of the target element if content-type is text/html. If the content-type is application/javascript
+the returned js code is executed.
+
+This system raise also two jQuery events on the target :
+
+* beforeAjax : raised just before ajax is submited.
+* afterAjax : raised after ajax request (and replace/update) if the call was successfull
+
+This is usefull to prepare data or rebind events when the dom has been replaced.
This method produce a javascript string
````(string) raiseAjaxRefresh($target, $url, $data=null, $mode=null);````
@@ -57,6 +104,38 @@ Parameters
* $data (mixed) data to pass
* $mode (enum) replacement mode can be replace or update
+#### Ajax forms using callback system
+
+This script intercept form posting, perform the post in ajax and update/replace or execute
+the javavscript depending on the content-type
+
+This method produce a javascript script which should be executed to enable form ajaxify
+````(string) ajaxSubmitHandlerScript($target);````
+This method produce a javascript which is automatically registered and ajaxify the form(s)
+````ajaxSubmitHandler($target);````
+
+Parameters
+
+* $target (string) the target element - form(s) to ajaxify
+
+An easier way to ajaxify the forms using this system is to use the all
+in one tag generator.
+
+replace the classic
+````(string) beginForm($action='',$method='post',$htmlOptions=array());````
+with
+````(string) beginAjaxForm($action='',$method='post',$htmlOptions=array());````
+
+And the form will be automagically ajaxified
+
+Parameters
+
+* $action (mixed) action
+* $method (string) method
+* $htmlOptions (array) html options
+
+### Javascript helper
+
#### Redirect system
Usefull when we need to redirect the main window from an iframe. We don't need
@@ -72,35 +151,6 @@ Parameters
* $url (mixed) url in Yii format
* $timer (integer) delay in second before executing redirect
-#### Sample
-
-As an example, you have created an online shop and in several places, the cart is updated.
-If in the header there is a widget which shows the number of products, this widget
-should be updated when the cart is updated.
-
-Using the callback system you can :
-
-Register an event in the widget using Sweeml
-
- <?php Sweeml::registerEvent('updateCart', "function(data){jQuery('#cart.nb').html(data+' products');}"); ?>
- <div id="cart">0 product</div>
-
-Whereever the cart is updated you can raise an event.
-
- <script type="text/javascript">
- function refreshCart() {
- // perform ajax call to refresh info
- jQuery.ajax({
- url : 'http://targeturl',
- success : function(nbOfProducts) {
- // nbOfProducts is an integer with the number of products in cart
- <?php echo Sweeml::raiseEvent('updateCart', nbOfProducts); ?>
- }
- });
- }
- </script>
- <a href="#" onclick="refreshCart()">refresh cart</a>
-
### Shadowbox system - aka easy lightbox system
#### Opening shadowbox
@@ -125,3 +175,18 @@ This method produce a javascript string
````(string) raiseCloseShadowbox();````
This method produce a javascript string which can be used directly as an url
````(string) raiseCloseShadowboxUrl();````
+
+### File upload using plupload
+
+The methods
+
+* ````(string) activeAsyncFileUpload($model, $attribute, $htmlOptions=array()) ;````
+* ````(string) asyncFileUpload($name, $htmlOptions=array(), $value=null);````
+
+This methods should work like the original ones.
+The difference is that they register js, css and everything to allow multi fileuploads with drag'n'drop
+and fancy features. See method doc clock for all options
+
+ <?php echo Sweeml::activeAsyncFileUpload($myModel, 'uploadField', $options); ?>
+
+
Please sign in to comment.
Something went wrong with that request. Please try again.