Getting Started With MCML

The MCML is an XML format describing profile and other display items in ParaWorld, such as task, quick action, action feed, tradableitem, etc. One can think of it as the HTML counterpart in 3D social networking world for describing renderable objects in both 2D and 3D

Mapping

MCML use similar architecture as java,html or ajax, if you are familiar with these technic, following mapping table may help you learn MCML, Java---> NPL HTML--->MCML AJax --> ParaWorldAPI+NPL+MCML

Code Behind

Inline Script

script/kids/3DMapSystemUI/Desktop/LoginPage.html

<script type="text/npl">
    <![CDATA[
    function OnInit()
       local self = document:GetPageCtrl();
       self:SetNodeValue("username", Map3DSystem.User.Name);
       self:SetNodeValue("password", Map3DSystem.User.Password);
    end
    OnInit()
    ]]>
  </script>

Inline Code Scoping (Page). Compiled each time the page is loaded or refreshed.

Function Invoke: Page scope

External Script

To a clean separation of MCML from presentation logic, one can put logic code in a separate lua file. We call this file as External Script. Use following code to set external script in MCML file:

<script type="text/npl" src="script/myExternalScirpt.lua"></script>

The code above equivalent to NPL.load(), so, code in external script is only compiled once.

Page Instance

MCML file and corresponding external script file define the a templet of page. One can create many instance with same templet . As long as your mcml page is derived from PageCtrl, one can use PageCtrl:Create(name, _parent, alignment, left, top, width, height),

to create a new instance of this page.

Page API Reference

Access to node , value and UI in MCML page

NPL.load("(gl)script/kids/3DMapSystemApp/mcml/mcml_base.lua"); NPL.load("(gl)script/kids/3DMapSystemApp/mcml/PageCtrl.lua");

Form

Form is for data binding for a group of input nodes.

the callback contains values, which name and value pairs.

Document Object Model (DOM)

Availability

document is a context containing the page node and page instance.

Where is document? When can you use document object?

PageCtrl

document:GetPageCtrl(): NPL.load("(gl)script/kids/3DMapSystemApp/mcml/PageCtrl.lua");

Write Method

<span style="font-weight:bold;color:#66000">
        <script type="text/npl"><![CDATA[
            local releaseYear, releaseMonth, releaseDay = 2008, 6, 19;
            local _,_, year, month, day = string.find(ParaGlobal.GetDateFormat("yyyy M d"), "(%d+)%s+(%d+)%s+(%d+)")
            if(year and month and day) then
                year = tonumber(year)
                month = tonumber(month)
                day = tonumber(day)
                local daysLeft = (releaseYear-year)*365+(releaseMonth-month)*30+(releaseDay-day);
                document:write(tostring(daysLeft));
            end 
        ]]></script>
    </span>

NodeValue v.s. UIValue

page:SetNodeValue

page:SetUIValue

CSS and Page Layout

Traditional desktop application user interface development is mostly based on absolute positioning of visual elements, namely setting properties on controls to affect their location and size. There are some higher-level concepts one can use to make it easier to create UIs that adapt to a changing Window size, such as docking and anchoring of controls to their respective containers. MCML addresses those issues very well, in many cases by borrowing some of the better layout concepts from the world of HTML.

css style inheritance order: parent-->Class-->tag style

<div style="margin:5px;float:left;background:;" class="defaultbutton">some inner text<br/>

Test your page

Only modified mcml (html) code : no need to restart ParaEngine Keep the Engine window open, and fine tune your UI.

modified external script code: needs to restart ParaEngine

Asynchronous page pattern

Page build pipeline (process):

1. read MCML to tree node instructure.
2. Per Instance: Create UI process (including document:write())
   • SetUIValue of a tag node is only available when that node's UI is created.
3. Page refresh (Asynchronous): Page:Refresh()

Localisation

php POEdit base mothor template, and many translation.

Rule: Use Chinese

Misc

1. Use Path replaceables like %WIKI%
2. query parameter (query string): script/kids/3DMapSystemApp/profiles/FriendsPage.html?tab=everyone

Examples

DOM example

inline script, etc. script/kids/3DMapSystemApp/Login/StartPage.html