PageCtrl

an interactive NPL control initialized from a MCML file

Description

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

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,
}

constructor

syntax

function PageCtrl:new (o)

parameters

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. |

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. |

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

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

PageCtrl:SetWindowText

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

syntax

function PageCtrl:SetWindowText(text,icon)

parameters

PageCtrl:OnLoad

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

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

PageCtrl:Refresh

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

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. |

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

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

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

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

PageCtrl:GetBindingContext

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

function PageCtrl:GetBindingContext(name)

function PageCtrl:GetRoot()

function PageCtrl:GetNode(name)

function PageCtrl:SetNodeText(name, text)

function PageCtrl:SetNodeValue(name, value)

function PageCtrl:GetNodeValue(name)

function PageCtrl:SetUIValue(name, value)

function PageCtrl:GetUIValue(name)

function PageCtrl:SetValue(name, value)

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

function PageCtrl:UpdateRegion(name)

function PageCtrl:SubmitForm(formNode)

function PageCtrl.OnPageDownloaded_CallBack(xmlRoot, entry, self)