---++!! !PageCtrl %TOC{title="Contents:"}% %STARTINCLUDE% ---++ 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 %T% __Sample Code__ <verbatim> 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) </verbatim> ---+++ Member Functions ---++++ !PageCtrl:new <verbatim> 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, }</verbatim> Map3DSystem.mcml.PageCtrl = PageCtrl; constructor __syntax__ <verbatim>function PageCtrl:new (o)</verbatim> __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 <pe:mcml> 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__ <verbatim>function PageCtrl:Init(url, cache_policy, bRefresh)</verbatim> __parameters__ | *url* | the url of the MCML page. It must contain one <pe:mcml> 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 <pe:mcml> 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__ <verbatim>function PageCtrl:Goto(url, cache_policy, bRefresh)</verbatim> __parameters__ | *url* | it can be the url or string "backward", "forward". If it is url path, its page must contain one <pe:mcml> 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__ <verbatim>function PageCtrl:Create(name, _parent, alignment, left, top, width, height)</verbatim> __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__ <verbatim>function PageCtrl:Close()</verbatim> ---++++ !PageCtrl:GetParentPage in case this page is inside an iframe, the parentpage contains the page control that created the iframe. __syntax__ <verbatim>function PageCtrl:GetParentPage()</verbatim> ---++++ !PageCtrl:GetWindow get the parent window containing this page. __syntax__ <verbatim>function PageCtrl:GetWindow()</verbatim> ---++++ !PageCtrl:CloseWindow close the containing window * _param_ __bDestroy__ : if true, it will destroy the window, otherwise it will just hide it. __syntax__ <verbatim>function PageCtrl:CloseWindow(bDestroy)</verbatim> __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__ <verbatim>function PageCtrl:SetWindowText(text,icon)</verbatim> __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__ <verbatim>function PageCtrl:OnLoad()</verbatim> ---++++ !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__ <verbatim>function PageCtrl:OnCreate()</verbatim> ---++++ !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__ <verbatim>function PageCtrl:OnRefresh(_parent)</verbatim> __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__ <verbatim>function PageCtrl:GetUsedSize()</verbatim> ---++++ !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__ <verbatim>function PageCtrl:AddOpenedUrl(url)</verbatim> __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__ <verbatim>function PageCtrl:Refresh(DelayTime)</verbatim> __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__ <verbatim>function PageCtrl.OnFrameMove_(pageName)</verbatim> __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__ <verbatim>function PageCtrl:Redirect(url, cache_policy, bRefresh, DelayTime)</verbatim> __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__ <verbatim>function PageCtrl:GetRequestParam(paramName)</verbatim> __parameters__ | *paramName* | | | *return* | nil or string value. | ---++++ !PageCtrl:DataBind Binds current data source to the all page controls __syntax__ <verbatim>function PageCtrl:DataBind()</verbatim> ---++++ !PageCtrl:GetDataItem Gets the first data item by its name in the data-binding context of this page. __syntax__ <verbatim>function PageCtrl:GetDataItem(name)</verbatim> __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__ <verbatim>function PageCtrl:SetFocus(name)</verbatim> __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__ <verbatim>function PageCtrl:FindControl(name)</verbatim> __parameters__ | *name* | | ---++++ !PageCtrl:GetBindingContext Get bindingtext in the page by its name. a page will automatically create a binding context for each <pe:editor> and <form> node. * _return_ ____ : binding context is returned or nil. bindContext.values contains the data source for the databinding controls. __syntax__ <verbatim>function PageCtrl:GetBindingContext(name)</verbatim> __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__ <verbatim>function PageCtrl:GetRoot()</verbatim> ---++++ !PageCtrl:GetNode get a mcmlNode by its name. * _return_ ____ : the first mcmlNode found or nil is returned. __syntax__ <verbatim>function PageCtrl:GetNode(name)</verbatim> __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__ <verbatim>function PageCtrl:SetNodeText(name, text)</verbatim> __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__ <verbatim>function PageCtrl:SetNodeValue(name, value)</verbatim> __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__ <verbatim>function PageCtrl:GetNodeValue(name)</verbatim> __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__ <verbatim>function PageCtrl:SetUIValue(name, value)</verbatim> __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__ <verbatim>function PageCtrl:GetUIValue(name)</verbatim> __parameters__ | *name* | name of the node | ---++++ !PageCtrl:SetValue set node value and set UI value if UI can be found. __syntax__ <verbatim>function PageCtrl:SetValue(name, value)</verbatim> __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__ <verbatim>function PageCtrl:CallMethod(name, methodName, ...)</verbatim> __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. <pe:container> and <pe:editor> 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__ <verbatim>function PageCtrl:UpdateRegion(name)</verbatim> __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__ <verbatim>function PageCtrl:SubmitForm(formNode)</verbatim> __parameters__ | *formNode* | form node or nil. if nil, it will use the first form found. | ---++++ !PageCtrl.OnPageDownloaded_CallBack called when page is downloaded __syntax__ <verbatim>function PageCtrl.OnPageDownloaded_CallBack(xmlRoot, entry, self)</verbatim> __parameters__ | *xmlRoot* | | | *entry* | | | *self* | | %STOPINCLUDE%
E
dit
|
A
ttach
|
P
rint version
|
H
istory
: r1
|
B
acklinks
|
V
iew topic
|
Ra
w
edit
|
M
ore topic actions
Topic revision: r1 - 2008-02-29
-
LiXizhi
Home
Site map
CCWeb web
HaqiTeen web
Main web
ParaEngine web
TWiki web
Main Web
Users
Groups
Index
Search
Changes
Notifications
RSS Feed
Statistics
导航页WebTopMenu
Preferences
开发指南
Getting Started
ParacraftSDK
NPL
MCML
NPL Reference Manual
美术Mod
Account
Log In
English
简体中文
簡體中文
E
dit
A
ttach
Copyright © 2008-2024 by the contributing authors. All material on this collaboration platform is the property of the contributing authors.
Ideas, requests, problems regarding TWiki?
Send feedback