documentation/manual/en/module_specs/Zend_View-Helpers-HeadStyle.xml

   1 <?xml version="1.0" encoding="UTF-8"?>
   2 <!-- Reviewed: no -->
   3 <sect3 id="zend.view.helpers.initial.headstyle">
   4     <title>HeadStyle Helper</title>
   5
   6     <para>
   7         The <acronym>HTML</acronym> <emphasis>&lt;style&gt;</emphasis> element is used to include
   8         <acronym>CSS</acronym> stylesheets inline in the <acronym>HTML</acronym>
   9         <emphasis>&lt;head&gt;</emphasis> element.
  10     </para>
  11
  12     <note>
  13         <title>Use HeadLink to link CSS files</title>
  14
  15         <para>
  16             <link linkend="zend.view.helpers.initial.headlink">HeadLink</link>
  17             should be used to create <emphasis>&lt;link&gt;</emphasis> elements for
  18             including external stylesheets. <classname>HeadStyle</classname> is used when
  19             you wish to define your stylesheets inline.
  20         </para>
  21     </note>
  22
  23     <para>
  24         The <classname>HeadStyle</classname> helper supports the following methods for
  25         setting and adding stylesheet declarations:
  26     </para>
  27
  28     <itemizedlist>
  29         <listitem>
  30             <para>
  31                 <command>appendStyle($content, $attributes = array())</command>
  32             </para>
  33         </listitem>
  34
  35         <listitem>
  36             <para>
  37                 <command>offsetSetStyle($index, $content, $attributes = array())</command>
  38             </para>
  39         </listitem>
  40
  41         <listitem>
  42             <para>
  43                 <command>prependStyle($content, $attributes = array())</command>
  44             </para>
  45         </listitem>
  46
  47         <listitem>
  48             <para>
  49                 <command>setStyle($content, $attributes = array())</command>
  50             </para>
  51         </listitem>
  52     </itemizedlist>
  53
  54     <para>
  55         In all cases, <varname>$content</varname> is the actual <acronym>CSS</acronym> declarations.
  56         <varname>$attributes</varname> are any additional attributes you wish to provide to the
  57         <property>style</property> tag: lang, title, media, or dir are all permissible.
  58     </para>
  59
  60     <note>
  61         <title>Setting Conditional Comments</title>
  62
  63         <para>
  64             <classname>HeadStyle</classname> allows you to wrap the style tag in conditional
  65             comments, which allows you to hide it from specific browsers. To add the conditional
  66             tags, pass the conditional value as part of the <varname>$attributes</varname> parameter
  67             in the method calls.
  68         </para>
  69
  70         <example id="zend.view.helpers.initial.headstyle.conditional">
  71             <title>Headstyle With Conditional Comments</title>
  72
  73             <programlisting language="php"><![CDATA[
  74 // adding scripts
  75 $this->headStyle()->appendStyle($styles, array('conditional' => 'lt IE 7'));
  76 ]]></programlisting>
  77         </example>
  78     </note>
  79
  80     <para>
  81         <classname>HeadStyle</classname> also allows capturing style declarations; this
  82         can be useful if you want to create the declarations programmatically,
  83         and then place them elsewhere. The usage for this will be showed in an
  84         example below.
  85     </para>
  86
  87     <para>
  88         Finally, you can also use the <methodname>headStyle()</methodname> method to
  89         quickly add declarations elements; the signature for this is
  90         <methodname>headStyle($content$placement = 'APPEND', $attributes = array())</methodname>.
  91         <varname>$placement</varname> should be either 'APPEND', 'PREPEND', or 'SET'.
  92     </para>
  93
  94     <para>
  95         <classname>HeadStyle</classname> overrides each of <methodname>append()</methodname>,
  96         <methodname>offsetSet()</methodname>, <methodname>prepend()</methodname>, and
  97         <methodname>set()</methodname> to enforce usage of the special methods as listed above.
  98         Internally, it stores each item as a <property>stdClass</property> token, which it later
  99         serializes using the <methodname>itemToString()</methodname> method. This allows you
 100         to perform checks on the items in the stack, and optionally modify these
 101         items by simply modifying the object returned.
 102     </para>
 103
 104     <para>
 105         The <classname>HeadStyle</classname> helper is a concrete implementation of the
 106         <link linkend="zend.view.helpers.initial.placeholder">Placeholder
 107             helper</link>.
 108     </para>
 109
 110     <note>
 111         <title>UTF-8 encoding used by default</title>
 112
 113         <para>
 114             By default, Zend Framework uses <acronym>UTF-8</acronym> as its default encoding, and,
 115             specific to this case, <classname>Zend_View</classname> does as well. Character encoding
 116             can be set differently on the view object itself using the
 117             <methodname>setEncoding()</methodname> method (or the the <varname>encoding</varname>
 118             instantiation parameter). However, since <classname>Zend_View_Interface</classname> does
 119             not define accessors for encoding, it's possible that if you are using a custom view
 120             implementation with this view helper, you will not have a
 121             <methodname>getEncoding()</methodname> method, which is what the view helper uses
 122             internally for determining the character set in which to encode.
 123         </para>
 124
 125         <para>
 126             If you do not want to utilize <acronym>UTF-8</acronym> in such a situation, you will
 127             need to implement a <methodname>getEncoding()</methodname> method in your custom view
 128             implementation.
 129         </para>
 130     </note>
 131
 132     <example id="zend.view.helpers.initial.headstyle.basicusage">
 133         <title>HeadStyle Helper Basic Usage</title>
 134
 135         <para>
 136             You may specify a new style tag at any time:
 137         </para>
 138
 139         <programlisting language="php"><![CDATA[
 140 // adding styles
 141 $this->headStyle()->appendStyle($styles);
 142 ]]></programlisting>
 143
 144         <para>
 145             Order is very important with <acronym>CSS</acronym>; you may need to ensure that
 146             declarations are loaded in a specific order due to the order of the
 147             cascade; use the various append, prepend, and offsetSet directives
 148             to aid in this task:
 149         </para>
 150
 151         <programlisting language="php"><![CDATA[
 152 // Putting styles in order
 153
 154 // place at a particular offset:
 155 $this->headStyle()->offsetSetStyle(100, $customStyles);
 156
 157 // place at end:
 158 $this->headStyle()->appendStyle($finalStyles);
 159
 160 // place at beginning
 161 $this->headStyle()->prependStyle($firstStyles);
 162 ]]></programlisting>
 163
 164         <para>
 165             When you're finally ready to output all style declarations in your
 166             layout script, simply echo the helper:
 167         </para>
 168
 169         <programlisting language="php"><![CDATA[
 170 <?php echo $this->headStyle() ?>
 171 ]]></programlisting>
 172     </example>
 173
 174     <example id="zend.view.helpers.initial.headstyle.capture">
 175         <title>Capturing Style Declarations Using the HeadStyle Helper</title>
 176
 177         <para>
 178             Sometimes you need to generate <acronym>CSS</acronym> style declarations
 179             programmatically. While you could use string concatenation,
 180             heredocs, and the like, often it's easier just to do so by creating
 181             the styles and sprinkling in <acronym>PHP</acronym> tags.
 182             <classname>HeadStyle</classname> lets you do just that, capturing it to the stack:
 183         </para>
 184
 185         <programlisting language="php"><![CDATA[
 186 <?php $this->headStyle()->captureStart() ?>
 187 body {
 188     background-color: <?php echo $this->bgColor ?>;
 189 }
 190 <?php $this->headStyle()->captureEnd() ?>
 191 ]]></programlisting>
 192
 193         <para>
 194             The following assumptions are made:
 195         </para>
 196
 197         <itemizedlist>
 198             <listitem>
 199                 <para>
 200                     The style declarations will be appended to the stack. If you
 201                     wish for them to replace the stack or be added to the top,
 202                     you will need to pass 'SET' or 'PREPEND', respectively, as
 203                     the first argument to <methodname>captureStart()</methodname>.
 204                 </para>
 205             </listitem>
 206
 207             <listitem>
 208                 <para>
 209                     If you wish to specify any additional attributes for the
 210                     <emphasis>&lt;style&gt;</emphasis> tag, pass them in an array as
 211                     the second argument to <methodname>captureStart()</methodname>.
 212                 </para>
 213             </listitem>
 214         </itemizedlist>
 215     </example>
 216 </sect3>
 217 <!--
 218 vim:se ts=4 sw=4 et:
 219 -->