New Message: Macros

[webmaster at userland.com]

A new message was posted:

Address: http://frontier.userland.com/discuss/msgReader$11807

By: Lawrence Lee (lawrence at userland.com)

<rules><!-- 1.5 spacing -->
   <rule><outlineSpacing>1.5</outlineSpacing></rule>
   </rules>
Macros provide a way for you to include calculated elements in your Manila web pages and templates. Macros are a <a href="http://frontier.userland.com/stories/storyReader$3281">Frontier feature</a> that have been enabled in Manila sites, and are key to producing dynamic browser-editable sites.
By opening macros to Manila users, we offer a taste of the kind of customization we do, behind the scenes, as we develop Manila. It's a learning process.
<rules><!-- bold headings -->
   <rule level="1" to="1"><textStyle>bold</textStyle></rule>
   </rules>
Example
   If you include \&#123;10 * 10\&#125; in a page on your Manila site, you see {10 * 10}
Macros don't just do math
   They can do lots of other kinds of calculations too, like manipulating pieces of text, counting the number of words in a sentence, or displaying a greeting message.
   Let's say you wanted to display a customized greeting message for any user who is currently logged in to your site. You could use a macro to do this. Here's how:
   Copy and paste the following text into your homepage:
   \&#123;if whoAmI != "" \&#123;return ("Hi there, " + string.nthField (whoAmI, '&nbsp;', 1) + "!")\&#125; else &#123;return ("")\&#125;\&#125;
   This will display the text "Hi there, Jake!" in the page, whenever a user whose first name is "Jake" is logged in.
How does this work?
   Manila sites already included the macro, \&#123;whoAmI\&#125;. It returns some text that looks like this: "Jake Savin is logged in." When the user is not logged in, \{whoAmI} returns nothing (the empty string).
   But we only wanted to get the user's first name, and include that in our own customized message. We didn't want the whole sentence. So we used the string.nthField&nbsp;(whoAmI, '&nbsp;', 1) to extract the first word of the sentence -- the user's first name.
   string.nthField is one of the newly legal Frontier verbs. If you're already familiar with Frontier, the syntax should be familiar to you.
What's a verb?
   Like verbs in a spoken language, a verb in macro performs an action.
   You give (pass) it some information, it does something with it, and it returns the result to you. 
   In the example above, we passed three things to the string.nthField verb: the string of text, "Jake Savin is logged in." from the whoAmI macro; a space character represented as '&nbsp;', which is used to determine how to break the string into words; and the number 1 representing which word -- which field -- we wanted to extract from the string.
   string.nthField returned the first word, "Jake".
How if ... else ... and curly braces work
   The first curly brace, \&#123;, signals the begining of your macro. The last one, \&#125;, signals the end. The ones inside your macro delimit blocks of code that if and else apply to.
   When you use an "if" statement, you specify what happens if the condition is true, and optionally what happens if it's not true. The first pair of braces after the if statement encloses the part of your macro which will be evaluated if the condition is true, and the second pair after the "else" encloses the part which will be evaluated if the condition is not true.
   In this example, we test to see if whoAmI contains some text -- that it does not equal (!=) the empty string (""). If the test is true, the first code block which returns the welcome message gets evaulated. If the test is false, the second block gets evaluated, returning the empty string.
How quotes characters work
   The quote characters (\") inside macros are different from the quote characters used for shortcuts.
   They represent the begining and ending of a string of text. In the example above, we used quote characters to represent the start and end of the string, "Hi there, ". (Note the trailing space in the example.) We also used quotes to delimit the exclamation point, and the empty string that's returned if noone is logged in.
   If you want to use a quote character inside a string, you escape the quote character using a backslash like this: \\&quot;
   Say for example, that you don't want a greeting like "Hi there, Jake!", but you want a message like this:
      \"Jake\" is the current user.
   (Note the quotation marks around the user's name.)
   Your macro would look like this:
   \&#123;if whoAmI != "" \&#123;return ("\&quot;" + string.nthField (whoAmI, ' ', 1) + "\&quot; is the current user.")\&#125; else &#123;return ("")\&#125;\&#125;
   Single characters are enclosed in single quote marks (the key next to the enter or return key on most keyboards). In this example, the space character is represented by '&nbsp;'. A comma character would be represented represented by ','.
   Text strings of more than one character are always enclosed in double-quotes, for instance: "a string of text".
A second example: dynamic copyright messages
   Say you've got a site that was started in the year 2000, and you want to place a copyright message at the bottom of every page. You want the copyright message to say "&copy; 2000" until the year changes to 2001, after which you want the message to say "&copy; 2000-2001".
   It's easy to write a macro which does this.
   Copy and paste the following text into your template:
   \&#123;if year == 2000 \&#123;return (\"&amp;copy; 2000\")&#125; else \&#123;return (\"&amp;copy; 2000-\" + year)&#125;
   This macro takes advantage of the fact that like whoAmI, year is a legal macro. It returns the current year.
   The macro in this example tests to see if the year is still 2000. If it is, the macro returns the string, "&copy; 2000", and otherwise it returns a string like this: "&copy; 2000-2001".
   Looking closely, you can see that when the year changes from 2001 to 2002, what you'll see on your pages is "&copy; 2000-2002", because after the year 2000, the macro includes the current year after the '-'.
Can I use Frontier or Radio UserLand to edit macros?
   Yes you can. You can create a script in Frontier or Radio, and paste it into your site.
   The pasted text of the script will automatically be formatted correctly, including curly braces that define code blocks.
   Keep in mind that you will need to put curly braces around the whole script after you paste it in, or else it won't be evaluated as a macro. If you don't do this, you may see strange results -- statements outside code blocks will end up as text in your page, and statements inside code blocks will be evaluated as macros since they're inside curly braces. If we'd forgotten the braces around the copyright example, here's what we'd see in the page during the year 2000:
      if year == 2000 &copy; 2000 else &copy; 2000-2000
   Remember that macros are powerful. When you write one, you're writing a little program, and as with writing any program, it has to be just right, or you'll get unexpected results. 
Can I use carriage returns, spaces and tab characters to format my macro so that it's easier to read?
   Yes you can. In fact, if you paste a Frontier or Radio UserLand script into your site, it will contain the carriage returns and tab characters that correspond to the formatting in the outline-based script editor.
   You also get the curly braces which define code blocks.
See also
   <a href="http://macros.userland.com/">Macros.UserLand.Com</a>