PageCtrl

an interactive NPL control initialized from a MCML file

Title an interactive NPL control initialized from a MCML file
Author(s) LiXizhi
Date 2008/3/20
File script/kids/3DMapSystemApp/MCML/PageCtrl.lua

Description

In many cases, we want to build interactive control from a static or asynchronous MCML file. The MCML file contains the layout and default databinding for all UI elements. However, to make those UI element interactive, we need to associate NPL code with that MCML file. The PageCtrl automates the above design pattern, by creating an NPL control from an MCML file. One can implement predefined or MCML page defined event handlers in it. One can also easily nagivate and access UI and databinding controls defined in the MCML file. It is a Code-Behind Page pattern to seperate UI with logics. And the UI may be asynchronously loaded such as an URL.

Note: it will only search and render the first occurance of pe:mcml node in the url

TIP Sample Code

NPL.load("(gl)script/kids/3DMapSystemApp/mcml/PageCtrl.lua");
MyApp.MyPage = Map3DSystem.mcml.PageCtrl:new({url="script/kids/3DMapSystemApp/mcml/test/MyPageControl_UI.html"});
-- on load
function MyApp.MyPage:OnLoad()
   -- anything here
end
-- One can also override the default refresh method to implement owner draw. 
function MyApp.MyPage:OnRefresh(_parent)
   Map3DSystem.mcml.PageCtrl.Refresh(self, _parent);
end

-- one can create a UI instance like this. 
MyApp.MyPage:Create("instanceName", _parent, "_fi", 0, 0, 0, 0)

-- call Goto to change url after or before Create is called. 
MyApp.MyPage:Goto(url, cache_policy, bRefresh)

Member Functions

PageCtrl:new

 a browser window instance.
local PageCtrl = {
   name = nil,
   -- nil means not started downloading. 1 means ready. 0 means downloading. 2 means not able to download page.  3 means <pe:mcml> node not found in page body. 
   status = nil,
   -- the status string message
   status_line = nil,
   -- the <pe:mcml> node
   mcmlNode = nil,
   -- a function to be called when a new page is downloaded. 
   OnPageDownloaded = nil,
   -- default policy if no one is specified. 
   cache_policy = Map3DSystem.localserver.CachePolicy:new("access plus 1 hour"),
   -- default refresh page delay time in seconds. More information, please see Refresh() method. 
   DefaultRefreshDelayTime = 1,
   -- default page redirect delay time in seconds. More information, please see Redirect() method. 
   DefaultRedirectDelayTime = 1,
   -- time remaining till next refresh page update. More information, please see Refresh() method. 
   RefreshCountDown = nil,
   -- the init url, if this is not provided at first, one needs to call Init(url) before calling Create()
   url = nil,
   -- we will keep all opened url in a stack, so that we can move back or forward. This is just a simple table array for all opened urls. 
   opened_urls = nil,
   -- if nil it means the last one in opened_urls, otherwise, the index of the current url in opened_urls 
   opened_url_index = nil,
   -- mcml page to be displayed when an error occurs.
   errorpage = nil,
   -- in case this page is inside an iframe, the parentpage contains the page control that created the iframe. use GetParentPage() function to get it. 
   parentpage = nil,
   -- the window object containing the page control. CloseWindow() function will close this window object. 
   window = nil,
}
Map3DSystem.mcml.PageCtrl = PageCtrl;

constructor

syntax

function PageCtrl:new (o)

parameters

o  

PageCtrl:Init

Init control with a MCML treenode or page url. If a local version is found, it will be used regardless of whether it is expired or not. It does not create UI until PageCtrl:Create() is called. NOTE: Calling this function with different urls after PageCtrl:Create() will refresh the UI by latest url.

  • param url : the url of the MCML page. It must contain one node. Page should be UTF-8 encoded. It will automatically replace %params% in url if any if url is nil, content will be cleared. if it is a table, it will be the mcmlNode to open.
  • param cache :_policy: cache policy object. if nil, default is used.
  • param bRefresh : whether to refresh if url is already loaded before.

syntax

function PageCtrl:Init(url, cache_policy, bRefresh)

parameters

| url | the url of the MCML page. It must contain one node. Page should be UTF-8 encoded. It will automatically replace %params% in url if any if url is nil, content will be cleared. if it is a table, it will be the mcmlNode to open. |

cache  
policy  
bRefresh whether to refresh if url is already loaded before.

PageCtrl:Goto

go to a given url or move backward or forward. This function can NOT be called in embedded page code. In page script, use Redirect() instead.

  • param url : it can be the url or string "backward", "forward". If it is url path, its page must contain one node. Page should be UTF-8 encoded. It will automatically replace %params% in url if any if url is nil, content will be cleared. if it is a table, it will be the mcmlNode to open.
  • param cache :_policy: cache policy object. if nil, default is used.
  • param bRefresh : whether to refresh if url is already loaded before.
  • return true : if it is processing to the next stage.

syntax

function PageCtrl:Goto(url, cache_policy, bRefresh)

parameters

| url | it can be the url or string "backward", "forward". If it is url path, its page must contain one node. Page should be UTF-8 encoded. It will automatically replace %params% in url if any if url is nil, content will be cleared. if it is a table, it will be the mcmlNode to open. |

cache  
policy  
bRefresh whether to refresh if url is already loaded before.

PageCtrl:Create

create (instance) the page UI. It will create UI immediately after the page is downloaded. If page is local, it immediately load.

  • param name : name of the control. it should be globally unique if page is asynchronous. and it can be anything, if page is local.

syntax

function PageCtrl:Create(name, _parent, alignment, left, top, width, height)

parameters

name name of the control. it should be globally unique if page is asynchronous. and it can be anything, if page is local.
parent  
alignment  
left  
top  
width  
height  

PageCtrl:Close

close and destory all UI objects created by this page. only call this function if self.name is a global name.

syntax

function PageCtrl:Close()

PageCtrl:GetParentPage

in case this page is inside an iframe, the parentpage contains the page control that created the iframe.

syntax

function PageCtrl:GetParentPage()

PageCtrl:GetWindow

get the parent window containing this page.

syntax

function PageCtrl:GetWindow()

PageCtrl:CloseWindow

close the containing window

  • param bDestroy : if true, it will destroy the window, otherwise it will just hide it.

syntax

function PageCtrl:CloseWindow(bDestroy)

parameters

bDestroy if true, it will destroy the window, otherwise it will just hide it.

PageCtrl:SetWindowText

set the text and/or icon of the page's container window

syntax

function PageCtrl:SetWindowText(text,icon)

parameters

text  
icon  

PageCtrl:OnLoad


overridable functions

this function is overridable. it is called before page UI is about to be created. You cannot use view-state information within this event; it is not populated yet.

  • param self :.mcmlNode: the root pe:mcml node, one can modify it here before the UI is created, such as filling in default data.

syntax

function PageCtrl:OnLoad()

PageCtrl:OnCreate

this function is overridable. it is called after page UI is created. One can perform any processing steps that are set to occur on each page request. You can access view state information. You can also access controls within the page's control hierarchy. In other words, one can have direct access to UI object created in the page control. Note that some UI are lazy created such as treeview item and tab view items. They may not be available here yet.

syntax

function PageCtrl:OnCreate()

PageCtrl:OnRefresh

refresh the page UI. It will remove all previous UI and rebuild (render) from current MCML page data. it will call the OnLoad method. Note One can override this method to owner draw this control.

  • param __ :_parent: if nil, it will get using the self.name.
  • return __ : the parent container of page ctrl is returned.

syntax

function PageCtrl:OnRefresh(_parent)

parameters

parent  

PageCtrl:GetUsedSize

get the used size of the page. This is called to obtain the actual size used to render the mcml page.

syntax

function PageCtrl:GetUsedSize()

PageCtrl:AddOpenedUrl

add current opened url to the opened urls stack so that we can move forward or backward. if the last url is the same as current, url will not be added.

  • param url :; nil or url string to add. if nil, self.url is used.

syntax

function PageCtrl:AddOpenedUrl(url)

parameters

url ; nil or url string to add. if nil, self.url is used.

PageCtrl:Refresh


public method: for accessing mcml node, UI, and databinding objects in the page.

refresh the entire page after DelayTime seconds. Please note that during the delay time period, if there is another call to this function with a longer delay time, the actual refresh page activation will be further delayed Note: This function is usually used with a design pattern when the MCML page contains asynchronous content such as pe:name, etc. whenever an asychronous tag is created, it will first check if data for display is available at that moment. if yes, it will just display it as static content; if not, it will retrieve the data with a callback function. In the callback function, it calls this Refresh method of the associated page with a delay time. Hence, when the last delay time is reached, the page is rebuilt and the dynamic content will be accessible by then.

  • param DelayTime : if nil, it will default to self.DefaultRefreshDelayTime (usually 1.5 second). tip: If one set this to a nagative value, it may causes an immediate page refresh.

syntax

function PageCtrl:Refresh(DelayTime)

parameters

| DelayTime | if nil, it will default to self.DefaultRefreshDelayTime (usually 1.5 second). tip: If one set this to a nagative value, it may causes an immediate page refresh. |

PageCtrl.OnFrameMove_

private method

syntax

function PageCtrl.OnFrameMove_(pageName)

parameters

pageName  

PageCtrl:Redirect

Same as Goto(), except that it contains a delay time. this function is safe to be called via embedded page code. it will redirect page in DelayTime second

  • param url : relative or absolute url, like you did in a src tag if url is nil, content will be cleared. if it is a table, it will be the mcmlNode to open.
  • param cache :_policy: cache policy object. if nil, default is used.
  • param bRefresh : whether to refresh if url is already loaded before.
  • param DelayTime : if nil, it will default to self.DefaultRedirectDelayTime(usually 1 second). we do not allow immediate redirection, even delayTime is 0

syntax

function PageCtrl:Redirect(url, cache_policy, bRefresh, DelayTime)

parameters

| url | relative or absolute url, like you did in a src tag if url is nil, content will be cleared. if it is a table, it will be the mcmlNode to open. |

cache  
policy  
bRefresh whether to refresh if url is already loaded before.
DelayTime  

PageCtrl:GetRequestParam

get request url parameter by its name. for example if page url is "www.paraengine.com/user?id=10&time=20", then GetRequestParam("id") will be 10.

  • return __ : nil or string value.

syntax

function PageCtrl:GetRequestParam(paramName)

parameters

paramName  
return nil or string value.

PageCtrl:DataBind

Binds current data source to the all page controls

syntax

function PageCtrl:DataBind()

PageCtrl:GetDataItem

Gets the first data item by its name in the data-binding context of this page.

syntax

function PageCtrl:GetDataItem(name)

parameters

name  

PageCtrl:SetFocus

Sets the focus to the control with the specified name.

  • param name : The name of the control to set focus to

syntax

function PageCtrl:SetFocus(name)

parameters

name The name of the control to set focus to

PageCtrl:FindControl

Searches the page naming container for a server control with the specified identifier.

  • note __ : this function is NOT available in OnInit(). use this function in OnCreate()
  • return __ : It returns the ParaUIObject or CommonCtrl object depending on the type of the control found.

syntax

function PageCtrl:FindControl(name)

parameters

name  

PageCtrl:GetBindingContext

Get bindingtext in the page by its name. a page will automatically create a binding context for each and

node.
  • return __ : binding context is returned or nil. bindContext.values contains the data source for the databinding controls.

syntax

function PageCtrl:GetBindingContext(name)

parameters

name  
return binding context is returned or nil. bindContext.values contains the data source for the databinding controls.

PageCtrl:GetRoot

get the root node. it may return nil if page is not finished yet.

syntax

function PageCtrl:GetRoot()

PageCtrl:GetNode

get a mcmlNode by its name.

  • return __ : the first mcmlNode found or nil is returned.

syntax

function PageCtrl:GetNode(name)

parameters

name  
return the first mcmlNode found or nil is returned.

PageCtrl:SetNodeText

set the inner text of a mcmlNode by its name. this function is usually used to change the text of a node before it is created, such as in the OnLoad event.

syntax

function PageCtrl:SetNodeText(name, text)

parameters

name  
text  

PageCtrl:SetNodeValue

set a MCML node value by its name

  • param name : name of the node
  • param value : value to be set

syntax

function PageCtrl:SetNodeValue(name, value)

parameters

name name of the node
value  

PageCtrl:GetNodeValue

Get a MCML node value by its name

  • param name : name of the node
  • return __ : the value is returned

syntax

function PageCtrl:GetNodeValue(name)

parameters

name name of the node

PageCtrl:SetUIValue

set a MCML node UI value by its name. Currently support: text input

  • param name : name of the node
  • param value : value to be set

syntax

function PageCtrl:SetUIValue(name, value)

parameters

name name of the node
value  

PageCtrl:GetUIValue

Get a MCML node UI value by its name. Currently support: text input

  • param name : name of the node
  • return __ : the value is returned

syntax

function PageCtrl:GetUIValue(name)

parameters

name name of the node

PageCtrl:SetValue

set node value and set UI value if UI can be found.

syntax

function PageCtrl:SetValue(name, value)

parameters

name  
value  

PageCtrl:CallMethod

call a page control method

  • param name : name of the node
  • param methodName : name of the method
  • return __ : the value from method is returned

syntax

function PageCtrl:CallMethod(name, methodName, ...)

parameters

name name of the node
methodName  
return the value from method is returned

PageCtrl:UpdateRegion

Update the region causing all MCML controls inside the region control to be deleted and rebuilt. and are the only supported region control at the moment. This function is used to reconstruct a sub region of mcml in a page. if the region control is not created before, this function does nothing, this is the correct logic when the region control is inside a lazy loaded control such as a tab view.

  • param name : name of the region control.
  • return true : if succeed

syntax

function PageCtrl:UpdateRegion(name)

parameters

name name of the region control.

PageCtrl:SubmitForm

automatically submit a form.

  • param formNode : form node or nil. if nil, it will use the first form found.

syntax

function PageCtrl:SubmitForm(formNode)

parameters

formNode form node or nil. if nil, it will use the first form found.

PageCtrl.OnPageDownloaded_CallBack

called when page is downloaded

syntax

function PageCtrl.OnPageDownloaded_CallBack(xmlRoot, entry, self)

parameters

xmlRoot  
entry  
self  
Topic revision: r1 - 2008-02-29 - LiXizhi
 
This site is powered by the TWiki collaboration platform Powered by PerlCopyright © 2008-2021 by the contributing authors. All material on this collaboration platform is the property of the contributing authors.
Ideas, requests, problems regarding TWiki? Send feedback