Attribute Scripting Tutorial
This tutorial provides a quick introduction to EditMe's Attribute Scripting template language.
If you have not already, read through the Layouts page to understand how Layouts are used and managed in EditMe as these topics are not repeated here. This tutorial also assumes a basic proficiency with HTML.
0. Define a few terms...
<p editme="text 'Hello world!'"></p>
Before we get started, let's define a few terms so we don't get lost in term soup. The above is a one-line EditMe layout that produces <p>Hello world!</p>. We'll use this to define these terms:
| tag | The <p></p> part is called a tag. In XML parlance, this can also be called an element. You may find those terms being interchanged in the help content on this site. |
| attribute | The editme="..." part is called an attribute, and would be referred to as "the editme attribute of the P tag". |
| attribute script | The editme="..." part, while an attribute, is also an attribute script. What makes it an attribute script is that the name of the attribute is "editme". When EditMe processes a layout, it looks for every attribute named "editme" on every tag in the layout and processes the script found inside. |
| layout command | The text 'Hello world!' is a layout command. This is the text layout command, and the 'Hello world!' is a little piece of JavaScript that gives the text command something to go on. In this case, the text "Hello world!" will be placed inside the P tag. |
1. HTML for a Simple Layout
Moving on, we will start with plain HTML for a very simple layout. This layout will display menu content in a table cell on the left, and page content in the middle. Comments for the page will be displayed beneath the page content. In the right column will be a link to edit the page if the user has access. Otherwise, a login link will be shown in its place.
<html> <head> <title>Site Title</title> </head> <body> <table> <tr> <td class="menuColumn"> <div>Menu goes here.</div> </td> <td class="pageColumn"> <h1>Page title goes here</h1> <div>Page content goes here.</div> <hr> <div>Comments are listed here.</div> </td> <td class="toolsColumn"> <div>Edit Page or Login link goes here.</div> </td> </tr> </table> </body> </html>
After studying this HTML, we will add layout commands to implement each dynamic section.
2. Insert the Site Title
While we could simply type in a site title, using a layout command allows us to manage that value from within EditMe instead of having to change the layout. We simply add a "text" layout command to the title tag:
<html> <head> <title editme="text site.title">Site Title</title> </head> ...
In this example, we see the "text" layout command, which replaces the value of the tag with the result of the JavaScript argument. "site.title" is a bit of JavaScript that returns the title attribute of the site object. The site object is one of the implicit objects detailed on the JavaScript API page.
When this attribute script is processed, the "Site Title" text will be replaced with the title we have defined for our site in the Site Management -> General Settings screen.
3. Insert the Menu Content
Next, we'll pop in the menu page content. The Menu page is special in that it's always provided to us as an instance of the Page class named "menu".
... <td class="menuColumn"> <div editme="cdata menu.content">Menu goes here.</div> </td> ...
Here we see the cdata layout command in action. The cdata command inserts HTML content into the current tag, replacing whatever was there before ("Menu goes here." in this case). Compare the cdata and text commands at the Attribute Commands page to see how they're slightly different.
And remember, the Menu page is special... you couldn't do this with just any page. If you wanted to insert the MySpecialMenu page, you could use include 'MySpecialMenu' instead of the example above.
4. Insert the Page Title and Content
<h1 editme="text page.title">Page title goes here</h1> <div editme="cdata page.content">Page content goes here.</div>
We're cruising through two steps at once here because we've already covered both of these commands. Note the use of the "page" object. This always points to an instance of the Page class that is populated with the requested page.
It should be noted that "cdata page.content" will not work for Scripted Pages — it will simply dump the script code into the HTML document. If you want your layout to be able to process scripted pages, you would include page content with either the cdata or process commands based on a test whether the page is scripted or not:
<div editme="if !page.isScript ;; cdata page.content">Page content goes here.</div> <div editme="if page.isScript ;; process page">Scripted content goes here.</div>
5. List the Comments
What was:
<div>Comments are listed here.</div>
Becomes:
<div editme="foreach comment comments ;; parse">
<b>On {comment.date}, {comment.user} said:</b>
<br/>{comment.comment}
</div>
Here's something to sink our teeth into. The foreach command repeats its tag for every item found in an array of items. The comments array is provided by EditMe and contains an array of Comment objects representing the comments made on the current page. So if there are three comments, we'll get three <div> tags, each displaying one of the comments.
We also have two layout commands present in one attribute script. The ;; is what separates multiple layout commands. The parse command doesn't need any arguments here, and simply tells EditMe to look for {code snippets} in squiggly brackets and replace them with their appropriate values. A peak at the documentation for the Comment class will show you what these three scriptlets are doing.
6. Insert the Edit Page or Login Link
What was:
<div>Edit Page or Login link goes here.</div>
Becomes:
<div>
<a editme="if !user.isLoggedIn ;; parse href"
href="/_Login?redirect={page.name}">Login</a>
<a editme="if user.isLoggedIn ;; parse href"
href="/_Edit?page-id={page.name}">Edit This Page</a>
</div>
Here we see use of the if command. "if" here could be expanded to "only show this tag if the following is true". The if command looks at the JavaScript snippet provided and evaluates for true or false. If false, the tag is removed from the layout output.
There is no "else" command, so we have two if commands... one that looks for the user to not be logged in, and another that looks for the user to be logged in. Since both cannot be true at the same time, we'll only get one of these links... Login if the user hasn't logged in yet, and Edit This Page if the user has logged in.
We also see a fresh perspective on the parse command. All by itself, parse looks for squiggly bracket scripts within the tag content. If you give it one or more attribute names, it looks in the named attribute values instead. Here, we want to replace {page.name} with the current page name in these links.
7. Revel in Your New Layout Powers
Here is our finished layout.
<html>
<head>
<title editme="text site.title">Site Title</title>
</head>
<body>
<table>
<tr>
<td class="menuColumn">
<div editme="cdata menu.content">Menu goes here.</div>
</td>
<td class="pageColumn">
<h1 editme="text page.title">Page title goes here</h1>
<div editme="cdata page.content">Page content goes here.</div>
<hr>
<div editme="foreach comment comments ;; parse">
<b>On {comment.date}, {comment.user} said:</b>
<br/>{comment.comment}
</div>
</td>
<td class="toolsColumn">
<div>
<a editme="if !user.isLoggedIn ;; parse href"
href="/_Login?redirect={page.name}">Login</a>
<a editme="if user.isLoggedIn ;; parse href"
href="/_Edit?page-id={page.name}">Edit This Page</a>
</div>
</td>
</tr>
</table>
</body>
</html>
We're hoping if you got this far you have a good idea of how EditMe Layouts work. Read through the pages linked to from Developer Support to get all the details. Also, reading through the layouts in the provided skins will show you how all this stuff is used. Just install one of the new skins and then go to Settings -> Look & Feel -> Layouts and edit the Layout that got installed.