ultrajam 3rd party developer
Timeline blog documentation followers forum marketplace

How to use Livesearch in your module

Ultrajam » Documentation » Code » How to use Livesearch in your module

Table of Contents:


The live_search form function
The Module View
More than one livesearch in a page
The HTML
Pick it up and run
  • When developing a module, if you need to add a livesearch field to a Jamroom form you will need to know about the live_search field type, which (fortunately) is pretty easy to use if you keep it simple.

    What is livesearch?
    In a form text field, when you type and a dropdown appears, that is livesearch in use.

    Where is livesearch used?
    Example: Admin can see it when creating a new profile, they need to search a username so they type into the form field and narrowing results are shown as they type. Check it out: yourwebsite.com/profile/create

    The JR5 code is very readable, once you find the relevant functions you can just read it and get a pretty good idea as to how things work even if you don’t know much php. But it can take time to trace through and find those functions, so we are going to look at an existing example from jrProfile - the user picker which admin can use to select which user will be the owner of the profile. Hopefully by isolating the relevant parts I can save you some time in getting to grips with livesearch.

  • The live_search form function

    live_search is a field type, provided by the core. If you are developing a module you will already have your form functions, that’s where you will add a livesearch field using jrCore_form_field_create, just like all the other fields in your form.
    In jrProfile/index.php in the form function. 
        // Show User Picker...  (ADMINS ONLY)

    $_tmp = array(
        'name'          => 'profile_user_id', // this is the name of the field in the datastore

        'group'         => 'admin', // only admin users will see this field in the form

        'label'         => 'profile owner', // the text label for the field in the form

        'help'          => 'What User Account should this profile be created for? The User Account selected here will have admin capabilities for the Profile.', // the help text which appears when clicking the ? button

        'type'          => 'live_search', // this is what makes the field in the form display the live search.

        'target'        => "{$_conf['jrCore_base_url']}/{$_post['module_url']}/get_profile_users", // the url to query

        'value'         => $_user['_user_id'], // sends the user_id so you do not see yourself in the search results

        'required'      => false, // is it required or not

        'validate'      => 'number_nz', // check that it is a number greater than zero, return an error if it is not

        'form_designer' => false  // We do not allow the form designer to override this field

    );
    jrCore_form_field_create($_tmp);
  • The 'target' field in the above array is the url called by the livesearch javascript which then expects a response from the server. That response will be an array of user_id’s and user_name’s which is then used to populate the dropdown list of users to choose from. As the user types, fresh queries are sent to the server which returns updated results for the dropdown.

  • The Module View

    The 'target’ url needs a view created for it, which is also in jrProfile/index.php 
    function view_jrProfile_get_profile_users($_post,$_user,$_conf)
{
    jrUser_admin_only();
    $tbl  = jrCore_db_table_name('jrUser','item_key');
    $req  = "SELECT `_item_id`, `value` FROM {$tbl} WHERE `key` = 'user_name' AND `value` LIKE '". jrCore_db_escape($_post['q']) ."%' ORDER BY `value` ASC";
    $_sel = jrCore_db_query($req,'_item_id',false,'value');
    return jrCore_live_search_results('profile_user_id',$_sel);
}
  • If you are writing your own module you can make this a more complicated query, but bear in mind that especially for live search you want a fast and snappy response, so keep it as light as possible. You can see a more complex example in the jrPrivateNote module: view_jrPrivateNote_get_users
  • You will notice that the results are passed between the different livesearch fields. Look into using .empty() to clear the results from #jquery-live-search
  • Because YOURFIELD_livesearch_value (will contain the id) is a hidden field, the change event is not triggered when it's value changes. If you need to do that, trigger the change manually using .change()

  • The HTML

    The key parts that the above php adds to the form html are a text input field and some jquery which uses the liveSearch function. You could recreate the field in a smarty template like this: 
    <input type="text" id="profile_user_id" class="form_text live_search_text" name="profile_user_id" value="search" tabindex="2" onfocus="if($(this).val() == 'search'){ $(this).val('').removeClass('live_search_text'); }">

<script type="text/javascript">
$(document).ready(function(){
try { $('#profile_user_id').liveSearch( { url:'{$_conf['jrCore_base_url']}/{$murl}/get_profile_users/q='}); } catch(e) { };
return true;
});
</script>

  • Pick it up and run

    Of course that only creates a livesearch field, you’d need to create the rest of the form as well if you needed to submit it.

    Note: If you are creating forms in your pages using smarty there is probably a better way of doing it. Check out iframes as a way of bringing forms into your page or modal, Jamroom provides some very useful functions for converting your form view function to work within your page (a form in a modal is particularly easy).

    https://www.jamroom.net/ultrajam/documentation/code/1660/how-to-use-forms-in-a-modal-iframe

Tags