Simple Use Case: YAHOO.plugin.Dispatcher
Markup (dispatcher container element):
<div id="mydynamicarea">
</div>
Script:
YAHOO.plugin.Dispatcher.fetch ( 'mydynamicarea', 'PATH/TO/CONTENT/page.html' );
The Dispatcher Manager will fetch the remote page, and set the response as the content of the container area "mydynamicarea".
Singleton: YAHOO.plugin.Dispatcher
YAHOO.plugin.Dispatcher.fetch(str|HTMLElement|obj el,
str uri, obj config);
Arguments:
(1) HTML ID or HTMLElement of the container.
(2) The remote file used by the connection manager.
(3) Configuration Object: JS object defining configuration
properties for the area. See Configuration
section for full list.
YAHOO.plugin.Dispatcher.delegate(obj tab, obj tabview, obj config);
Arguments:
(1) reference to the new tab.
(2) reference to the tabview (optional).
(3) Configuration Object: JS object defining configuration
properties for the area. See Configuration
section for full list
YAHOO.plugin.Dispatcher.process(str|HTMLElement|obj el,
str content, obj config);
Arguments:
(1) HTML ID or HTMLElement of the container.
(2) content: You can use another component to managemente the ajax process, and pass the response directly to the dispatcher to process the content and put it inside the container.
(3) config: Configuration Object: JS object defining configuration
properties for the area. See Configuration
section for full list
YAHOO.plugin.Dispatcher.cssLoader(str uri,
obj config);
Arguments:
(1) The remote JS file used by the connection manager.
(2) config: Configuration Object: JS object defining configuration
properties for the JS file. See Configuration
section for full list
YAHOO.plugin.Dispatcher.jsLoader(str uri, obj config);
Arguments:
(1) The remote CSS file used by the connection manager.
(2) config: Configuration Object: JS object defining configuration
properties for the CSS file. See Configuration
section for full list
YAHOO.plugin.Dispatcher.applyCSS(str cssCode,
obj params, obj config);
Arguments:
(1) cssCode: a chunk of CSS code.
(2) params: List of properties for the new CSS tag (media, href, etc).
(3) config: Configuration Object: JS object defining configuration
properties for the CSS chunk. See Configuration
section for full list
Solutions:
Use the dispatcher to process the tabview connection method
var tabView = new YAHOO.widget.TabView({id: 'demo'});Use the dispatcher to load a remote uri inside a DIV:
YAHOO.plugin.Dispatcher.delegate (new YAHOO.widget.Tab({ label: 'Remote Scripts', dataSrc: 'PATH/TO/xhtml.with.remote.scripts.html', cacheData: true, active: true }), tabView);
YAHOO.plugin.Dispatcher.fetch ( 'my_dynamic_area', 'PATH/TO/xhtml.with.remote.scripts.html' );
Use the dispatcher to process the content provided by an external package:
var area = YAHOO.util.Dom.get ('dynamic_area');
YAHOO.plugin.Dispatcher.process ( area, 'xhtml content here...' );
CSS Injection:
// injecting a remote CSS file in your page... YAHOO.plugin.Dispatcher.cssLoader( 'css-injection-default.css'); // injecting certains CSS's rules in your page...
YAHOO.plugin.Dispatcher.applyCSS ("#demo {border: 1px solid #ff0000;} #demo ul {text-align: center;}");
Avoid memory leaks:
Define the rules to destroy the controls/widgets before change the content of the areas. In this example the dispatcher will destroy the DataTable control, releasing the memory and then will display the new content. Also, by default, the dispatcher will release all the listeners defined for elements within a area before display the new content (YAHOO.util.Event.purgeElement).
// setting the destruction's rules from inside (use this sentence at the end of the remote content)
YAHOO.plugin.Dispatcher.destroyer.subscribe (function(el, config){
myDataTable.destroy ();
}); // setting the destruction's rules from outside (use this senctence at any time) YAHOO.plugin.Dispatcher.onDestroy = function ( areaID, function(el, config){
myDataTable.destroy ();
}, scope);
Key Interesting Moments in Dispatcher
Events | Fires | Arguments | Execution Scope |
---|---|---|---|
onStart |
...before start the loading or the process methods | [0] element: container DOM ref | config: Configuration Object |
before |
Deprecated in favor of onStart... | [0] element: container DOM ref | config: Configuration Object |
onReady |
...after display the new content and before start the execution process | [0] element: container DOM ref | config: Configuration Object |
onLoad |
...after finish the execution process | [0] element: container DOM ref | config: Configuration Object |
after |
Deprecated in favor of onLoad... | [0] element: container DOM ref | config: Configuration Object |
onDestroy |
...before display the new content | [0] element: container DOM ref | config: Configuration Object |
Key Dispatcher Configuration Options
Option (type) | Default | Description |
---|---|---|
action (s) |
'replace' | sustitution method (replace | update | tabview) |
scope (o) |
window | Object used for correction of the execution scope for remote scripts. |
onStart (f) |
null | Deafult function for the corresponding moment |
onLoad (f) |
null | Default function for the corresponding moment |
onDestroy (f) |
null | Default function for the corresponding moment |
relative (b) |
false | If the path of the remote assets (CSS, Images and JS files) is relative or not. |
baseURI (s) |
null | The base URI for relative assets. (by default the baseURI is the path to the remote content) |
Dependencies
Requires:
YUI:YAHOO, YUI:Dom, YUI:Event and YUI:Connection
Facts
- The dispatcher simulate the browser execution (ordered execution)
- The dispatcher allow cross reference within the dynamic area (YAHOO.util.Dom.get ('id_of_element_within_container')
)
- The dispatcher use lineal execution (one thread)
Firewall:
Before load the content of an external source, the dispatcher will analyze the URI, at this point you can define your own routine to determine if the source can be loaded or not, defining your own policies.
In this case we can use the configuration object to define this policies:
proxy
(string
):
It's an URL that will be used to load external sources thru a proxy, by default the proxy setting is:
'/dispatcher.php?uri='monolithic
(bool
)
It's an option parameter, iftrue
the dispatcher will be forced to complied with the cross domain policy, loading only the files from the same domain.firewall
(function
):
It's an optional function that will override theproxy
and themonolithic
parameters, and will be called it using the URI as the first argument, and using the configuration object like the scope, and the result of this function will be used like the correct URI; if the result isn't an string, this file will be discarded.
Example:
YAHOO.plugin.Dispatcher.fetch ( 'my-div', '/PATH/TO/my-url.html', { proxy: '/PATH/TO/my-proxy.php?f=' });
YAHOO.plugin.Dispatcher.fetch ( 'my-div', '/PATH/TO/my-url.html', { firewall: function(uri){ // transform the uri... return uri; }
});
See the API Docs at full screen in a new window:
Events
I see the events onStart, onLoad and onDestroy. But i'm asking what are the exact moments dispatcher fires these events?
Btw, the dispatcher is a great tool to load and savely execute js code dynamicaly. It should be part of the YUI Library.
RE: Events
Hello Bernhard, thanks for the kind words.
About the events, these are not Custom Events, they are just hook methods (functions defined in the configuration object), and they will be executed at certain moments:
1. onStart: immediately after starting the AJAX request to the server.
2. onLoad: after the whole process, which mean after inserting the content within the DIV, and executing the scripts as well.
3. onDestroy: just before replacing the content of the DIV for the new content.
Makes sense for you?
About including the Dispatcher as part of the YUI library, I don't think we will include it in the HEAD branch, it's like an advanced plugin.
Events
Thx for the explaination, and yes, it makes sense. But it wasn't clear from the above sentense 'Default function for the corresponding moment'. Now its clear what the real moment is if they are fired.
struts2 firefox compatibility
thanks very much for your distribution.
I use it with struts 2 and YUI tabview. It's working fine in IE. but Firefox won't work.
the error message is
Error: dojo.lang is undefined
Source File: http://localhost:8080/portal/struts/dojo/dojo.js
Line: 1014
Error: YAHOO is not defined
Source File: http://localhost:8080/portal/pages/javascript/yui/build/dispatcher/dispatcher.js
Line: 172
Error: dojo.hostenv is undefined
Source File: http://localhost:8080/portal/struts/dojo/src/browser_debug.js
Line: 11
RE: struts2 firefox compatibility
Hey John,
Do you have a test-case or something, to take a look, and dig a little bit?
How to reuse same tab with different contents?
Hi,
First of all, great library!
After a tab is created & populated with dynamic contents using delegate, how do I reuse the tab and load it with a different dynamic content again? I can't seem to find example on this. Would appreciate some good advice.
YAHOO.plugin.Dispatcher.delegate (new YAHOO.widget.Tab({
label: 'Browser',
dataSrc: sUrl,
active: true
}), tabView);
Re: How to reuse same tab with different contents?
@AJ, thanks for the kind words.
The delegation process is not related with the loading process (AJAX call using YUI Connection Manager). Dispatcher only post-process the response of the AJAX call. You can handle the url directly thru the tab object. Here is an example:
var tab = new YAHOO.widget.Tab({
label: 'Browser',
dataSrc: sUrl,
dataCache: false,
active: true
});
YAHOO.plugin.Dispatcher.delegate (tab, tabView);
// later on:
tab.set ('dataSrc', myNewUrl);
So, next time the user visit that tab, the new url will be used to load the content of the tab. Keep an eye on dataCache. :-)
If you want to refresh the current tab,, you can dig a little bit in the YUI Tab documentation, and you will see few options to do it.
IE8 / Tables
Not sure if anyone's come across this problem. We've been using the Dispatcher in conjunction with Tabview for a while and it's been great until IE8 came out.
The problem appears to be that when the dispatcher tries to load some html containing a table, the table will not render at all within the tab.
Is there a quick workaround for this?
Thanks
RE: IE8 / Tables
@Alex:
Few questions:
- Did you tried this without dispatcher? probably using firebug to inject the html content manually?
- Is IE8 running in compatibility mode?
- Is the code that you're trying to inject a valid HTML fragment without HTML/BODY/HEADER?
Normally, rendering issues are not related with the dispatcher. :-)
And finally, can you provide a test-case to analyze this?
onfailure
Hi. Just came across this plug-in and I am already benefiting from it. My question: is there an onfailure configuration option when calling the fetch method. Sort of the equivalent of success and failure options in YAHOO.util.asyncRequest call.
Thanks,
Sundar
RE: onfailure
Hello Sundar,
In the same way you use onStart, onLoad, onDestroy, you can use onError. The method will receive two arguments:
el - DOM reference to the container element
o - YUI Connection Manager Object reference where you can collect more information about the error.
Also, if you use "fetch" method, it will return the handler for the YUI Connection Manager object that you can use to define your own success and failure listeners.
Best Regards,
Caridy