blog documentation FAQ followers forum marketplace services youtube

{jrCore_list}

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

Table of Contents:


Overview
What is {jrCore_list}
Using {jrCore_list} in a template
Search Wildcards
Function {jrCore_list}
Pagination
Order_by
Search Conditions
Order_by order with multiple factors
group_by
Searching with OR
quota_check=false
Performance Tips
Debugging: fdebug=true

  • 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"}
  • 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

  • {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.

  • 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 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" ... }

  • 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.

  • 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

Tags