Looks like you've got JavaScript disabled in your browser - you'll get a better site experience if you enable JavaScript

How To Use Scrollintoview In Your Module (or skin)

Ultrajam » Documentation » Code » How To Use Scrollintoview In Your Module (or skin)

Using Scrollintoview

Scrollintoview is a scrolling query plugin which is used on jamroom.net. It does animated scrolling to any element - you click a link and scroll smoothly down to that item in the list. You can see it in action on a long forum thread here on jamroom.net - click the back to top button and you will see an animated scroll back to the top of the page. It is very easy to use and adds a nice bit of motion enhancement to your page.

Scrollintoview is an MIT licensed javascript by Robert Koritnik.
You can find it on github: https://github.com/litera/jquery-scrollintoview

Jamroom lists a lot of items. In the stock skins the lists are all relatively short (with pagination), and each item is not very high. But imagine a custom site where there may be lists of hundreds of tiny items, or 10 items where each item is several hundred pixels in height = lots of scrolling for your users.

Under such circumstances Scrollintoview would be one of the (many) ways of improving the user's experience of your long page.

So let's do that.
The jrCore_list Function

As you know, jrCore_list uses a template to display a list. For our example we are going to list 5 tall profiles with style="height:500px;" just as a placeholder for now.

The list function would be placed in a template where you want it to appear and will look something like this:
```
{jrCore_list module="jrProfile" order_by="_created desc" limit="5" search1="_profile_id in `$_conf.myModule_profile_ids`" template="very_tall_profile_list.tpl"}
```

The List Template

jrCore_list parses the very_tall_profile_list.tpl ONCE providing it with an array of all data for each the 5 items. The looping over each item is done within the template itself.

Take a look at very_tall_profile_list.tpl which would probably be in the skin directory:

{if isset($_items)} 

  	<ul class="list-inline feature-menu">
	{foreach from=$_items item="item"}
	    <li>
	        <a href="#{$item.myitem_title|jrCore_url_string}">
	            <h3>{$item.myitem_title}</h3>
	        </a>
	    </li>
	{/foreach}
	</ul> 

    {foreach from=$_items item="item"}
    <div class="item" id="{$item.myitem_title|jrCore_url_string}" style="height:800px;">
    	
    	<h1>{$item.myitem_title}</h1>

    </div>
    {/foreach}
    
{/if}

What that template says is "if there is an array called $_items, foreach of the items write a div with the title of the item as that div's id attribute and the title as a h1 header". The inline style tags give it the necessary height for now - the item would really have content to make it that height, or something in the css to make it display with height.

Note the jrCore_url_string smarty modifier used on the item title to make it suitable for use as the item id (there can be no spaces). It is this id that Scrollintoview will use as the target - the place to scroll to: id="{$item.myitem_title|jrCore_url_string}"

The Navigation

We aren't limited to looping through the $_items array so let's add in a list of # links to each item - that gives us something to click to scroll to the item. We can add this just after {if isset($_items)}

  	<ul class="list-inline feature-menu">
	{foreach from=$_items item="item"}
	    <li>
	        <a href="#{$item.myitem_title|jrCore_url_string}" id="{$item.myitem_title|jrCore_url_string}_click">
	            <h3>{$item.myitem_title}</h3>
	        </a>
	    </li>
	{/foreach}
	</ul>

This writes the unordered list that would eventually be styled as a menu, possibly floating, with a link to each item. Click the link and smoothly scroll down or up to the item.

The Javascript

Here is the javascript to work with that html, it should be in a document ready function or similar:

  $(".list-inline.feature-menu a").click(function(e){
    e.preventDefault();
    target = this.getAttribute('href');
    $(target).scrollintoview({ duration: "normal"});
  });

We have a javascript selector, $(".list-inline.feature-menu a") basically a foreach for the list of links in our menu.
It gives each link a click function, so when clicked the target is set to whatever the href is for that link, and then scrollintoview is called in to do it's thing.

That could be placed in the template, just before the end of the $_items foreach loop so it is only written once. Or it could be placed in your module or skin javascript file if you prefer to do it that way. Read on for details.
More About Scrollintoview

Scrollintoview is very simple to use if you stick to the defaults. You can just put this into an onclick attribute for a link.
$("some_selector").scrollintoview();

It isn't much more complicated to override the defaults, and it has a handy callback function:
```
$("some_selector").scrollintoview({
    duration: 2500,
    direction: "vertical",
    complete: function() {
        // highlight the element so user's focus gets where it needs to be

    }
});
```
Of course, in order for this to work we need to include the Scrollintoview javascript in the page. To keep it all in one place I'll just add that into the template and link it to the github script. You would need to add the script to your skin or module's js directory as /myModule/js/jquery.scrollintoview.js and then include it in the module or skin init function:
```
jrCore_register_module_feature('jrCore','javascript','myModule','jquery.scrollintoview.js');
```
Use the unminified script and Jamroom will minify it for you. You would also want to paste the javascript into your skin or module javascript file rather than leaving it in the template.
Add A Back To The Top Button

A button to get back to the top will be useful unless the menu is in a floating panel, so we'll do that in the simplest possible way by adding a button after the tall div, and give the menu an id to use as the target.
```
<button onclick="$('#mymenu').scrollintoview();" />
```

Together At Last

Here it is all together in the completed very_tall_profile_list.tpl. Copy that into your skin or module to try it out.

{if isset($_items)} 

  	<ul class="list-inline feature-menu" id="mymenu">
	{foreach from=$_items item="item"}
	    <li>
	        <a href="#{$item.myitem_title|jrCore_url_string}">
	            <h3>{$item.myitem_title}</h3>
	        </a>
	    </li>
	{/foreach}
	</ul> 

    {foreach from=$_items item="item"}
    <div class="item" id="{$item.myitem_title|jrCore_url_string}" style="height:800px;">
    	
    	<h1>{$item.myitem_title}</h1>

    </div>
    <button type="button" onclick="$('#mymenu').scrollintoview();">Back to top</button>
    {/foreach}

<script type="text/javascript" src="https://raw.github.com/litera/jquery-scrollintoview/master/jquery.scrollintoview.min.js"></script>
<script>
jQuery(document).ready(function() {

  $(".list-inline.feature-menu a").click(function(e){
    e.preventDefault();
    target = this.getAttribute('href');
    $(target).scrollintoview({ duration: "normal"});
  });

});
</script>

{/if}

And that's about it. I hope you've learned something useful, let me know in the comments, and have fun with it.

How to use a modal in a template

Code

How To Hijack A Url (using a module_view_listener)

How To Use Scrollintoview In Your Module (or skin)

Table of Contents:

Using Scrollintoview

The jrCore_list Function

The List Template

The Navigation

The Javascript

More About Scrollintoview

Add A Back To The Top Button

Together At Last

Tags