From c2e656869af6782d3b02ab81b08ea728da0f05db Mon Sep 17 00:00:00 2001 From: Fabio Bas Date: Tue, 21 Jan 2014 23:14:37 +0100 Subject: Added quickstart doc for query upgrade --- demos/quickstart/protected/controls/TopicList.tpl | 1 + .../pages/GettingStarted/Upgrading32.page | 234 +++++++++++++++++++++ 2 files changed, 235 insertions(+) create mode 100644 demos/quickstart/protected/pages/GettingStarted/Upgrading32.page (limited to 'demos/quickstart/protected') diff --git a/demos/quickstart/protected/controls/TopicList.tpl b/demos/quickstart/protected/controls/TopicList.tpl index a44e56eb..b8563c50 100644 --- a/demos/quickstart/protected/controls/TopicList.tpl +++ b/demos/quickstart/protected/controls/TopicList.tpl @@ -8,6 +8,7 @@
  • Installation
  • New Features
  • Upgrading from v2.x and v1.x
    • +
  • Upgrading from v3.2
  • Web Site Administration Tool
  • Command Line Tool
    • diff --git a/demos/quickstart/protected/pages/GettingStarted/Upgrading32.page b/demos/quickstart/protected/pages/GettingStarted/Upgrading32.page new file mode 100644 index 00000000..e6e2b1cf --- /dev/null +++ b/demos/quickstart/protected/pages/GettingStarted/Upgrading32.page @@ -0,0 +1,234 @@ + + +

    Upgrading from v3.2

    + +
    +

    +Since version 3.3, PRADO uses jQuery as its default javascript framework. +Previously, up to version 3.2, PRADO used Prototype and Scriptaculous as its default javascript framework. +

    +

    +PRADO relies a lot on clientside javascript code to implement its standard controls, to handle clientside validators, and to create a seamless ajax experience using active controls. +All this javascript code, originally developed on Prototype, has been rewritten in order to use jQuery instead. The choice was mainly driven by the lack of development and decline of the Prototype community, while jQuery has become the de-facto standard library for javascript. +

    +

    +While the PRADO javascript code is ready to work with jQuery, legacy javascript code in existing applications can require some porting to make it work properly. +We summarize in the following the most significant changes in v3.3 to help developers upgrade their v3.2 PRADO applications more easily, if needed. +

    +
    + +

    Basic Prototype to jQuery javascript porting

    +

    +The number one rule on writing jQuery javascript code is to read the jQuery documentation. Porting code from Prototype to jQuery needs some effort: here's a basic lookup table to port existing code: +

    + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    Prototype (OLD)jQuery (NEW)
    Get element by id$('element_id')// get the base DOM element +
    $('#element_id').get(0) +
    // get the the extended element +
    $('#element_id').eq(0) +
    Get element by css selector$$('.class')$('.class')
    Apply a function to multiple elements$$('.class').each(Element.remove)$('.class').remove()
    Create or extend a classClass.create(Prado.WebUI.Control, { ... }) +
    Class.extend(Prado.WebUI.Control, { ... }) +     		jQuery.klass(Prado.WebUI.Control, { ... })
    Extend an objectObject.extend(...)jQuery.extend(...)
    Bind an event to a callback event handlerEvent.observe(element, 'click', callback)$(element).on('click', callback)
    Unbind an event from a callback event handlerEvent.stopObserving(element, 'click', callback)$(element).off('click', callback)
    Stop event propagationEvent.stop(event)// stop event bubbling chain +
    event.stopPropagation() +
    // prevent form submit +
    event.preventDefault() +
    Detect keypress eventif(kc == Event.KEY_RETURN || +
    kc == Event.KEY_SPACEBAR || +
    kc == Event.KEY_TAB)    		// use the numeric codes +
    if(kc == 13 || +
    kc == 32 || +
    kc == 9) +
    Execute a function when the page has finished loadingdocument.observe("dom:loaded", function(event) { ... })$( document ).ready(function() { ... })
    Create an animation effect with a "finish" callbacknew Effect.Fade(element, { +
    duration: 400, +
    afterFinish: function() { +
    // Animation complete. +
    });    		$(element).fadeOut( 400, function() { +
    // Animation complete. +
    });
    Declare a function to be used as event handler binding its "this" propertythis.functionName.bindAsEventListener(this)this.functionName.bind(this)
    Css class functions (add, remove, test for css class)addClassName() +
    removeClassName() +
    hasClassName() +     		addClass() +
    removeClass() +
    hasClass() +
    Get event target inside an event handlerEvent.element(event)event.target
    Get event mouse positionEvent.pointerX(event) +
    Event.pointerY(event) +     		event.pageX +
    event.pageY +
    Fire eventsEvent.fireEvent(this.control, "change")$(element).trigger("change")
    Get element sizeelement.getWidth() +
    element.getHeight() +     		element.width +
    element.height +
    Hook on ajax eventsAjax.Responders.register({ +
    "onLoading" : my_function +
    }); +
    Ajax.Responders.register({ +
    "onSuccess" : my_function +
    }); +     		$( document ).ajaxSend(my_function); +
    $( document ).ajaxSuccess(my_function); +
    + +

    PRADO specific code changes

    +

    +PRADO +Porting prado to jQuery some method signatures has changed, or have been adapted: +

    + + + + + + + + + + + + + + + + + + + + + + + + + + +
    Prototype (OLD)jQuery (NEW)
    Implementing the postback handler for a PostBackControl; +
    the function signature has changed (parameters are inverted):    		onPostBack : function(event, options)onPostBack : function(options, event)
    Execute a postbackPrado.PostBack(options, event);// Create a new object +
    new Prado.PostBack(options, event); +
    Test browser software method has been removedPrado.Browser().ie// Test for browser support for specific capabilities instead +
    jQuery.support +
    // or, better, use Modernizr +
    Focus an elementPrado.Element.focus(element)$(element).focus()
    + +

    Specific controls changes

    +

    +Some Prado controls were based on specific extensions of the Prototype + Scriptaculous javascript framework, and they have been deprecated now that jQuery has become the primary js framework in PRADO. +PRADO 3.3 introduces jQuery-based counterpart for these controls and encourage everyone to port their code to the new controls, but the old controls are still supposed to work with some minor annoyance: +

    +Following is the list of deprecated controls: +

    + +

    TAutoComplete

    +

    +TAutoComplete is deprecated, use TJuiAutoComplete instead. Main changes in porting existing code using TAutoComplete to TJuiAutoComplete: +

    +

    + +

    TDraggable and TDropContainer

    +

    +TDraggable and TDropContainer have been deprecated and replaced respectively by TJuiDraggable and TJuiDroppable. +The options for the new controls are available at jQueryUI's API documentation. +

    + +     -- cgit v1.2.3