jQuery & jQuery UI Documentation

jQuery & jQuery UI

previous page next page

jQuery Plugin

.tmplItem()

Categories: Plugins > Templates

.tmplItem() Returns: tmplItem

Description: Return the tmplItem data structure for the rendered template that the matched element is part of.

  • version added: 1.4.3.tmplItem()

This documentation topic concerns the jQuery Templates plugin (jquery-tmpl), which can be downloaded from: http://github.com/jquery/jquery-tmpl.

Note: For information about how to render templates, see .tmpl() and jQuery.tmpl().

$(selector).tmplItem() provides access to the rendered template item which the target element of the selector is part of.

See also jQuery.tmplItem().

The return value of tmplItem() is a tmplItem data structure whose fields provide access to:

  • The HTML elements that the template item is made up of (nodes field).
  • The associated data item (data field).
  • The parent template item, if the template is nested (parent field).
  • The template that was used to render the template item (tmpl field).
  • User defined parameters or methods, such as any values that were set on the options map, passed to tmpl() when the template was rendered.

The following example shows how to use .tmplItem() to get information about the rendered template:

var tmplItem = $( selector ).tmplItem();
alert( "Description: " + tmplItem.data.description );

Building Interactive Ajax Applications

.tmplItem() and jQuery.tmplItem() make it easy to use templates in scenarios beyond simple string concatenation and read-only rendering. They let you create fully-fledged interactive client-side Ajax applications in which the code needs to perform actions like the following:

  • Accessing the associated data item.
  • Modifying the data item.
  • Accessing HTML elements that make up the rendered template item.
  • Updating (re-rendering) the template item, with modified data, modified user-defined parameters, or using a different template

Example: Access data and HTML elements for a template item.:

// Get the template item for an element
var tmplItem = $( selector ).tmplItem();

// Get the corresponding data item and HTML nodes
var movieData = tmplItem.data;
var htmlNodes = tmplItem.nodes;

// Modify style
$( htmlNodes ).css( "backgroundColor", color );

// Access data
alert( "'" + movieData.Name + "' was released in "
        + movieData.ReleaseYear + "." );

The following example is from the Master Detail sample, below. It uses .tmplItem() to set selection on the new item that is added to the list:

$("#addBtn").click( function () {
    // Add a new item to the data array
    people.push( { firstName: "first", lastName: "last" } );

    // Render the template with the new data
    renderTemplate( "#peopleList", "#listItemTemplate", people );

    // Find the added template item
    var addedTmplItem = $("#peopleList tr:last").tmplItem();
    
    // Set selection on the added item
    select ( addedTmplItem );
});

Examples:

Example: Access the template item of matched element, to show data and to modify CSS styles on the rendered template. 

<!DOCTYPE html>
<html>
<head>
  <script src="http://code.jquery.com/jquery-latest.min.js"></script>
  <script src="http://ajax.microsoft.com/ajax/jquery.templates/beta1/jquery.tmpl.min.js"></script>
</head>
<body>
  
<tmpl id="movieTemplate" type="text/x-jquery-tmpl">
    <li>
        <b>${Name}</b>
    </li>
</tmpl>

<button id="lastItemBtn">Details of last movie</button>

<ul id="movieList"></ul>

<script>
var movies = [ 
    { Name: "The Red Violin", ReleaseYear: "1998" },
    { Name: "Eyes Wide Shut", ReleaseYear: "1999" },
    { Name: "The Inheritance", ReleaseYear: "1976" }
];
var color = "aqua"; 
/* Render the template with the movies data */
$( "#movieTemplate" ).tmpl( movies )
    .appendTo( "#movieList" );

$( "#lastItemBtn" ).click( function() {
    /* Flip the color */
    color = (color === "aqua" ? "yellow" : "aqua");

    /* Get the data structure for the last
       template item in the list */
    var lastTmplItem = $( "li:last" ).tmplItem();

    /* Get the corresponding data item and HTML nodes */
    var movie = lastTmplItem.data;
    var htmlNodes = lastTmplItem.nodes;

    /* Switch the background color */
    $( htmlNodes ).css( "backgroundColor", color );

    /* Acces the data */
    alert( "'" + movie.Name + "' was released in " + movie.ReleaseYear + "." );
});
</script>

</body>
</html>

Example: Editable master detail view. 

<!DOCTYPE html>
<html>
<head>
  <style>
  table {cursor:pointer;border-collapse:collapse;float:left;clear:both;} 
  table tr {border:1px solid blue;color:blue;height:25px;} 
  table tr:hover {color:red;}
  table, #personDetail > div {border:2px solid blue;width:230px;
                     margin:4px 0 4px 4px;
                     background-color:#f8f8f8;} 
  table td, #personDetail div div {padding:3px;margin:3px;}
  .selected {background-color:yellow;} 
  #personDetail input {float:right;width:125px;} 
  #personDetail {float:left;margin-left:10px;} 
  button {float:left;margin:4px;}
</style>
  <script src="http://code.jquery.com/jquery-latest.min.js"></script>
  <script src="http://ajax.microsoft.com/ajax/jquery.templates/beta1/jquery.tmpl.min.js"></script>
</head>
<body>
  
<tmpl id="listItemTemplate" type="text/x-jquery-tmpl"> 
    <tr><td>
        ${firstName} ${lastName} 
    </td></tr>
</tmpl>

<tmpl id="detailTemplate" type="text/x-jquery-tmpl"> 
    <div>
        <div>First Name: <input name="firstName" value="${firstName}"/></div>
        <div>Last Name: <input name="lastName" value="${lastName}"/></div>
    </div>
</tmpl>

<button id="addBtn">Add a person</button>

<table><tbody id="peopleList"></tbody></table>

<div id="personDetail"></div>

<script>
var people = [
    { firstName: "Peter", lastName: "Jones" },
    { firstName: "Eva", lastName: "Smolinski" }
];

var selectedItem = null;

function renderTemplate( container, template, data ) {
    $( container ).empty();
    $( template ).tmpl( data ).appendTo( container );
}

/* Render the list */
renderTemplate( "#peopleList", "#listItemTemplate", people );

function select( tmplItem ) {
    if ( selectedItem ) {
        $( selectedItem.nodes ).removeClass( "selected");
    }
    $( tmplItem.nodes ).addClass( "selected");
    selectedItem = tmplItem;

    /* Render the detail view for this data item */
    renderTemplate( "#personDetail", "#detailTemplate", tmplItem.data );
}

$("#addBtn").click( function () {
    /* Add a new item to the data array */
    people.push( { firstName: "first", lastName: "last" } );

    /* Render the template with the new data */
    renderTemplate( "#peopleList", "#listItemTemplate", people );

    /* Find the added template item */
    var addedTmplItem = $("#peopleList tr:last").tmplItem();
    
    /* Set selection on the added item */
    select ( addedTmplItem );
});

$("#peopleList")
    .delegate( "tr", "click", function () {
        /* Set selection on the clicked item */
        select ( $.tmplItem(this) );
    });

$("#personDetail")
    .delegate( "input", "change", function () {
        /* Set the data to the modified value */
        $.tmplItem(this).data[ this.name ] = this.value;
        
        /* Render the list, to show the updated data */ 
        renderTemplate( "#peopleList", "#listItemTemplate", people );
    });
</script>

</body>
</html>
previous page start next page