Macros - dojo.E

Macros

> > >

Macros - Your friendly DOM Builder

Macros provide containers for modifications and templating. This allows for modifications to be run whenever needed, and for you to combine multiple modifications together. Macros in your application replace tedious HTML DOM building using string concatenation or more time consuming creation of a Dojo widget. Macros allow developers to specify how the DOM should be changed in an declarative way. This means that the same approach to building a DOM using HTML in a static page can be reused in a dynamic page.

Macros support three different formatting capabilities. These formats provide developers with the different options that may be helpful for creating the final HTML.

dojoe.util.MessageFormat - A very simple replacement syntax where the execute method takes a list of parameters that will be used to replace the {0}, {1} ... {4}
dojo.string.substitute - This is my favorite format, as it allows developers to use ${lastName}, ${firstName}. When using this format type the macro's execute method will take a single object. dojoe.macros.myMacro.execute(personObject)
dojox.dtl._Templated - This is the most complex and flexible formatting type as it will allow developers to use dojox's Django Templates.

Helpful Tip
Developers can simply connect macros to any HTML form component by using the "form" attribute. This functionality is added to


<form id="myForm">
	<input type="text" name="userNameField">
	<input type="text" name="passWordField">
</form>

<dojoe.Macro form="myForm">
	This text will be formatted with dojo.string.substitute:
	${userNameField} - ${passWordField}
</dojoe.Macro>

The following macro contains modifications that replace the contents of a "swapPanel" with a new HTML fragment. This code could be used to step through a wizard within your application.

Sample Macro Snippet

 
<declarations>
    <dojoe.Macro id="macro1">
    <dojoe.Xmodify>
        <replace-children query="div[id='swapPanel']">
		<div>
                      Last step is to configure the properties for the 
			Dashboard Component, Datasource, Widget!
		</div>
		<div>
			<label for="labelOptions">Choose Label:</label>
			<select id="labelOptions">{0}</select>	
			<br/><br/>										
			<label for="valueOptions">Choose Value:</label>
			<select id="valueOptions">{1}</select>
			<br/><br/>										
			<label for="hrefOptions">Choose Link:</label>
			<select id="hrefOptions">{2}</select>
		</div>
		<div style="width: 500px; text-align:right">
			<dijit.form.Button label="Finish" 
                                onclick="newWidget.pickItem()"/>							
		</div>	
        </replace-children>
    </dojoe.Xmodify>
    </dojoe.Macro>
</declarations>

Executing a Macro

When a Macro is created, an object is placed into the dojoe.macros object. Developers can access the Macro from an event handler using the macros object to find and execute the macro:

 
<ui>
    <dijit.layout.LayoutContainer>
    <dijit.layout.ContentPane>
        <img src="images/foreground.JPG" id="image1"/>
        <br/>
        <dijit.form.Button label="Press me"  
             onclick="dojoe.macros.macro1.execute()" 
             id="button1"/>
    </dijit.layout.ContentPane>
    </dijit.layout.LayoutContainer>
</ui>

For an example of a Macro in action, click on the "Old Label" button and see the text replaced with "New Label".

 
<script type="text/javascript">
      dojo.require("dijit.form.Button");
      dojo.require("dojoe.dojoe");
</script> 
<script type="text/xml" dojoType="dojoe.XmlScript">
   <declarations>
	<dojoe.Macro id="MyMacro">
            <dojoe.Xmodify>
                <set-attribute query="button[id='MyButton']">
                      <attribute name="label" value="New Label" />
                </set-attribute>
           </dojoe.Xmodify>
	</dojoe.Macro>
   </declarations>
   <ui xmlns="html" xmlns:dijit="dijit">
      <dijit:form.Button id="MyButton" 
               onclick="dojoe.macros.MyMacro.execute()" label="Old Label "/>
   </ui>
</script>

Helpful Tip
When using macros keep in mind the following things:

The modifications element can contain any number of XModify commands
Loading a new macro with the name already used to define another macro will overwrite the old macro

Macro Parametrization

To make macros more flexible, you can use MessageFormat syntax to perform string replacements. The following example loads a Macro after the page is finished loading.

To utilize parametrization in a macro, you need to do the following:

Add parameters to the macro. {0} - {n}, ${firstName} - ${any-property-name}, or depending on the templating mechanism.

Supply the values for the parameters to the macros execute(value0, ..., valueN); function.

The code snippet below shows a usage of a parametrized macro.

 
<!DOCTYPE HTML PUBLIC   "-//W3C//DTD HTML 4.01//EN"
    "http://www.w3.org/TR/html4/strict.dtd">
<html>
  <head> 
    <title>Test Dojo.E: Parametrized Macro.</title>
    <script type="text/javascript" djConfig="isDebug: true, parseOnLoad: true"
            src="js/dojo-release-1.1.1/dojo/dojo.js.uncompressed.js"></script>
    <script type="text/javascript">
	dojo.require("dojoe.dojoe");
	dojo.addOnLoad(function(){
		dojoe.macros.testMacro.execute("Hello World!");
	});
   </script> 
  </head> 
  <body> 
    <h1 class="testTitle">Test Dojo.E: Parametrized Macro.</h1> 
    <p id='testDescription'>
      If the test works, a greeting should appear as the next paragraph.
 
    <div id="greeting">Replace this with greeting...</div>
    <script type="text/xml" dojoType="dojoe.XmlScript">
      <declarations>
        <dojoe.Macro id="testMacro">
           <dojoe.Xmodify>
            <replace-children query="div[id='greeting']">
                     {0}
             </replace-children>
          </dojoe.Xmodify>
         </dojoe.Macro>
      </declarations>
    </script>
  </body>
</html>