MagicRepeat exemplifies our philosophy of extremely powerful, easy-to-use technology. It enables you to select blocks of HTML that can be repeated whenever the content manager wants to create a new section with the same layout. What if your client wants the ability to add news items to their page? All you have to do is create a news item template, wrap it in
<magicrepeat></magicrepeat> tags, and...that's it! When the content manager logs in, they click the "New" button to add a section and update the content with the latest news.
Of course, there are so many other uses for MagicRepeat. You can set up a blog in seconds; all you need is the opening and closing tag, then the content manager can repeat the block and add a new blog post. The same would go for testimonials. Page summaries. Even new pages!
A NOTE OF WARNING: Although it is not required, you should generally set the
me_name attribute on MagicRepeat. If you do not, you may see undesired behavior since MagicEdit names each MagicRepeat based on a hash of its content. That means that if you change any HTML inside a MagicRepeat block, MagicEdit will treat it as a completely new MagicRepeat, which may result in edited content being lost.
MagicRepeat lets you create a single template page, then quickly and easily duplicate that page by simply wrapping a link to that page with MagicRepeat tags. After you have designed your template page, put
<magicrepeat></magicrepeat> around the
<a> tag linking to your template page in your navigation. You must have
<a> tags in the MagicRepeat section in order for this to work. In this example, the MagicRepeat tags will enclose just the second nav item. We'll leave the Home link out of the MagicRepeat in this instance, since the home page may have a different layout than the rest of the pages (although MagicRepeat will work fine if there are no other
<a> tags). The second nav item will become the template link for every new page you add. It has MagicEdit tags because you will want to change the name of the newly created link for each new page.
<body> ... <div class="nav"> <li><a href="index.html">Home</a></li> <magicrepeat me_name="myPages"> <li> <a href="NewPage.html"> <magicedit me_name="navLink" me_plain>New Page</magicedit> </a> </li> </magicrepeat> </div> ... </body>
To create a new page, the content manager logs into the site and clicks the "New" button. They edit their newly created link in the navigation and update the content for the new page they just created. That's all there is to it!
Setting up a blog with MagicRepeat could not be any easier. All you have to do is format a single blog post, wrap the editable fields in MagicEdit tags, and wrap the region MagicRepeat tags!
<magicrepeat me_name="blog"> <magicedit me_name="content"> <h2>Article Title</h2> <p>Content of article</p> </magicedit> </magicrepeat>
Now you have a basic template for a single page of blog articles. If you want to create a blog with separate pages for each entry using just one HTML file, see our One Page Blog article in the Advanced Magic section.
To edit your first blog entry, login to your site and edit the title, summary, and content fields. For a new blog entry, just click the new button and edit the fields. It's that easy!
HTML specifications require IDs to be unique on a page. So what happens if you use MagicRepeat to duplicate an element with an ID set on it? You can see how this would be a problem. MagicEdit automatically updates the ID of any element inside a MagicRepeat region. Therefore, if you style a MagicRepeat element with an ID, the style will not be applied to any new elements. Use class instead of ID to style elements inside of a MagicRepeat.
MagicRepeat automatically increments the ID and name of any elements with an ID or name set with
_#, where # is the index of the repeat. For example, if you have an element set to
id="widget", the first instance will have
id="widget_1", the second will have
MagicRepeat has the following options:
It is best to name each MagicEdit/MagicRepeat region using the
me_name option. Here is an example:
<magicrepeat me_name="RegionName"> ... </magicrepeat>
If you give different MagicRepeat regions the same name, they will be updated with the same content across the site. If your goal is to create similar regions with different content, be sure the regions have different names (or no name at all.)
WARNING: Not setting me_name on a magicrepeat may result in all content and edits being lost if the code inside the magicrepeat tags is even slightly changed. MagicEdit cannot be responsible for lost content if me_name is not used.
You can use
<me_repeat="yes"> on pages linked from a
<magicrepeat> tag. The default is
<me_repeat="no">, which is contrary to MagicEdit tags and images. A great use of
<me_repeat="yes"> is to allow content managers to set up their own image gallery from an article page, for example. In most cases, however, you would not want to turn it on as it can cause major problems if used incorrectly. Never put
me_repeat="yes" on a MagicRepeat section containing an
<a> tag that points back to its own page.
If you do not want to expose the sort, delete, and new buttons on a MagicRepeat section, simply invoke the
me_hidebuttons option. For example:
<ul class="nav"> <magicrepeat me_name="news" me_hidebuttons> <li> <a href="newsDetail.html"><magicedit me_hidebuttons>Title</magicedit></a> </li> </magicrepeat> </ul>
Note that you must explicitly set the
me_hidebuttons option on MagicEdit regions inside MagicRepeat sections as well. This allows you the flexibility to determine precisely when the editing functions are exposed to the content manager.
You should only use this when you know that there is another place on the site where the user can manage this MagicRepeat instance. Remember that you can "edit once change everywhere" by using the same
me_name on MagicRepeats throughout the site. The
me_hidebuttons option allows the site designer to choose when the management buttons should be displayed and when they shouldn't.
A particularly useful application of the
me_hidebuttons option on MagicRepeats is for generating dynamic navigation menus.
There are a some of advanced methods available in MagicRepeat that can be very useful when building rich MagicEdit sites.
If you need a count of the number of instances of a repeat, you can use the
indexes.count method. An example of its use on a repeat that has
me_name="myRepeat" would be:
<p>My repeat has <cl_marker cl_binding="$myRepeat.indexes.count" /> instances.</p>
This will simply insert an integer value of the number of repeats. Note that there is always at least one repeat.
Sometimes you might want to show or hide something if there are actually multiple repeats on the page. Here's how you would hide a
div if there is only one instance of a repeat with
me_name="myRepeat" and an administrator is not logged in by using
cl_visible in conjunction with
<div cl_visible="=CLManager.activeSession.account:isAdmin||!$myRepeat.indexes.containsMultipleObjects"> <magicrepeat me_name="myRepeat"> ... </magicrepeat> </div>
This is using the
! to invert the logic here. In plain English this means, "Only show this
div if an administrator is logged in or if
myRepeat has repeated regions." Note that you can show or hide anything on the site using this method, not just the repeat itself.
One of the most useful methods is hiding and showing things on a page based on if a particular MagicRepeat has anything in it that has been edited via MagicEdit (e.g. MagicEdit for text, images, or links). This is really useful when you don't want to show the entire repeat block if it only contains placeholder text because the content manager hasn't edited anything yet, or you want to place an optional section on the page (e.g. an image gallery or set of file downloads) that should "disappear" if it doesn't contain anything and the administrator is logged out.
<div cl_visible="=CLManager.activeSession.account:isAdmin||$myRepeat.hasEdits"> <magicrepeat me_name="myRepeat"> ... </magicrepeat> </div>
By default, MagicRepeat regions will be user-sortable. That is, they will appear to the content manager with up and down arrows so that they can be positioned however the user sees fit. In some cases it may be preferable to pre-define the sort and save the content manager from having to reposition new entries all the time.
Like some of MagicEdit's other advanced features, sorting is a function of the ClearLake framework and is called using the attribute
cl_sort. The default sort is
cl_sort="position", but you can also use
cl_sort="modified". "Created" and "modified" refer to the time the post was created or modified, respectively, and by default they display in ascending order (oldest to newest). To sort in descending order (newest to oldest), add a "-" in front of the value. For example, if you are creating a blog or news page, you will likely want to sort the articles by "created" date, from newest to oldest. The basic code would look something like this:
<magicrepeat cl_sort="-created"> <magicedit> <h2>Article Title</h2> <p>Content of article</p> </magicedit> </magicrepeat>
Keep in mind that if you use
cl_sort for anything other than "position", the up and down arrows will not be visible. If the content manager wants to reorganize the repeats, then you must remove
In some instances, you may want to display only a certain number of repeats. For instance, if you have a News page on your site and want to list the three most recent articles on the index page, you can use
me_maxitems to do so. To accomplish this, set up a news page to display links to all your articles and a newsDetail page that would serve as your article template file:
<ul> <magicrepeat me_name="newsRepeat" cl_sort="-created"> <li> <a href="newsDetail.html"> <magicedit me_name="pageTitle" me_plain>Page Title</magicedit> </a> </li> </magicrepeat> </ul>
<magicedit> <h2>Article Title</h2> <p>Content of article</p> </magicedit>
Take note of
me_name="newsRepeat" as it is required to make this exercise work. On the index page, use the same HTML as in news.html, but add
me_maxitems to the repeat tag:
<ul> <magicrepeat me_name="newsRepeat" cl_sort="-created" me_maxitems="3"> <li><a href="newsDetail.html"><magicedit me_name="pageTitle" me_plain>Page Title</magicedit></a></li> </magicrepeat> </ul>
The result will display the three newest items (as determined by
By default, MagicEdit injects up and down arrows by every repeat to enable manual sorting. If a sort option is chosen (such as
cl_sort="-created"), then these buttons are not displayed.
If there are a lot of repeated items, however, it can take a lot of time to resort them by simply clicking on the arrows one at a time. MagicEdit also supports shifting items up and down by more than one. By default, the following options are supported by simply holding a keyboard modifier key down (ALT or SHIFT):
For example, to move a given item by 7 items up, append
?meshift=7 to the end of the href found on the up arrow, and then set the
window.location to that URL. MagicEdit will apply the shift and reload the current page.
To move the maximum amount, just use 0 for n:
This will move to the end, either up or down depending on the direction of the arrow you chose.