Rotating Image Banner

The Oncord rotator has seen numerous revisions throughout the years resulting in a robust, powerful tool for displaying content and allowing clients to easily manage banners on their website. One of the most common implementations of the rotator is for use as an image slider.

This article will explore various methods of implementing an image rotator on a Oncord powered website.

How The Rotator Works

The image rotator is created through use of the <ss:layout:rotator> tag, which is referenced in the Oncord api here. In order to take advantage of all the features and possibilities of the rotator tag, take note of all the "Tag Attributes" available in the api reference. The rotator tag should be supplied with an unordered list <ul> tag, where each of the element in the list <li> specifies the content to be displayed in the rotator. Each list item <li> should have the same width and height in order to ensure that the rotator renders correctly and other elements on the page don't shuffle around when the rotator changes between images.

Basic Hard-coded Image Rotator

This implementation is the most basic form of the image rotator and is referenced in this article mostly for the exercise of explaining the rotator in its least complicated implementation. This implementation technique isn't ideal, as there is no way for a general user to update the banner images through a UI without altering code. But this method is great for getting started with the image rotator, so here it is:

<div class="banner"> <ss:layout:rotator id="featured_rotator" startatrandom="false" movenextid="featured_rotator_next" movepreviousid="featured_rotator_previous"> <ul> <li> <ss:standard:image alt="Banner One" src="/media/website_designs/1/banner1.jpg" width="980px" height="375px" /> </li> <li> <ss:standard:image alt="Banner Two" src="/media/website_designs/1/banner2.jpg" width="980px" height="375px" /> </li> </ul> </ss:layout:rotator> <!-- featured_rotator control buttons for changing between different slides --> <div class="leftArrow"><a id="featured_rotator_previous" href="#"><img src="/media/website_designs/1/arrow-left.png" alt="Previous" /></a></div> <div class="rightArrow"><a id="featured_rotator_next" href="#"><img src="/media/website_designs/1/arrow-right.png" alt="Next" /></a></div> </div>

Explaining The Code

• Line 3: The opening of the <ss:layout:rotator> tag. The rotator has been given the id "featured_rotator". The startatrandom attribute is set to false, so this rotator will display the content in the order it is given, rather than randomly. The id of the next and previous buttons has been defined, it's good practise to use the format "rotatorId_rotator_direction" for the id's of the next and previous elements (eg. featured_rotator_next).
• Lines 4-11: An unordered list of images. The <ss:standard:image> tag has been used here (lines 6 and 9) instead of the regular HTML<img> tag.
• Lines 14 -16 : The elements used to change between rotator slides. Any click-able element can be used to change images, in this example the two <a> tags have been given the IDs relevant to the next and previous buttons (defined as moveNextId and movePreviousId on line 3).

In a typical implementation, the rotator is generally contained within a wrapping div element, followed by divs containing the rotator slider controls. Here is an example of the CSS code used to display a 980px wide, centered rotator with left and right slider controls.

.banner { width: 980px; height: 375px; margin: 0 auto; position: relative; } .rightArrow { right: -60px; top: 160px; } .leftArrow { left: -60px; top: 160px; }

Post-based Image Rotator

The posts functionality of Oncord can be used to allow general website admin users to update the banner via the posts section of the admin panel. This method is similar to the above example, however instead of defining the elements to be included in the rotator, an <ss:data:repeator> tag is used. This tag acts similar to a "for" loop. In this situation the repeater tag will be used to get all the post articles assigned to the post category "featured". Click here to view the API reference of the <ss:data:repeater> tag.

Before getting started coding this rotator, go to the admin panel and setup a new post category for the banner. In this example the category will be called "featured". After creating a new category, click on the post category to edit its details. On the post category edit screen, there is a tab titled "Developer". This tab will display the post category id, which is used when coding the below banner.

Copy and paste the following code into a design to implement a post-based image rotator:

<div class="banner"> <ss:layout:rotator id="featured_rotator" startatrandom="false" movenextid="featured_rotator_next" movepreviousid="featured_rotator_previous"> <ul> <ss:data:repeater datasource="\Components\Website\Posts::getAllForCategory(2)" as="post"> <li> <ss:logic:if test="$post['post_content_url']"> <a href="[? $post['post_content_url'] ?]"> <ss:standard:image alt="[? $post['post_title'] ?]" src="[? $post['post_icon'] ?]" width="780px" height="339px" maintainaspect="crop" /> </a> </ss:logic:if> <ss:logic:else> <ss:standard:image alt="[? $post['post_title'] ?]" src="[? $post['post_icon'] ?]" width="780px" height="339px" maintainaspect="crop" /> </ss:logic:else> </li> </ss:data:repeater> </ul> </ss:layout:rotator> <span class="leftArrow"><a href="#" id="featured_rotator_previous"><img src="/media/website_designs/1/icn-arrow-left.png" alt="navigator" /></a></span> <span class="rightArrow"><a href="#" id="featured_rotator_next"><img src="/media/website_designs/1/icn-arrow-right.png" alt="navigator" /></a></span> </div>

Explaining The Code

• Line 2: The opening of the <ss:layout:rotator> tag. The rotator has been given the id "featured_rotator". The startatrandom attribute is set to false, so this rotator will display the content in the order it is given, rather than randomly. The id of the next and previous buttons has been defined, it's good practise to use the format "rotatorId_rotator_direction" for the id's of the next and previous elements.
• Line 4: The opening of the <ss:data:repeater> tag. Everything between lines 4 and 15 is repeated for every element returned by the datasource attribute of this tag. In this example the data source attribute is a call to the function getAllForCategory(2). This number represents the post category Id.
• Lines 6: The opening of an <ss:logic:if> tag. The contents of this tag will only apply if the test attribute of this tag is true. In this case, the test is to determine whether the post is linked to a page.
• Line 11: The opening of an <ss:logic:else> tag. If the previous <logic:if> tag fails, the content included in this tag will apply.
• Lines 18 -19 : The elements used to change between rotator slides. Any clickable element can be used to change images, in this example the two <a> tags have been given the IDs relevant to the next and previous buttons (defined as moveNextId and movePreviousId on line 2).

Managing The Slider

The code for displaying the slider basically states "Display all posts which have the category of featured". You can add a new slider image by taking the following steps:

1. Navigate to the "posts" section of the admin panel by clicking the button labelled "posts" in the left-hand sidebar of the Oncord admin panel.
2. Click the "New post" button.
3. Enter a post title, it won't be displayed on the public site, however in order to keep data organized it's a good idea to name the post appropriately.
4. Set the post primary category to the category which is used for displaying the banner images.
5. Click "choose image" to choose an image for use on the slider. Ensure that the banner image is the same size as defined by your web designer. If it's not exact the website will crop the image to size.
6. The post teaser/ short description not relevant to banner posts.
7. Select a page to link the banner image to, or select "No link".
8. Save the post.

Post-based Image Rotator With Text

The short description field of a post, or the post title (or both) can be used to include text in a rotator. The following method is the same as the previous, however also uses the post short description field to add text to a slider. An <ss:logic:if> tag is used to test whether the post has a short description set, and adjust the rotator accordingly.

Copy and paste the following code into a design to implement a post-based image rotator with text:

<style type="text/css"> .banner { width:980px; height:400px; margin:0 auto; position:relative; } .rightNav { position:absolute; top:200px; right:-70px; } .leftNav { position:absolute; top:200px; left:-70px; } .bannerText { position: absolute; top: 315px; background: black; background:rgba(0,0,0,.75); padding: 10px; } .bannerText p{ margin:0; padding:0; color:#fff; } </style> <div class="banner"> <ss:layout:rotator id="featured_rotator" startatrandom="false" movenextid="featured_rotator_next" movepreviousid="featured_rotator_previous"> <ul> <ss:data:repeater datasource="\Components\Website\Posts::getAllForCategory(2)" as="post"> <li> <!-- If the post has a linked page --> <ss:logic:if test="$post['post_content_url']"> <a href="[? $post['post_content_url'] ?]"> <ss:standard:image alt="[? $post['post_title'] ?]" src="[? $post['post_icon'] ?]" width="780px" height="339px" maintainaspect="crop" /> </a> <!-- If the post has a short decription --> <ss:logic:if test="$post['post_content_short']"> <span class="bannerText"><p>[? $post['post_content_short'] ?]<br /><a href="[? $post['post_content_url'] ?]">Read more</a></p></span> </ss:logic:if> </ss:logic:if> <!-- Otherwise, if the post does not have a linked page --> <ss:logic:else> <ss:standard:image alt="[? $post['post_title'] ?]" src="[? $post['post_icon'] ?]" width="780px" height="339px" maintainaspect="crop" /> <!-- If the post has a short decription --> <ss:logic:if test="$post['post_content_short']"> <span class="bannerText"><p>[? $post['post_content_short'] ?]<br /><a href="[? $post['post_content_url'] ?]">Read more</a></p></span> </ss:logic:if> </ss:logic:else> </li> </ss:data:repeater> </ul> </ss:layout:rotator> <span class="leftArrow"><a href="#" id="featured_rotator_previous"><img src="/media/website_designs/1/icn-arrow-left.png" alt="navigator" /></a></span> <span class="rightArrow"><a href="#" id="featured_rotator_next"><img src="/media/website_designs/1/icn-arrow-right.png" alt="navigator" /></a></span> </div>

Explaining The Code

• Line 2: The opening of the <ss:layout:rotator> tag. The rotator has been given the id "featured_rotator". The startatrandom attribute is set to false, so this rotator will display the content in the order it is given, rather than randomly. The id of the next and previous buttons has been defined, it's good practise to use the format "rotatorId_rotator_direction" for the id's of the next and previous elements.
• Line 4: The opening of the <ss:data:repeater> tag. Everything between lines 4 and 15 is repeated for every element returned by the datasource attribute of this tag. In this example the data source attribute is a call to the function getAllForCategory(2). This number represents the post category Id.
• Lines 6: The opening of a <logic:if> tag. The contents of this tag will only apply if the test attribute of this tag is true. In this case, the test is to determine whether the post is linked to a page.
• Line 11: The opening of a <logic:else> tag. If the previous <logic:if> tag fails, the content included in this tag will apply.
• Lines 18 -19 : The elements used to change between rotator slides. Any click-able element can be used to change images, in this example the two <a> tags have been given the IDs relevant to the next and previous buttons (defined as moveNextId and movePreviousId on line 2).

Managing The Slider

The code for displaying the slider basically states "Display all posts which have the category of featured". You can add a new slider image by taking the following steps:

1. Navigate to the "posts" section of the admin panel by clicking the button labelled "posts" in the left-hand sidebar of the Oncord admin panel.
2. Click the "New post" button.
3. Enter a post title, it won't be displayed on the public site, however in order to keep data organized it's a good idea to name the post appropriately.
4. Set the post primary category to the category which is used for displaying the banner images.
5. Click "choose image" to choose an image for use on the slider. Ensure that the banner image is the same size as defined by your web designer. If it's not exact the website will crop the image to size.
6. The post teaser/ short description not relevant to banner posts.
7. Select a page to link the banner image to, or select "No link".
8. Save the post.