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

HowTo: Using jrCore_list in a template - step-by-step

The Jamroom Network » Documentation » Skin Design Guide » HowTo: Using jrCore_list in a template - step-by-step

overview

The jrCore_list function is for getting lists of stuff.

This is a step by step to get familiar with that function, its useful.
Our Example

The example call we will be using is listed below. Its is asking for "Get me a list of profiles that are active. Use the file index_list_profiles.tpl in the skins directory to format the list. make sure there are only 5 profiles and only get one's with an image. I want them ordered with the latest created ones at the top."
```
{jrCore_list module="jrProfile" order_by="_created desc" search1="profile_active = 1" template="index_list_profiles.tpl" limit="5" require_image="profile_image"}
```
jrCore_list

The first call is
```
jrCore_list
```
which is the function we are calling. Its action will be to generate a list when executed.

Next we tell Jamroom where to look for the list. Since our goal here is to list 5 new active profiles we need use the jrProfile module. We have to tell Jamroom to look in the modules/jrProfile for profiles. So we type
```
module="jrProfile"
```
We would like to list the returned result to show only 5 of the newest profiles.

So we tell Jamroom to "order_by" and since we want it to list the newest 5 we need it "_created desc" which stands for created descending. Consider order_by, search1, limit and require_image like filters.

So far the code should look like this:
```
{jrCore_list module="jrProfile" order_by="_created desc"
```
ok from here we will call our search. We could call multiple searches "search1 = something", "search2 = otherthing", "search3 = goats" etc. But to keep it simple we will just use one.
```
search1="profile_active = 1"
```
The left hand side of search1="profile_active = 1" is profile_active.

You can use any of the other profile_something fields that exist in the datastore. Use the datastore browser to see the available field names.
so far we have requested that Jamroom returns to us with a list; The jrCore_list is called and directed to the module jrProfiles expecting a return with the newest created descending but we want to make sure the profile is active. So we include "profile_active = 1".

Congratulations, now the list filters out only profiles that are currently active on Jamroom.

Now that we have the data we need to direct traffic here for a moment and tell Jamroom what to do with this list we have. So next we will be including the location of our .tpl file which processes the returned list.
```
template="index_list_profiles.tpl"
```
Great! Currently the result will return all profiles that are active. We only want to see the last 5. So to achieve that you will have to tell Jamroom to limit the results
you do that by adding a limit filter.
```
limit="5"
```
Now only 5 profiles will be returned.

And last we also want to require the returned results to have a picture. so we will add this filter here.
```
require_image="profile_image"
```

That's it! The jrCore_list Function broken down as Jamroom reads it.

Your final code should look like this:

{jrCore_list module="jrProfile" order_by="_created desc" search1="profile_active = 1" template="index_list_profiles.tpl" limit="5" require_image="profile_image"}

The Process

Lets discuss how this process works first to better understand whats going on here.

First we created a jrCore_List which is located below:

{jrCore_list module="jrProfile" order_by="_created desc" search1="profile_active = 1" template="index_list_profiles.tpl" limit="5" require_image="profile_image"}

This filtered out all of our profiles to 5 of the newest ones.

also this data was told to be sent to the template "index_list_profiles.tpl" inside you skin directory.

Its important to note that all the template .tpl files are always located in the root directory of your skin directory.

Time to get started with index_list_profiles.tpl

Ok now lets look at the first bit of code inside of index_list_profiles.tpl

{if isset($_items)}
  {foreach $_items as $item}
  <div style="display:table">
      <div style="display:table-cell">
          <a href="{$jamroom_url}/{$item.profile_url}">{jrCore_module_function function="jrImage_display" module="jrProfile" type="profile_image" item_id=$item._profile_id size="small" crop="auto" alt=$item.profile_name title=$item.profile_name class="iloutline"}</a>
      </div>
      <div class="p5" style="display:table-cell;vertical-align:middle">
          <a href="{$jamroom_url}/{$item.profile_url}" class="media_title">{$item.profile_name}</a>
      </div>
  </div>
  {/foreach}
{if $info.total_pages > 1 && $info.page == 1}

One thing to note is everything we stored from our jrCore_List is getting saved inside $_items.

So for our first line of code we need to check and make sure if we are on this page with data to list otherwise "else" next step.

{If isset($_items)} is saying if the data has been set go forward with the code. If no data was set for ($_items) "else" next step.

moving forward here, our next line is {foreach $_items as $item}

Now this line of code will create an item for each of your $_items and $item is setting to display the data from $_items in rows.

Its important to remember that each $_item returned should have been returned with all of the data fields you filtered and asked Jamroom to bring you.

In our case we asked for 5 of the newest profiles with a picture descending.

so with out the actual pictures and to keep this simple I will use words to represent the pictures representing our data example.

Our results would look something like for $_items.
```
row 1)John,  (Johns picture)
```
```
row 2) Adam,  (Adams Picture)
```
```
row 3) Jessica, (Jessicas Picture)
```
```
row 4) Erica, (Ericas Picture)
```
```
row 5) Candice, (Candice Picture)
```
This is the data you have just passed to $_items. where john representing #1 would be you newest jrProfile and they are descending in that order.

The next lines are some ways to display the rows and data
```
<div style="display:table">
      <div style="display:table-cell">
```

This div style "display:table" added to your div tag will Let the element behave like a element.

and "display:table-cell" will Let the element behave like a element.

Now we can insert this data to the table.

we do that with a simple line of code.

<a href="{$jamroom_url}/{$item.profile_url}">{jrCore_module_function function="jrImage_display" module="jrProfile" type="profile_image" item_id=$item._profile_id size="small" crop="auto" alt=$item.profile_name title=$item.profile_name class="iloutline"}</a>

To break down this code as simple as possible it reads back almost exactly as it looks.

So We will use John for this example and it would read like this.
```
<a href="{$jamroom_url}/{$item.profile_url}">
```
A clickable link => {Jamroom Site Directory} / {Profile Url} /

which translates to => http: //www yoursite com/john/

Next we need to bring in the picture. There could be many pictures with johns profile. We need to be clear on what we are asking Jamroom here.

so we are going to use a function to bring the correct picture to this row

Now we are going to call a function. ==> {jrCore_module_function

And ask the function to be displayable ==> function="jrImage_display"

We are using the module jrProfile ==> module="jrProfile"

and we are asking for the type to be profile image ==> type="profile_image

we are taking the item_id which is equal to this ==> item_id=$item._profile_id

and the remainder are some extra parameter that can be passed in ==>

size="small" crop="auto" alt=$item.profile_name title=$item.profile_name class="iloutline"}

so the entire code looks like this
```
{jrCore_module_function function="jrImage_display" module="jrProfile" type="profile_image" item_id=$item._profile_id size="small" crop="auto" alt=$item.profile_name title=$item.profile_name class="iloutline"}</a>
```

next you will see a closing /div and
a couple lines

<div class="p5" style="display:table-cell;vertical-align:middle">
          <a href="{$jamroom_url}/{$item.profile_url}" class="media_title">{$item.profile_name}</a>
</div>

which are displaying the Jamroom profile name in a clickable link.
Notice it says $item.profile_url and $item.profile_name

These are important to note as they are referring to the individual row we are currently working through.

and last but not least you see the old famous /foreach

The script will go back to step 1 and loop this process foreach $_items in your jrCore_List.

Since we limited our search to 5 it will repeat this process foreach $_items and create a table row of 5 data entries of your newest jrProfiles.

The rest of the code listed below the /foreach controls the pages which we will cover next.

NOTE: one important thing to note whats going on here is this page does not display the content it has just generated. It processes all requests and sends them back to the previous page that called this file.

So it has only generated the tables and rows with our data. populated them and sends the data back before you ever knew it left. If this concept is new to you please refer to this link for reference

MVC "Module View Controller"
http://php-html.net/tutorials/model-view-controller-in-php/

Jamroom is a powerful tool and you can take this concept and build on it to endless possibilities.
This HowTo has been brought to you by @b360 .

HowTo: Change the way a list item looks in a skin

Skin Design Guide

Jamroom User Manual

HowTo: Using jrCore_list in a template - step-by-step

Table of Contents:

overview

Our Example

jrCore_list

The Process

Time to get started with index_list_profiles.tpl

Tags