PG Software Development

by **Clifton** » Fri Dec 18, 2015 10:36 pm

LAST UPDATED: August, 8, 2016 | September 13, 2016 | May 21, 2017 | September 1, 2019
This topic requires PowerPac v12.862 or above.
NOTE: Some features may require PowerPac v13.x beta.

What is the XML <make> tag that the PowerPac interprets?
Answer: With the release of PowerPac v12.860, support has been added to dynamically create elements (objects) during the loading of a page. These elements can be created in level 0 DOM area which is the area outside the ToolBook page content frame. Or the elements can be created inside the level 1, or ToolBook page area. Dynamically created object in the level 0 area remain in place for the entire browser session and do not have to be refreshed each time a page loads. Dynamically created objects can have their own functions and behavior and ToolBook is able to send events (on user, on click, on trigger) to these objects to summon specific behavior.

Why create level 0 elements?
Answer: These elements can be used to contain static menus, page footers, or video players that permit true full screen viewing. There are many uses for these objects in extending the look and feel of your application and in adding additional features.
The example below shows an exported page without XML. Click the button to load the XML. The XML file will cause ToolBook to execute some PowerPac functions, create a background object from a <make> tag and transform the look of the page.

As you can see by viewing the NEXT page of the above ToolBook export, the XML is very simple in format. PLUS, when you navigate to the next page the level 0 object (from the <make> tag in the XML) does not have to reload itself. Therefore, no flashing of content occurs. If you come to a page where the anchor object (which defines the bounds of the level 0 DOM object) is missing, the PowerPac behavior is to hide the level 0 object to avoid misalignment with objects on the current page.

You will also notice that when you go back to the first page of the demo, the XML content modifications "stick" and so clicking the "Trigger XML Loading" button appears to have no effect. The PowerPac will avoid processing <make> tags that have already been created in the current browser session. If the object(s) is/are deleted, and the XML is reloaded, then the PowerPac will rebuild the object(s) from the cached <make> tags. All of this presents fascinating potential in creating effects in your exported content. There are no limits on the number of <make> tags in an XML and you can nest <make> tags to create merged groups of objects.

XML <make> tag declaration:
The PowerPac XML parser recognizes the following <make> tag properties:

type = "string" (required)
This value is a HTML tag name that defines the type of element that you want the XML parser to create. Usually, the most common values would be "div" or "span". However, the XML parser will attempt to create any valid HTML element.
id = "string" (required)
This is the HTML id identifier. This value ensure the object can be found and manipulated by JavaScript calls like document.getElementById("id"). NOTE: id properties are case sensitive in all modern browsers.
level = "0" or "1" (defaults to "0" if unset)
This property determines whether the object should be created in the level 0 DOM area which is above or outside the ToolBook content frame. Or level 1 which is inside the ToolBook frame as an additional object to those already created by the loading of the ToolBook page. The area (or namespace) in which the object is created is up to you and is generally based on the effect you are trying to achieve.
dims = "string" (optional)
If set, this is a comma-separated string of 4 values.
Value format is "[left pos],[top pos],[width as integer pixels, percent, or auto],[height as integer pixels, percent or auto]"
Example 1: "24,24,100,200" ... creates object with left position at 24px, top position at 24px, width of 100px and height of 200px.
Example 2: "24,24,auto,200" ... similar to above but set the width to auto-size based on the HTML content of the element.
Example 3: "24,24,100%,200" ... similar to above but set the width to 100% of parent and height to 200 pixels..
NOTE: This property can also be set to the name of the a ToolBook object. The new element created will be set to match the bounds of the ToolBook object. Also accepts the string
```
"page"
```
to match the size and bounds of the object to the ToolBook page. You can set autoAlign="true" to maintain the alignment when the browser window changes. (See details at autoAlign.)
Example 4: "video_player" ... creates object whose bounds matches a ToolBook object named "video_player"
NOTE: If you are loading a css or adding styling which already sets the bounds of the new object, then leave the dims property unset.
class = "string" (optional)
A class name definition from a CSS stylesheet this is loaded with PowerPac's pgExtFiles() or via the <config> section of the XML file.
refObj = "string" (optional)
This property determines where the stacking order should begin for newly created objects. If unset, this defaults to "syspageDiv" for level 0 objects; for level 1 objects, this value defaults to placing the newly created objects on top of all ToolBook page objects.
NOTE: To begin stacking new objects UNDER the ToolBook frame content, use refObj="sysbootstrap"
autoAlign = "true" or "false" (defaults to "false" if unset)
This property adds some JavaScript to each newly created object to ensure the alignment with it's ToolBook object is maintained. If you are setting the dims property to a valid ToolBook object AND you are creating a level="0" object, then you should usually set autoAlign="true" so that the new level 0 DOM object stays in alignment if/when the browser window is resized.
replace = "true" or "false" (defaults to "false" if unset) or "remove"
When set to "true" the XML parsing engine will REPLACE any object that shares the same id with an object that matches the new <make> object definition.
When unset or set to "false" the <make> object definition is ignored if an object sharing the same id already exists.
When set to "remove" the <make> object definition section of the XML file is ignored ONLY IF an object by the same id already exists. The XML parsing engine will proceed to REMOVE the object that already exists. This is useful to destroy a previously created object with a <make> object definition.
Removing an object previous created is as simple as loading an XML file with this line:
```
<page>
    <make id="[ObjID]" replace="remove"> </make>
</page>
```

The following sub-tags are parsed inside a <make> tag:

<style> ... </style>
This tag defines CSS styles to apply to the newly created element/object.
Typical Format:
<htmlText> ... </htmlText>
This tag define the innerHTML property of the newly created object container. Any valid HTML code can be entered as long as it is wrapped inside a CDATA descriptor. This tells the XML parser that the code entered is to be treated as raw code and not XML-related code.
Example:
<text> ... </text>
This tag is similar to the <htmlText> tag with the exception that the text is treated as raw text and HTML code and tags will not be compiled. Use this tag to define text for input fields and textareas.
<function ... [properties]> ... </function>
Multiple function sub-tags are allowed. Function tags allow you to define functions that should be assigned to events on the newly created object/element. You can define functions for clicks, triggers, user events, etc. (See section on Attaching Functions for property support description.)
Example:
<exeJavascriptDirect> [raw JavaScript code] </exeJavascriptDirect>
Use this tag to execute newly added functions or other custom JavaScript when the <make> tag is parsed.
Code: Select all
<make id="myLogo" ... [other properties] > <function name="myFct" event="click" params="evt"> <![CDATA[ var id = this.id; alert( "Hello World! The id of this element is: " + id ); ]]> </function> <exeJavascriptDirect> <![CDATA[ var obj = document.getElementById( "myLogo" ); obj.myFct(); //Executes above function immediately when XML is parsed ]]> </exeJavascriptDirect> </make>
<make ... [properties]> ... </make>
You can nest additional <make> tags. Each object created will be attached to the <make> tag in which it is nested. All sub-tags are supported within nested <make> tags.

Attaching Functions to newly created objects inside a <make> tag:
You can create functions for <make> objects OR for any ToolBook object referenced in your XML file. The <function ...[properties] > [body] </function> sub-tag takes the following properties:

name = "string" (optional)
If a name property is specified in a <function> tag, the function will become a named property (or method) of the new object and callable by this name.
Example:
Code: Select all
<make level="0" id="myLogo" type="div" ... > <function name="xfct" event="click" params="evt"> <![CDATA[ alert( "Hello World!" ); ]]> </function> </make>

NOTE: In this example, the defined function "xfct" could be called when the object whose id is "myLogo" is clicked. OR, it could be called directly as [object].xfct() in a JavaScript from another object or script. You can even use pgTBObjSet() to call this function or method regardless of whether the object it is attached to is on level 0 (top level) OR 1 (ToolBook frame level).
event = "string" (optional but required if no name property is assigned)
This property is the name of an event that executes the function. Usually "click", "trigger", "user", "mouseover", "mouseout" are the most common event types. You can create the same function to respond to multiple events by comma-separating the events.
Example of the same function used for mouseover and mouseout events:
Code: Select all
<make level="0" id="myLogo" type="div" ... > <function name="ms" event="mouseover,mouseout" params="evt"> <![CDATA[ if (evt.type == "mouseover") { this.innerHTML = "mouse has entered this " + this.tagName + " area"; } else if (evt.type == "mouseout") { this.innerHTML = "the mouse has left me"; } ]]> </function> </make>

NOTE: The single function can respond differently depending on which event was received. The [this] keyword refers to the object which received the event. Therefore, in the above example our function would change the innerHTML property of our container (usually a <div> or a <span> element) with new text.
params = "string"
This property defines the parameters that may be submitted to your function. For clicks, mouse events, etc. a single parameter should be specified to hold the event object. This object contains important information about the event received. If your function may be called remotely as a named property of the object, then you may want assign additional parameters to this string. Multiple parameters my be entered as a comma-separated string.
useTB = "string" as true or false (default)
This property tells the XML Parsing Engine to check whether the object for which a function is being defined is a native Toolbook object. If it is and useTB="true", then the parser will attempt to create the function using the internal ToolBook event listener system. This means that if the object already has a click event defined in the Actions system and the XML Parser encounters a function assigned for the click event, it will attempt to append the XML function to the already existing Actions Editor click event. The actions click will execute first followed by the XML click function.

NOTE: You may have to define additional parameters for functions with useTB="true" in order to get predictable data passed to your function. For example, to get the value parameter of a user event when the XML function is appended to the already existing ToolBook actions event:
Code: Select all
<function name="myUser" event="user" params="evt,value" useTB="true"> <![CDATA[ alert( "This is the [ value ] parameter of the user event: " + value ); ]]> </function>

As shown in the examples above, the body of the function is written between the opening and closing function tag descripors.
Format:

Code: Select all: <function ... [properties] > <![CDATA[ (Write your function body here.) ]]> </function>

NOTE: Your function body must be wrapped inside a CDATA tag to prevent XML parse errors when special characters are encountered.

The <function ... [properties]> ... </function> is supported for ToolBook objects as well. Therefore, if you have an object named "Field_1" and you want assign a custom method to this object, you can do so as follows:

Code: Select all: <Field_1> <htmlText> <![CDATA[ <p class="custSty"> This is a paragraph of text that will be inserted as the HTML content <b>inside</b> this field. </p> ]]> </htmlText> <function name="insTxt" event="" params="txt"> <![CDATA[ this.innerHTML += '<p class="custSty">' + txt + '</p>'; ]]> </function> </Field_1>

NOTE: The above XML code will put some default text into a field named "Field_1" and then create a function for appending text to the field each time the function is called. To execute the function called insTxt(), create this exeJavascriptDirect string and execute it in the Actions Editor.

var obj = gTBo( "Field_1", "objRef");
if (obj) {
    obj.insTxt( "Add this text to my field." );
}

NOTE: Functions are METHODS of the objects to which they are assigned. This is true whether the object is a ToolBook or an object created by the <make> tag.

Enjoy using the new <make> tag in your ToolBook WEB/XML applications!
Feel free to post your questions or start a specific topic where necessary.

PG Software Development

Using the NEW <make> tag to create elements

Using the NEW <make> tag to create elements

Who is online