libs/js/jquery-mobile-1.1.0/docs/toolbars/docs-headers.html

   1 <!DOCTYPE html>
   2 <html>
   3         <head>
   4         <meta charset="utf-8">
   5         <meta name="viewport" content="width=device-width, initial-scale=1">
   6         <title>jQuery Mobile Docs - Header Bars</title>
   7         <link rel="stylesheet"  href="../../css/themes/default/jquery.mobile.css" />
   8         <link rel="stylesheet" href="../_assets/css/jqm-docs.css"/>
   9
  10         <script src="../../js/jquery.js"></script>
  11         <script src="../../docs/_assets/js/jqm-docs.js"></script>
  12         <script src="../../js/"></script>
  13
  14 </head>
  15 <body>
  16
  17         <div data-role="page" class="type-interior">
  18
  19                 <div data-role="header" data-theme="f">
  20                 <h1>Headers</h1>
  21                 <a href="../../" data-icon="home" data-iconpos="notext" data-direction="reverse">Home</a>
  22                 <a href="../nav.html" data-icon="search" data-iconpos="notext" data-rel="dialog" data-transition="fade">Search</a>
  23         </div><!-- /header -->
  24
  25         <div data-role="content">
  26                 <div class="content-primary">
  27                         <h2>Header structure</h2>
  28                         <p>The <code>header</code> is a toolbar at the top of the page that usually contains the page title text and optional buttons positioned to the the left and/or right of the title for navigation or actions. Headers can optionally be positioned as <a href="bars-fixed.html">fixed</a> so they remain at the top of the screen at all times instead of scrolling with the page.</p>
  29
  30                         <p>The title text is normally an H1 heading element but it's possible to use any heading level (H1-H6) to allow for semantic flexibility. For example, a page containing multiple mobile 'pages' may use a H1 element on the home 'page' and a H2 element on the secondary pages. All heading levels are styled identically by default to maintain visual consistency.</p>
  31
  32 <div class="highlight">
  33 <pre>
  34 <span class="nt">&lt;div</span> <strong><span class="na">data-role=</span><span class="s">"header"</span></strong><span class="nt">&gt;</span>
  35         <span class="nt">&lt;h1&gt;</span>Page Title<span class="nt">&lt;/h1&gt;</span>
  36 <span class="nt">&lt;/div&gt;</span>
  37 </pre>
  38 </div>
  39
  40                         <h2>Default header features</h2>
  41                         <p>The <code>header</code> toolbar is themed with the "a" swatch by default (black in the default theme) but you can easily <a href="bars-themes.html">set the theme swatch color</a>.</p>
  42
  43
  44
  45                         <div data-role="header">
  46                                 <h1>Page title</h1>
  47                         </div>
  48
  49
  50                         <h2>Adding buttons</h2>
  51
  52
  53
  54
  55
  56                         <p>In the standard header configuration, there are slots for buttons on either side of the text heading. Each button is typically an <code>anchor</code> element, but any valid <a href="../buttons/buttons-types.html">button markup</a> will work. To save space, buttons in toolbars are set to <a href="../buttons/buttons-inline.html">inline styling</a> so the button is only as wide as the text and icons it contains. </p>
  57
  58
  59
  60
  61                         <h3>Default button positioning</h3>
  62
  63                         <p>The header plugin looks for immediate children of the header container, and automatically sets the first link in the left button slot and the second link in the right. In this example, the 'Cancel' button will appear in the left slot and 'Save' will appear in the right slot based on their sequence in the source order. </p>
  64
  65
  66 <pre><code>
  67 &lt;div data-role=&quot;header&quot; data-position=&quot;inline&quot;&gt;
  68         &lt;a href=&quot;index.html&quot; data-icon=&quot;delete&quot;&gt;Cancel&lt;/a&gt;
  69         &lt;h1&gt;Edit Contact&lt;/h1&gt;
  70         &lt;a href=&quot;index.html&quot; data-icon=&quot;check&quot;&gt;Save&lt;/a&gt;
  71 &lt;/div&gt;
  72 </code></pre>
  73
  74
  75                         <div data-role="header">
  76                                 <a href="index.html" data-icon="delete">Cancel</a>
  77                                 <h1>Edit Contact</h1>
  78                                 <a href="index.html" data-icon="check">Save</a>
  79                         </div>
  80
  81                         <h3>Making buttons visually stand out</h3>
  82
  83                         <p>Buttons automatically adopt the swatch color of the bar they sit in, so a link in a header bar with the "a" color will also be styled as "a" colored buttons. It's simple to make a button visually stand out. Here, we add the <code> data-theme</code> attribute and set the color swatch for the button to "b" to make the "Save" button pop.</p>
  84
  85                         <pre><code>
  86 &lt;div data-role=&quot;header&quot; data-position=&quot;inline&quot;&gt;
  87         &lt;a href=&quot;index.html&quot; data-icon=&quot;delete&quot;&gt;Cancel&lt;/a&gt;
  88         &lt;h1&gt;Edit Contact&lt;/h1&gt;
  89         &lt;a href=&quot;index.html&quot; data-icon=&quot;check&quot; data-theme=&quot;b&quot;&gt;Save&lt;/a&gt;
  90 &lt;/div&gt;
  91 </code></pre>
  92
  93
  94                         <div data-role="header">
  95                                 <a href="index.html" data-icon="delete">Cancel</a>
  96                                 <h1>Edit Contact</h1>
  97                                 <a href="index.html" data-icon="check" data-theme="b">Save</a>
  98                         </div>
  99
 100                         <h3>Controlling button position with classes</h3>
 101
 102                         <p>The button position can also be controlled by adding classes to the button anchors, rather than relying on source order. This is especially useful if you only want a button in the right slot. To specify the button position, add the class of <code>ui-btn-left</code> or <code>ui-btn-right</code> to the anchor.</p>
 103
 104
 105
 106
 107 <div class="highlight">
 108 <pre><code>
 109 &lt;div data-role=&quot;header&quot; data-position=&quot;inline&quot;&gt;
 110         &lt;h1&gt;Page Title&lt;/h1&gt;
 111         &lt;a href=&quot;index.html&quot; data-icon=&quot;gear&quot; class=&quot;ui-btn-right&quot;&gt;Options&lt;/a&gt;
 112 &lt;/div&gt;
 113 </code></pre>
 114 </div>
 115
 116                         <div data-role="header" >
 117                                 <h1>Page Title</h1>
 118                                 <a href="index.html" data-icon="gear" class="ui-btn-right">Options</a>
 119                         </div>
 120
 121
 122                                 <h3>Adding buttons to toolbars without heading</h3>
 123
 124                         <p>The heading in the header bar has some margin that will give the bar its height. If you choose not to use a heading, you will need to add an element with <code>class="ui-title"</code> so that the bar can get the height and display correctly.</p>
 125
 126
 127 <div class="highlight">
 128 <pre><code>
 129 &lt;div data-role=&quot;header&quot; data-position=&quot;inline&quot;&gt;
 130         &lt;a href=&quot;index.html&quot; data-icon=&quot;gear&quot; class=&quot;ui-btn-right&quot;&gt;Options&lt;/a&gt;
 131         &lt;span class=&quot;ui-title&quot; /&gt;
 132 &lt;/div&gt;
 133
 134 </code></pre>
 135 </div>
 136
 137                         <div data-role="header" >
 138                                 <a href="index.html" data-icon="gear" class="ui-btn-right">Options</a>
 139                                 <span class="ui-title" />
 140                         </div>
 141
 142
 143
 144                 <h2>Adding Back buttons</h2>
 145
 146                 <p>jQuery Mobile has a feature to automatically create and append "back" buttons to any header, though it is disabled by default. This is primarily useful in chromeless installed applications, such as those running in a native app webview. The framework automatically generates a "back" button on a header when the page plugin's <code>addBackBtn</code> option is true. This can also be set via markup if the page div has a <code>data-add-back-btn="true"</code> attribute. </p>
 147
 148
 149                 <p>If you use the attribute <code>data-rel="back"</code> on an anchor, any clicks on that anchor will mimic the back button, going back one history entry and ignoring the anchor's default href. This is particularly useful when linking back to a named page, such as a link that says "home", or when generating "back" buttons with JavaScript, such as a button to close a dialog. When using this feature in your source markup, <strong>be sure to provide a meaningful href that actually points to the URL of the referring page. This will allow the feature to work for users in C-Grade browsers.</strong></p>
 150                 <p>If you just want a reverse transition without actually going back in history, you should use the <code>data-direction="reverse"</code> attribute.</p>
 151
 152                 <h2>Customizing the back button text</h2>
 153
 154                 <p>If you'd like to configure the back button text, you can either use the <code>data-back-btn-text="previous"</code> attribute on your page element, or set it programmatically via the page plugin's options: <br /><code>$.mobile.page.prototype.options.backBtnText = "previous";</code></p>
 155
 156                 <h3>Default back button style</h3>
 157                 <p>If you'd like to configure the back button role-theme, you can use: <br /><code>$.mobile.page.prototype.options.backBtnTheme = "a";</code><br />
 158                 If you're doing this programmatically, set this option inside the mobileinit event handler.</p>
 159
 160                         <h2>Custom header configurations</h2>
 161                         <p>If you need to to create a header that doesn't follow the default configuration, simply wrap your custom styled markup in any container, such as <code>div</code>. The plugin won't apply the automatic button logic to the wrapped content inside the header container so you can write custom styles for laying out the content in your header.</p>
 162
 163                         <p>It's also possible to create custom bars without using the header data-role at all. For example, start with any container and add the <code>ui-bar</code> class to apply standard bar padding and add the <code>ui-bar-b</code> class to assign the bar swatch styles from your theme. (The "b" can be any swatch letter.)</p>
 164
 165                         <pre><code>
 166 &lt;div <strong>class=&quot;ui-bar ui-bar-b&quot;</strong>&gt;
 167         &lt;h3&gt;I&#x27;m just a div with bar classes and a &lt;a href=&quot;#&quot; data-role=&quot;button&quot;&gt;Button&lt;/a&gt;&lt;/h3&gt;
 168 &lt;/div&gt;
 169                         </code></pre>
 170
 171                         <p>This will produce this bar:</p>
 172                                 <div class="ui-bar ui-bar-b">
 173                                         <h3>I'm just a div with bar classes and a mini inline <a href="#" data-role="button" data-inline="true" data-mini="true">Button</a></h3>
 174                                 </div>
 175
 176                                 <p>Note that <code>.ui-bar</code> should not be added to header or footer bars that span the full width of the page, as the additional padding will cause a full-width element to break out of its parent container. To add padding inside of a full-width toolbar, wrap the toolbar's contents in an element and apply the padding to that element instead.</p>
 177
 178                                 <p>By writing some simple styles, it's easy to build message bars like this:</p>
 179                                         <!-- Yes, the inline styles aren't recommended in a real system but they are used to simply illustrate how to tweak CSS -->
 180                                         <div class="ui-bar ui-bar-e">
 181
 182                                                 <h3 style="display:inline-block; width:92%; margin-top:5px;">This is an alert message. </h3><div style="display:inline-block; width:8%; margin-top:0px;"><a href="#" data-role="button" data-icon="delete" data-iconpos="notext">Dismiss</a></div><p style="font-size:85%; margin:-.3em 0 1em;">And here's some additional text in a paragraph.</p>
 183                                         </div>
 184                                 </div><!--/content-primary -->
 185
 186                                 <div class="content-secondary">
 187
 188                                         <div data-role="collapsible" data-collapsed="true" data-theme="b" data-content-theme="d">
 189
 190                                                         <h3>More in this section</h3>
 191
 192                                                         <ul data-role="listview" data-theme="c" data-dividertheme="d">
 193
 194                                                                 <li data-role="list-divider">Toolbars</li>
 195                                                                 <li><a href="docs-bars.html">Toolbar basics</a></li>
 196                                                                 <li data-theme="a"><a href="docs-headers.html">Header bars</a></li>
 197                                                                 <li><a href="docs-footers.html">Footer bars</a></li>
 198                                                                 <li><a href="docs-navbar.html">Navbars</a></li>
 199                                                                 <li><a href="bars-fixed.html">Fixed positioning</a></li>
 200                                                                 <li><a href="footer-persist-a.html">Persistent toolbars</a></li>
 201                                                                 <li><a href="bars-themes.html">Theming toolbars</a></li>
 202
 203                                                         </ul>
 204                                         </div>
 205                                 </div>
 206
 207                         </div><!-- /content -->
 208
 209                         <div data-role="footer" class="footer-docs" data-theme="c">
 210                                         <p>&copy; 2011-12 The jQuery Foundation</p>
 211                         </div>
 212
 213                         </div><!-- /page -->
 214
 215                         </body>
 216                         </html>