.css(): Add new signature for 1.9

kswedberg · kswedberg · commit 23df8d89352a · 2013-01-09T09:56:05.000-05:00
diff --git a/entries/css.xml b/entries/css.xml
@@ -9,14 +9,21 @@
         <desc>A CSS property.</desc>
       </argument>
     </signature>
-    <desc>Get the value of a style property for the first element in the set of matched elements.</desc>
+    <signature>
+      <added>1.9</added>
+      <argument name="propertyNames" type="Array">
+        <desc>An array of one or more CSS properties.</desc>
+      </argument>
+    </signature>
+    <desc>Get the value of style properties for the first element in the set of matched elements.</desc>
     <longdesc>
       <p>The <code>.css()</code> method is a convenient way to get a style property from the first matched element, especially in light of the different ways browsers access most of those properties (the <code>getComputedStyle()</code> method in standards-based browsers versus the <code>currentStyle</code> and <code>runtimeStyle</code> properties in Internet Explorer) and the different terms browsers use for certain properties. For example, Internet Explorer's DOM implementation refers to the <code>float</code> property as <code>styleFloat</code>, while W3C standards-compliant browsers refer to it as <code>cssFloat</code>. For consistency, you can simply use <code>"float"</code>, and jQuery will translate it to the correct value for each browser.</p>
       <p>Also, jQuery can equally interpret the CSS and DOM formatting of multiple-word properties. For example, jQuery understands and returns the correct value for both <code>.css('background-color')</code> and <code>.css('backgroundColor')</code>. Different browsers may return CSS color values that are logically but not textually equal, e.g., #FFF, #ffffff, and rgb(255,255,255).</p>
       <p>Shorthand CSS properties (e.g. margin, background, border) are not supported. For example, if you want to retrieve the rendered margin, use: <code>$(elem).css('marginTop')</code> and <code>$(elem).css('marginRight')</code>, and so on.</p>
+      <p><strong>As of jQuery 1.9</strong>, passing an array of style properties to <code>.css()</code> will result in an object of property-value pairs.</p>
     </longdesc>
     <example>
-      <desc>To access the background color of a clicked div.</desc>
+      <desc>Get the background color of a clicked div.</desc>
       <code><![CDATA[
 $("div").click(function () {
   var color = $(this).css("background-color");
@@ -36,10 +43,42 @@ div { width:60px; height:60px; margin:5px; float:left; }
 <div style="background-color:#123456;"></div>
 <div style="background-color:#f11;"></div>]]></html>
     </example>
+
+    <example>
+      <desc>Get the width, height, text color, and background color of a clicked div.</desc>
+      <code><![CDATA[
+$("div").click(function () {
+  var html = ["The clicked div has the following styles:"];
+
+  var styleProps = $(this).css( ["width", "height", "color", "background-color"] );
+  $.each( styleProps, function( prop, value ) {
+    html.push( prop + ": " + value );
+  });
+
+  $( "#result" ).html( html.join( "<br>" ) );
+});
+
+]]></code>
+      <css><![CDATA[
+div { height: 50px; margin: 5px; padding: 5px; float: left; }
+
+#box1 { width: 50px; color: yellow; background-color: blue; }
+#box2 { width: 80px; color: rgb(255,255,255); background-color: rgb(15,99,30); }
+#box3 { width: 40px; color: #fcc; background-color: #123456; }
+#box4 { width: 70px; background-color: #f11; }
+]]></css>
+      <html><![CDATA[
+<p id="result">&nbsp;</p>
+<div id="box1">1</div>
+<div id="box2">2</div>
+<div id="box3">3</div>
+<div id="box4">4</div>]]></html>
+    </example>
     <category slug="css"/>
     <category slug="manipulation/style-properties"/>
     <category slug="version/1.0"/>
     <category slug="version/1.4"/>
+    <category slug="version/1.9"/>
   </entry>
   <entry type="method" name="css" return="jQuery">
     <signature>
