A new addition to WebXtra since version 4 is the concept of events. The Xtra sprite will generate scripting events that are sent directly to scripts attached to it, and pass the normal message chain in Director, reaching frame and movie scripts if they are not handled at the sprite level. This avoids the need to poll the browser for information continuously, as your scripts will be informed of any changes necessary. All events pass the "spriteRef" as the first parameter, and this value can be used to extract information about the sprite that generated the event directly.
Some events accept return values to indicate how the browser should react to a specific situation. Using events it is possible for example to block the creation of popup windows or authorize navigation to a specific link or URL, before it takes place. If you need more information please study the "WebBrowser_Behavior" script, attached to the "Complete Browser" example that ships with the Xtra. This is a good example of a simple behavior showing how your scripts can intercept events and act on them.
It is not necessary to implement a script to handle all events if you are not planning to use them: the Xtra will assume default values if an event is not handled. You can implement handlers only for the events that are appropriate for your movie, or you can use the pre-made behaviors available at our site as a starting point for your own scripts. Below are the events generated by WebXtra 4:
displayScrollBars(spriteRef) - Generated by the sprite when a browser window is create or refreshed, to control the display of outer scroll bars in the main window frame. Scripts can return FALSE to prevent scroll bars from appearing. The default behavior of the browser is to automatically create scroll bars.
Lingo example:
on displayScrollBars spriteRef
return false
end
JavaScript syntax example:
function displayScrollBars(spriteRef){
return false
}
showContextMenu(spriteRef) - Called by the Xtra when the user clicks with the right mouse button over the HTML area, to invoke the standard browser context menu. You can return TRUE to allow the menu to appear (the default value), or FALSE to prevent the menu from being displayed.
Lingo example:
on showContextMenu spriteRef
return false
end
JavaScript syntax example:
function showContextMenu(spriteRef){
return false
}
navigateError(spriteRef, URL, frameName) - This event is generated when the browser can not load an URL. It may be a malformed URL or one that is not currently online. The event parameters include the name of the URL that failed as well as the name of the frame containing it if the navigation was invoked in an HTML frame. The default action is to display the standard error URL for Internet Explorer, but you can instead return FALSE from this handler and present your own customized error message.
Lingo example:
on navigateError spriteRef, URL, frameName
alert("There was an error trying to load "&URL)
return false
end
JavaScript syntax example:
function navigateError(spriteRef, URL, frameName ){
_player.alert("There was an error trying to load "+URL)
return false
}
fileDownload(spriteRef) - Called by WebXtra when a local file is opened or a download operation is started. The operation can be canceled by returning FALSE. The default value is to let the download operation to start.
Lingo example:
on fileDownload spriteRef
return false
end
JavaScript syntax example:
function fileDownload(spriteRef ){
return false
}
startNavigation(spriteRef, URL, frameName) - This event is generated by WebXtra to request authorization to navigate to a given URL. You can use it to generally monitor all page navigation operations before they occur. It allows your scripts to restrict navigation to only certain sites, or intercept special URLs.
Your code should return true to allow the navigation to take place, or false to cancel it silently. Here are some examples:
Lingo examples:
on startNavigation spriteRef, URL, frameName
-- Only load pages from the macromedia.com domain
if not (URL contains "macromedia.com") then
alert("blocked")
return false
end if
-- Alternatively, you could blocks a specific domain
-- if URL contains "macromedia.com" then
-- return false
-- end if
--by default we allow all operations to complete
return true
end
JavaScript syntax example:
function startNavigation(spriteRef, URL, frameName ){
// Only load pages from the macromedia.com domain
if (URL.indexOf("macromedia.com") < 0) {
_player.alert("blocked")
return false
}
// Alternatively, you could blocks a specific domain
// if (URL.indexOf("macromedia.com") >= 0) {
// return false
// }
//by default we allow all operations to complete
return true
}
execDirectorScript(spriteRef, URL, scripttext) - This event is generated by WebXtra when the Javascript interpreter in the browser attempts to use the window.external.execDirectorScript(scripttext) function. It is a way to extend the HTML DOM directly: you can pass single line scripts or multiple line ones. For reference, check the SCRIPTING sample at the WebXtra tutorials and samples page. You can also use it to pass any sort of message to Director, as the full scripttext is available to Director for parsing, in either Lingo or JS.
Here are some examples:
Lingo examples:
on execDirectorScript spriteRef, scripttext
-- Simply execute a snippet of Lingo passed directly:
do scripttext
-- Alternatively, you could parse the scripttext, and do whatever you want with the text passed.
-- For example the scripttext could be a message like "lingo:reloadMovie"
if scripttext contains "lingo:" then
--use the do command to execute the "reloadMovie" handler
do URL.char[7..the number of chars in URL]
end if
end
JavaScript syntax example:
function execDirectorScript(spriteRef, scripttext ){
// Simply execute a snippet of JS passed directly:
eval(scripttext)
// Alternatively, you could parse the scripttext, and do whatever you want with the text passed.
// For example the page could contain a link that points to "js:reloadMovie"
if (URL.indexOf("js:") == 0) {
// parse the rest of the URL here, and pass it to the do command for execution
}
}
openNewWindow(spriteRef) - This handler is called by the Xtra sprite when the browser receives a request to create a new popup window. There are three possible return values:
a) True (or 1) indicates that the operation should be allowed. The browser will create a standard, independent floating browser window, not controlled by the Xtra.
b) False (or 0) blocks the creation of the new popup window.
c) Advanced users can also instruct the browser to use an existing WebXtra browser window to handle the request. This is done by passing the "browserReference" property of any WebXtra sprite as a return value. The "Complete Browser" sample movie distributed with the Xtra has a full implementation of this behavior, where a new movie in a window is created to handle all popup requests. You can also return the the same browser window as the target of the popup operation, but some web sites do not handle this situation well and may generate Javascript errors in their pages. See the examples below:
Lingo example:
on openNewWindow spriteRef
--if we want to reuse the existing browser sprite for the new window:
--return spriteRef.browserReference
--
--to allow the independent window to be created:
--return true
--
--in this case we want to block all popups
return false
end
JavaScript syntax example:
function openNewWindow (spriteRef) {
//if we want to reuse the existing browser sprite for the new window:
//return spriteRef.browserReference
//
//to allow the independent window to be created:
//return true
//
//in this case we want to block all popups
return false
}
closeWindowRequested(spriteRef) - This handler is invoked when the browser receives a request to terminate the browser window, usually invoked by a Javascript call (window.close()) in the HTML code. WebXtra will never automatically destroy the window, but your code can schedule a window destruction if you want, specially for popup movies. It is important to notice that it is not recommended to quit the application or forget a window directly from this callback, as this interrupts normal message processing. Instead, it is recommended to set a flag or spawn a timeout that will destroy the window after the current handler has ended its execution. We recommend checking the Complete Browser sample available at the Tutorials page on our site for a proper implementation of window destruction.
Lingo example:
on closeWindowRequested spriteRef
--sets a flag to indicate the window should be destroyed
pMustDestroyWindow = TRUE
end
JavaScript syntax example:
function closeWindowRequested(spriteRef){
//calls a routine to destroy the window
scheduleWindowTermination()
}
progressChange(spriteRef, progress, progressmax) - This handler is called by WebXtra to signalize a network operation in progress. The two parameters progress and progressmax indicate how much of the operation has completed. A progress value of -1 or a progressmax value of 0 indicate that the operation has completed or was aborted.
Lingo example:
on progressChange spriteRef , progress, progressmax
if progress>-1 and progressmax>0 then
put string((float(progress)/float(progressmax)*100)) &"% completed"
end if
end
JavaScript syntax example:
function progressChange(spriteRef, progress, progressmax){
if ((progress>-1) && (progressmax>0)){
trace((progress/progressmax*100.0).toString+"% completed")
}
}
titleChange(spriteRef, newTitle) - Called by WebXtra to signalize that the title of the document currently loaded has changed, usually when a page begins to load.
Lingo example:
on titleChange spriteRef , newTitle
(the activeWindow).title = newTitle
end
JavaScript syntax example:
function titleChange(spriteRef, newTitle){
_player.activeWindow.title = newTitle
}
statusTextChange(spriteRef, newText) - This handler is invoked when the text that needs to be displayed in the status bar has changed.
Lingo example:
on statusTextChange spriteRef , newText
member("statustext").text = newText
end
JavaScript syntax example:
function statusTextChange(spriteRef, newText){
member("statustext").text = newText
}
navigateBackState(spriteRef, enabled) - Called to indicate the current state of BACK navigation in the browser history, usually when a page finishes loading, or whenever necessary. Your code can use this information to enable or disable the BACK button in your interface.
Lingo example:
on navigateBackState spriteRef , enabled
if enabled=true then
sprite(8).membernum = member("enabledbutton").membernum
else
sprite(8).member.membernum = member("disabledbutton").membernum
end if
end
JavaScript syntax example:
function navigateBackState(spriteRef, enabled){
if (enabled==true) {
sprite(8).membernum = member("enabledbutton").membernum
} else {
sprite(8).member.membernum = member("disabledbutton").membernum
}
}
navigateForwardState(spriteRef, enabled) - Called to indicate the current state of FORWARD navigation in the browser history, usually when a page finishes loading, or whenever necessary. Your code can use this information to enable or disable the FORWARD button in your interface.
Lingo example:
on navigateForwardState spriteRef , enabled
if enabled=true then
sprite(9).membernum = member("enabledbutton").membernum
else
sprite(9).member.membernum = member("disabledbutton").membernum
end if
end
JavaScript syntax example:
function navigateForwardState(spriteRef, enabled){
if (enabled==true) {
sprite(9).membernum = member("enabledbutton").membernum
} else {
sprite(9).member.membernum = member("disabledbutton").membernum
}
}
secureLockState(spriteRef, state) - Called by WebXtra to inform the current state of the lock icon, indicating that a secure connection is in place. Valid state values are from 0 to 6. Values greater than 0 indicate that some sort of secure connection is in place. See the table below for the meaning of each value:
0 = Unsecured
1 = Mixed Environment (some elements are secure, others are not)
2 = Secure connection, unknown strength
3 = Secure connection using 40 Bit encryption
4 = Secure connection using 56 Bit encryption
5 = Secure connection using Fortezza encryption
6 = Secure connection using 128 Bit encryption
Lingo example:
on secureLockState spriteRef , state
if state> 1 then
put "Secure connection in place"
end if
end
JavaScript syntax example:
function secureLockState(spriteRef, state){
if (state>1) {
trace("Secure connection in place")
}
}