blog documentation FAQ followers forum marketplace services youtube

Annika Live Wall

The Jamroom Network » Documentation » Modules » Annika Live Wall

Table of Contents:


Description
How It Works
Usage - jrAnnika_live_wall
Function jrAnnika_live_wall
simple example
Usage - jrAnnika_encode
Advanced Usage

  • Description

    A module for creating 'Live Walls' on your Jamroom site pages.

    A Live Wall is an area of the page that is updated at regular intervals with 'latest content'. As with all other aspects of Jamroom sites, content that is updated into a Live Wall is created from templates so pretty well anything can be listed. The most common use of a Live Wall is likely to be activities on a profile home page where the current static list of activities is replaced by a dynamic Live Wall, updated every 10 seconds, say, so that users can stay right up to date with what the profiles they are following are up to. Alternatively, a smaller activity live wall could be placed in a sidebar so that this information is available on whatever site page a user is looking at.

    Annika is classed as an advanced Jamroom module in that it requires template modifications and understanding of its principles in order to integrate it into a Jamroom site. However, the module does include sample templates that can be used 'out of the box' or as sample templates to start your own customisation from.

    Documentation with example code snippets below.

  • How It Works

    Annika launches a javascript within your browser that loops every second. When it hits the specified update rate it initiates an ajax call to get the latest template content. This content is then compared with the previous wall content and if different, the live wall is updated.
    There is also a timeout value (in minutes) that when reached causes a timeout message to be placed on the wall and all further updates then cease.

  • Usage - jrAnnika_live_wall

    An activity wall can be created on a Jamroom page by inserting the following smarty call (below) into a template.

    The three parameters, target, template and tpl_dir are required for any jrAnnika_live_wall call. 'target' is the ID of the div tag into which content is updated so needs to be unique if more than one live wall is on a single page. 'template' is the name of the template that creates the wall content and 'tpl_dir' is the location of that template, be it in a module or a skin.

    So the example below is creating a livewall using the annika_module_item_list.tpl template that comes with the Annika module. Note the additional parameter 'module' which is set to 'jrAction'. All parameter values in the call are passed through to the template for parsing. The annika_module_item_list.tpl template is a general purpose listing template that uses that parameter to list the latest items of the specified module, so 'module' could also be set to jrAudio, jrVideo, jrComment, jrLike etc. to get the required listing. 
    {jrAnnika_live_wall target="activity_wall" template="annika_module_item_list.tpl" tpl_dir="jrAnnika" module="jrAction"}
  • Another template included with Annika is annika_profile_timeline.tpl. This can be used on profile pages to replace the default static timeline. See below for how it is called. Note that in this case, the profile_id parameter needs to be passed through to the template so that only activities pertaining to that profile are displayed. 
    {jrAnnika_live_wall target="ptimeline" template="annika_profile_timeline.tpl" tpl_dir="jrAnnika" profile_id=$_profile_id}
  • Other templates included with Annika are annika_likes.tpl and annika_profile_mentions.tpl. Take a look at all these templates to get an idea of how they, and Annika works and to see how to create your own Live Wall templates.

    When doing so, you'll probably notice that the templates have pagination that is using another Annika smarty call - jrAnnika_encode. This is explained below.

  • jrAnnika_live_wall

    Function
    jrAnnika_live_wall
    parameter
    type
    default
    required
    description
    target
    string
    -
    on
    a unique name for the section that will be created (the live div will have this as is id="name")
    template
    string
    -
    on
    the .tpl file which will be parsed and checked every few seconds
    tpl_dir
    string
    -
    off
    the name of the module where the template can be found. eg 'jrAnnika'
    ?????
    ????
    -
    off
    an optional parameter to be passed to the template
    ?????
    ?????
    -
    off
    an optional parameter to be passed to the template

  • simple example

    The code below would create a div with an id of 'activity_wall' and would check every 10 seconds to see if the template has changed or not.

    Because the contents of the template a list of action items in 'Newest at the Top' order, when refresh happens any new items will show on the list. 
    {capture assign="action_template"}
    {literal}
	   {jrCore_list module="jrAction" order_by="_created desc"}
    {/literal}
{/capture}

{jrAnnika_live_wall target="activity_wall" template=$action_template}
  • In the example above we are using {capture} instead of a file, see the '{capture}' link for details.

  • Usage - jrAnnika_encode

    When the javascript that regularly updates a live wall is launched, rate, timeout and template parameters are passed to it. jrAnnika_encode is a method of dynamically updating those parameters upon a site click.

    Take a look at the pagination section of one of the Annika templates and see the code snippet below. jrAnnika_encode is used to assign a parameter that embodies all the other parameters included in the call, i.e.. the new parameter values for the currently looping javascript. This parameter ($eparams) is then used in the jrAnnika_update() script that does the update, so in this example, when the 'next' icon in the live wall is clicked, the next page number is passed through, causing the live wall to be updated with content from the next page. 
    {jrAnnika_encode target=$target template=$template tpl_dir=$tpl_dir module=$module p=$np assign="eparams"}
<a onclick="jrAnnika_update('{$target}', '', '', '{$eparams}');">{jrCore_icon icon="next"}</a>
  • The jrAnnika_update() script has four arguments -

    jrAnnika_update(target, timeout, rate, encoded_params)

    If 'timeout' and 'rate' are empty, as in the above example, they are unchanged, otherwise the timeout and rate values can be dynamically updated. This mechanism actually opens up a lot more possibilities for the use of the Annika module.

  • Advanced Usage

    Take a look at the code snippet below. Its a 'Members' link and two Live Walls.
    The primary live wall on the left by default will show latest site activities whilst the secondary live wall on the right shows the content of the site_news.tpl template, which might be a specific admin blog. The primary live wall will use the default update rate of 10 seconds and timout of 10 minutes (set in the Annika module global config tab) and the secondary live wall will have an update rate of 10 minutes and a timeout of one hour.

    The Member link, when clicked, will invoke two jrAnnika_update calls that change the parameters of the two running scripts that are updating the live walls. The updated parameters are set in the two jrAnnika_encode calls prior to the link. Study them and see that the primary live wall will now list latest profiles (with an update rate of 60 seconds and timeout of one hour) and the secondary live wall now shows the latest site activities (with the default update rate and timeout). 
    {jrAnnika_encode target="plw" template="annika_module_item_list.tpl" tpl_dir="jrAnnika" module="jrProfile" assign="plwparams"}
{jrAnnika_encode target="slw" template="annika_module_item_list.tpl" tpl_dir="jrAnnika" module="jrAction" assign="slwparams"}
<a onclick="jrAnnika_update('plw', '60', '60', '{$plwparams}');jrAnnika_update('slw', '10', '10', '{$slwparams}');">Members</a>
<br>
<div class="row">
    {* PRIMARY LIVE WALL *}
    <div class="col8">
        <div class="inner mb8 mr8" style="height:500px;overflow:auto;">
            {jrAnnika_live_wall target="plw" template="annika_module_item_list.tpl" tpl_dir="jrAnnika" module="jrAction"}
        </div>
    </div>
    {* SECONDARY LIVE WALL *}
    <div class="col4 last">
        <div class="inner mb8 mr8" style="height:500px;overflow:auto;">
            {jrAnnika_live_wall target="slw" template="site_news.tpl" tpl_dir="jrElastic" rate=600 timeout=60}
        </div>
    </div>
</div>
  • More links could now be added for audio, video, gallery items, or maybe the menu template could be similarly modified so as to create a single page capable of showing all site content - dynamically - as it happens!!

Tags