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

{jrCore_list}

The Jamroom Network » Documentation » Module Developer Guide » {jrCore_list}

Overview

The {jrCore_list} function is used to create lists of the data in a module that stores it's data in a DataStore. It is the "Swiss army knife" of template functions for when you want to create lists of items.

For example:

* When you want a list of all audio items...
* When you want a list of all profiles...
* When you want a list of all YouTube videos in the "cats" category...
* When you want a list of the newest blog posts...

{jrCore_list} is what you will use.
What is {jrCore_list}

The {jrCore_list} function is the search function used to retrieve any data that is stored in a module DataStore.
The Jamroom core provides a feature for modules called a DataStore. A DataStore is a key -> value storage system that allows module developers to store data without having to create a database schema, or know what kind of information will be stored ahead of time. This type of database system is often called a document database.
Using {jrCore_list} in a template

When you want to retrieve something from the database, you can use any number of parameters to define what you are looking for.

Looking through the existing Jamroom skins will bring up lots of examples of possible parameters that could be used.

Here is an example of the {jrCore_list} function searching for:

"All the profiles who have the profile_active setting set to true. Get 5 of them that have an image and use the contents of the file index_list_profiles.tpl for instructions on how to lay the data out. Order them by the time when the profile was created, I want the 5 newest profiles."
```
{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}

Function

{jrCore_list}

parameter

type

default

required

description

module

string

-

on

The name of the module who's datastore you want to search. eg: jrAudio, jrVideo, jrVimeo etc...

template

string

item_list.tpl

off

The name of the template to be used to format the returned output. It will first look for (skin name)_item_list.tpl if none is defined, then module templates dir /item_list.tpl. If these don't exist then '404 not found'.

search#

string

-

off

Add a Search Condition (up to 25) - format is "(key) (option) (value)". eg: "_item_id = 15" or "audio_genre like rock"." Name additional search params sequentially - i.e. "search1", "search2", etc.

order_by

string

_item_id asc

off

an order to return the items in. eg for blogs, by the blog date "order_by blog_date asc". Valid values for the order direction are "asc" (ascending), "desc" (descending), "numerical_asc" (numerical ascending), "numerical_desc" (numerical descending) or "random" for random ordering.

group_by

string

n/a

off

If you wish to group your items by one of the item keys. eg: "List all the songs from the 'rock' genre and group by audio_album_url" to get all the rock albums, but no duplicates.

page

int

n/a

off

If you are using the 'pagebreak' functionality, then page is the number of the page you are on.

pagebreak

int

n/a

off

how many items you want to show on a page. Note: can not be used in conjunction with the limit functionality, its either/or.

limit

int

10

off

How many items you want to show. limit=5 will show only the first 5 items even if there are 10 items found.

return_keys

string

n/a

off

if you just want a specific array of keys. enter the item key you want to be returned. eg: return_keys="_item_id" (see gallery example below.)

???

???

n/a

off

anything you pass in as a parameter will be returned in the template. eg: pink_elephant="hello world" will output "hello world" if you use {$_params.pink_elephant} in the template.

assign

string

n/a

off

the name of a variable to assign the returned value to. eg assign="somthing". You then can use {$somthing} to output the result later in the template, or pass it to another function.

pager

bool

true

off

If we have been given a template, the pager="true" will use list_pager.tpl to handle pagination unless pager_template="something.tpl" is set too.

pager_template

string

n/a

off

If you pass in a pager_template="sometemplate.tpl" then that will be looked for in the active skins directory.

profile_id

int

n/a

off

passing in a profile_id or a _profile_id will limit the returned results to those owned by that profile id

assign

string

n/a

off

assign the returned results to a variable so they can be used later in the template

no_cache

bool

false

off

Set the "no_cache" parameter to true and caching will be disabled on the request. Note: If the {jrCore_list} call is embedded into another template, the outer template may be cached in which case the no_cache parameter will appear to not function!

return_count

bool

false

off

If the return_count parameter is set to TRUE, then only the count of matching items will be returned

cache_seconds

int

n/a

off

You can override the length of time the list will be cached by passing in a valid cache_seconds. Default is the core Cache Seconds length as configured in the Global Config.

privacy_check

bool

true

off

set to 'false' if you wish to include items from profiles that are private in the results

skip_triggers

bool

false

off

set to 'true' if you wish to skip the module event listener part of the search cycle that allows other modules to extend the results. eg: normally when a profile is retrieved, the user info and the quota info is included in the results. With skip_triggers="true" then only the profile info stored in the profile datastore would be returned. Useful for making large queries quicker.

ignore_pending

bool

false

off

set to 'true' if you want to include results that are currently in the pending approval queue in the search results

ignore_missing

bool

false

off

set to 'true' to exclude datastore items that are missing any key used in a negative search condition. By default if you use a negative search condition (such as !=) items that are missing the key being searched are candidates for being included in the result set. Setting this to 'true' will exclude those items and prevent a sub query - this can dramatically increase search performance on large datastores.

quota_check

bool

true

off

set this to 'false' if you want to include results from users who have results but are not in a quota that is allowed to use the module.
You are only limited in search options by what is available in the datastore New fields can be added to the datastore with the FORM DESIGNER so take a look at the datastore browser for the module to see all the possible search fields.
Example of return_keys:
{jrCore_list module="jrGallery" search1="gallery_title_url = `$item.gallery_title_url`" template="null" order_by="gallery_order numerical_asc" return_keys="_item_id" limit="3" assign="image_keys"}
Three items keys are retrieved so they can be used to create a stacked image in another function. See jrSage/galleries_row.tpl for more details.
If you need to search for a key that does not exist, or is set to zero, you can use this syntax:
```
{jrCore_list module="jrAudio" search="audio_file_item_price not_like %_%"}
```
Here we use the "not_like" operator to only find audio items who have an audio_file_item_price key with a value longer than 1 character.

Reference: https://www.jamroom.net/the-jamroom-network/forum/using-jamroom/8768/a-page-specifically-for-free-audio-downloads
Search Wildcards

When you search using a LIKE query, you have these wildcards to use:

% - any number of characters
_ - any single character

So this will get "any profile name beginning with 'tob' "
```
search1="profile_name LIKE tob%"
```
and would return

tobas
tobbo
tobmasen
tob j

Where as this would get any profile name beginning with 'tob' and followed by 2 other characters
```
search1="profile_name LIKE tob__"
```
and would return

tobas
tobbo
tob j

This would return any 5 letter profile name that has an 'm' in the middle:
```
search1="profile_name LIKE __m__"
```
and would return

admin
tim b
tammy
james
Pagination

If you want to add pagination to your list of items, include the pagebreak=(number) parameter in the function call - this will create pages with the number of items on them.

If you want to include a pager at the bottom of your list, then add pager=true as well. The pager is what provides the previous and next page elements so the user can click to move between the resulting pages of your list.

For example:
```
{jrCore_list module="jrYouTube" template="list_youtube.tpl" pagebreak="20" pager=true}  
```
Order_by

You can order by any of the fields that the module contains. To understand what fields the module contains, you can use the 'datastore browser' in the TOOLS section of that module to see all the available fields.
screenshot of the DATASTORE BROWSER button in the TOOLS section of the audio module.
When you open the Datastore Browser you will see each of the individual items and their ID.

In the 'Info' section on the left hand side you will see all of the options that are available to use in the order_by or search sections.

These are the keys you use to order_by.
screenshot of available keys to use (from the audio module) in order_by or search1 or other parameter.
There are also some "hidden" keys that don't show up in the Datastore browser, but will be visible if you ever browser the database tables directly. These keys are system level keys and all begin with an underscore (_):

_created
_updated
_user_id
_item_id
_profile_id

Do not change the value of system level keys unless you know what you are doing.

The syntax for order_by is:

order_by="key_name order_direction"

For example:

order_by="_profile_id numerical_desc"
order_by="audio_album desc"
order_by="audio_title asc"

The difference between 'asc' and 'numerical_asc' is that asc is the order of A~Z (lexicographical ordering) while numerical_asc is the order from 1 to 9 (numerical ordering).

If you order numerical items "asc" you will get this order:
1
11
113
2
3
34
4
5

desc means 'descending'
asc means 'ascending'
Search Conditions

These following Search Conditions can used in the search parameter.

= equal to
!= not equal to
> greater than
>= greater than or equal to
< less than
<= less than or equal to
like contains string
not_like does not contain string
in contains value found in list
not_in does not contain value found in list
regex perform a regular expression search (advanced)
between between one number and another
not_between between one number and another

Some examples of we were searching the Audio module DataStore for audio_title:
```
search="audio_title = something"
search="audio_title != something"
search="audio_title > 0"
search="audio_title >= 1"
search="audio_title < 500"
search="audio_title <= 501"
search="audio_title like %something%"
search="audio_title not_like %excluded%"
search="audio_title in title one,title two,title three"
search="audio_title not_in title one,title two,title three"
search="audio_title regexp [i]expression[/i]"
search="user_age between 5,20"
search="user_age not_between 5,20"
```
Some conversation about using REGEX in jrCore_list calls can be found the forums here:
https://www.jamroom.net/the-jamroom-network/forum/design-and-skin-customization/12724/jrcore-list-search

Documentation on constructing REGEX queries can be found here:
http://dev.mysql.com/doc/refman/5.1/en/regexp.html#operator_regexp
Order_by order with multiple factors

The ratings module now has support for a special "order_by" parameter:
order_by="bayesian_rating desc"

This will order the ratings based on a special "weighted" Bayesian method that will take several factors into account when doing the ranking, so it should rank items with a lot of votes higher than a highly rated item with a single vote - basically it will even things out.
The jrRating module docs page is here:
http://www.jamroom.net/the-jamroom-network/documentation/modules/287/jrrating
The multiple facets question came up in the forums here:

"jrCore_list order with multiple factors"
https://www.jamroom.net/the-jamroom-network/forum/using-jamroom/12819/jrcore-list-order-with-multiple-facters
group_by

From 5.2.10 there is a new UNIQUE parameter available in the group_by parameter.

If you wish to have only one of any single item in the list, you can use:
```
group_by="_profile_id UNIQUE"
```
eg:
```
{jrCore_list module="jrBlog" group_by="blog_category_url UNIQUE" ... }
```
UNIQUE was first discussed in the forums here:
https://www.jamroom.net/the-jamroom-network/forum/using-jamroom/13963/revisiting-blogs
Searching with OR

By default when you add extra search parameters to your {jrCore_list} call, they will be treated as AND queries.

search1="user_instrument = guitar"
search2="user_instrument = drums"

will search for "WHERE user instrument is drums and user instrument is guitar".

If you want to search for OR, then use this syntax
```
search1="user_instrument = guitar || user_instrument = drums"
```
quota_check=false

If you add quota_check=false to your jrCore_list call as an argument, it will skip the check to see if the profile the module is in is allowed to return results.

Example, if a user was in a quota that was allowed to create items at one point in time, then that user was changed to a different quota, the created items still exist in the datastore. If you want these items to be included in the list you are generating, add quota_check=false and they will be included.
Check out this HowTo: Using jrCore_list in a template - step-by-step
Performance Tips

When using the {jrCore_list} function data is being retrieved from the database. These are some tips to make that process faster if you find you're wanting to optimize.

* limit=10 and pagebreak=10 seam to do exactly the same thing, but pagebreak will be slower, so if you're not including the pager, use limit instead.

* order_by="_item_id ???" is the fastest order by parameter because of the way its setup in the database, any of the other orders will be slower, e.g. order_by="audio_title ???".

* order_by="??? random" is very slow when compared to any other order (even on the _item_id : order_by="_item_id random" )

* 'simplepagebreak' works the same as 'pagebreak' but you will not get the "count" query returned so you wont get the total number of pages. So use 'simplepagebreak' in cases where you want pagination, but do not want the "jumper" to allow the user to jump to any page in the result set.

* COUNT queries are always the slowest.
Some thought has to be put into what you're searching. The bigger and busier the site is, the less search conditions you want to use on datastores.

You get 1 search condition "for free" - each additional search causes a JOIN to be added to the query, and the larger the datastore the more expensive that JOIN becomes.

So if the site is fairly busy, ideally only have 1 search condition for the best performance.
Debugging: fdebug=true

This is for developers trying to figure out where problems may be at in a {jrCore_list} call. If you're just not getting the results you're expecting and need to figure out why you can add:
```
fdebug=true
```
to the call to get output of the actual SQL request made dumped into the DEBUG log found at
ACP -> ACTIVITY LOG -> DEBUG LOG.

This query can then be run in an SQL connection system to help understand what is going wrong.
```
{jrCore_list .............  fdebug=true}
```
screenshot of the debug log output from a jrCore_list call with fdebug=true in it

Template Functions

Module Developer Guide

{jrCore_file_type_image}

{jrCore_list}

Table of Contents:

Overview

What is {jrCore_list}

Using {jrCore_list} in a template

{jrCore_list}

Search Wildcards

Pagination

Order_by

Search Conditions

Order_by order with multiple factors

group_by

Searching with OR

quota_check=false

Performance Tips

Debugging: fdebug=true

Tags