.enhanceWithin()

Categories: Methods

.enhanceWithin()Returns: jQuery

Description: Enhance all the children of all elements in the set of matched elements.

This method is responsible for performing all jQuery Mobile enhancement. Given a set of DOM elements it will enhance their children with all the widgets available.

The enhancement is based on each widget's initSelector property. This selector will be used to identify the elements upon which the widget will be instantiated.

You can shield elements and their children from enhancement by adding the attribute data-enhance="false" to an element. This will cause it, and all its children to be ignored by .enhanceWithin(). Unfortunately, checking elements to see whether they are children of an element that has been marked with data-enhance="false" is performance-intensive. Thus, the presence of data-enhance="false" will only be considered if the global flag $.mobile.ignoreContentEnabled is set to true.

Caveat: enhanceWithin does not attempt to resolve issues related to the order in which widgets are enhanced. For example, enhancing filterable widgets before checkboxradio widgets are enhanced can cause the checkboxradio widgets to be displayed incorrectly. If this affects you, then you must ensure that the widgets which need to be enhanced early are instantiated before the rest of the widgets. One possibility for accomplishing this is to instantiate your widgets during the page widget's pagebeforecreate event.

Example:

Injecting new content at runtime and enhancing it with enhanceWithin.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
 
<!doctype html>
<html lang="en">
<head>
  <meta charset="utf-8">
  <meta name="viewport" content="width=device-width, initial-scale=1">
  <title>enhanceWithin demo</title>
  <link rel="stylesheet" href="http://code.jquery.com/mobile/1.4.4/jquery.mobile-1.4.4.min.css">
  <script src="http://code.jquery.com/jquery-1.10.2.min.js"></script>
  <script src="http://code.jquery.com/mobile/1.4.4/jquery.mobile-1.4.4.min.js"></script>
</head>
<body>
 
<script>
$.mobile.document.on( "click", "#insert-content", function() {
  var content =
    "<div>" +
      "<div data-role='collapsible' data-collapsed='false'>" +
        "<h2>Cities</h2>" +
        "<ul data-role='listview'>" +
          "<li><a href='http://en.wikipedia.org/wiki/Sydney'>Sydney</a></li>" +
          "<li><a href='http://en.wikipedia.org/wiki/Yekaterinburg'>Yekaterinburg</a></li>" +
          "<li><a href='http://en.wikipedia.org/wiki/Asuncion'>Asunci&oacute;n</a></li>" +
          "<li><a href='http://en.wikipedia.org/wiki/Liege'>Li&egrave;ge</a></li>" +
          "<li><a href='http://en.wikipedia.org/wiki/Kinshasa'>Kinshasa</a></li>" +
          "<li>" +
            "<div data-role='controlgroup' data-type='horizontal'>" +
              "<a href='#' class='ui-btn ui-shadow ui-corner-all'>Add</a>" +
              "<a href='#' class='ui-btn ui-shadow ui-corner-all'>Remove</a>" +
              "<a href='#' class='ui-btn ui-shadow ui-corner-all'>Edit</a>" +
            "</div>" +
          "</li>" +
        "</ul>" +
      "</div>" +
    "</div>";
 
  $( content ).appendTo( "#page-content" ).enhanceWithin();
});
</script>
<div data-role="header">
  <h2>jQuery Mobile Example</h2>
</div>
<div role="main" class="ui-content" id="page-content">
  <p>Content will be added at runtime when you click the button below.</p>
  <p><a href="#" id="insert-content" class="ui-btn ui-corner-all ui-shadow">Insert</a></p>
</div>
 
</body>
</html>

Demo: