Popup: Document generated IDs

Author: Gabriel Schulhof

entries/popup.xml

@@ -4,7 +4,7 @@
 	<title>Popup Widget</title>
 	<desc>Opens content in a popup.</desc>
 	<longdesc>
-		<h2>Popups</h2>
+		<h2 id="popups">Popups</h2>
 		<p>To create a popup, add the <code>data-role="popup"</code> attribute to a div with the popup contents. Then create a link with the <code>href</code> set to the <code>id</code> of the popup div, and add the attribute <code>data-rel="popup"</code> to tell the framework to open the popup when the link is tapped. This is a similar markup pattern to the <a href="../dialog/">dialog</a> widget. A popup div has to be nested inside the same page as the link.</p>
 
 <pre><code><![CDATA[
@@ -26,7 +26,7 @@
 		<iframe src="/resources/popup/example2.html" style="width:100%;height:590px;border:0px"></iframe>
 		</p>
 
-		<h2>Scaling images: Lightbox examples</h2>
+		<h2 id="scaling-images-lightbox-examples">Scaling images: Lightbox examples</h2>
 
 		<p>The framework CSS contains rules that make images that are immediate children of the popup scale to fit the screen. Because of the absolute positioning of the popup container and screen, the height is not adjusted to screen height on all browsers. You can prevent vertical scrolling with a simple script that sets the <code>max-height</code> of the image.</p>
 
@@ -47,7 +47,7 @@ $( document ).on( "pagecreate", function() {
 });
 ]]></code></pre>
 
-		<h2>Working with iframes in popups</h2>
+		<h2 id="working-with-iframes-in-popups">Working with iframes in popups</h2>
 
 		<p>You may need to embed an iframe into a popup to use a 3rd party widget. Here, we'll walk through a few real-world examples of working with iframes: videos and maps.</p>
 
@@ -397,6 +397,36 @@ $( document ).on( "pageinit", function() {
 
 		<iframe src="/resources/popup/example13.html" style="width:100%;height:390px;border:0px"></iframe>
 
+	<h2 id="id-generation">ID generation</h2>
+
+	<p>The <placeholder name="name"/> widget adds an ID to the elements it generates. The ID for any given generated element is constructed by suffixing the popup's own ID:</p>
+	<dl>
+		<dt>Placeholder</dt>
+		<dd><code><strong><![CDATA[<popup-id>]]></strong></code>-placeholder</dd>
+		<dt>Screen</dt>
+		<dd><code><strong><![CDATA[<popup-id>]]></strong></code>-screen</dd>
+		<dt>Container</dt>
+		<dd><code><strong><![CDATA[<popup-id>]]></strong></code>-popup</dd>
+	</dl>
+	<p>For example, creating a <placeholder name="name"/> with</p>
+<pre><code><![CDATA[
+<div id="extra-info" data-role="popup">
+	<p>To use this feature, enable it from Settings.</p>
+</div>
+]]></code></pre>
+	<p>will result in the following markup:</p>
+<pre><code><![CDATA[
+	<div id="extra-info-placeholder" style="display: none;">
+		<!-- placeholder for extra-info -->
+	</div>
+	<div id="extra-info-screen" class="ui-screen-hidden ui-popup-screen ui-overlay-inherit"></div>
+	<div id="extra-info-popup" class="ui-popup-container ui-popup-hidden ui-popup-truncate">
+		<div id="extra-info" data-role="popup" class="ui-popup ui-body-inherit ui-overlay-shadow ui-corner-all">
+			<p>To use this feature, enable it from Settings.</p>
+		</div>
+	</div>
+]]></code></pre>
+
 	</longdesc>
 	<added>1.2</added>
 	<options>