title: What's the right way to do layout updates with CMS pages?
body: <p>I have a featured products module I wrote that puts a custom block on the page with a list of products that match whatever attribute(s) I've defined in the block.  Originally I had it working by adding a <code>{{block...}}</code> line to the Content section of the CMS page.  This worked fine, but I wasn't getting the pager.  So, I fixed that by removing the <code>{{block...}}</code> line from the Content section and adding XML to the Layout Update XML section like so:</p>
  
  <pre><code>&lt;reference name="content"&gt;
      &lt;block type="cms/block" name="product_list_top" /&gt;
      &lt;block type="vps_featured/list" name="vps_featured_list" template="catalog/product/sale_list.phtml"&gt;
          &lt;block type="catalog/product_list_toolbar" name="product_list_toolbar" template="catalog/product/list/toolbar.phtml"&gt;
              &lt;block type="page/html_pager" name="product_list_toolbar_pager"/&gt;
          &lt;/block&gt;
          &lt;action method="setToolbarBlockName"&gt;&lt;name&gt;product_list_toolbar&lt;/name&gt;&lt;/action&gt;
          &lt;action method="setAttributeName"&gt;&lt;name&gt;my_attribute&lt;/name&gt;&lt;/action&gt;
      &lt;/block&gt;
  &lt;/reference&gt;
  </code></pre>
  
  <p>This also worked great.  I then decided, since there are so many instances of this block, that it would be much cleaner if I added an XML file to the layout folder for my theme and put this code in there.  Then, in the Layout Update section, I could simply have this instead:</p>
  
  <pre><code>&lt;reference name="vps_featured_list"&gt;
      &lt;action method="setAttributeName"&gt;&lt;name&gt;other_attribute&lt;/name&gt;&lt;/action&gt;
  &lt;/reference&gt;
  </code></pre>
  
  <p>So, I created a file called <code>vps_featured.xml</code> and added this to it:</p>
  
  <pre><code>&lt;layout version="0.1.0"&gt;
      &lt;default&gt;
          &lt;reference name="content"&gt;
              &lt;block type="cms/block" name="product_list_top" /&gt;
              &lt;block type="vps_featured/list" name="vps_featured_list" template="catalog/product/sale_list.phtml"&gt;
                  &lt;block type="catalog/product_list_toolbar" name="product_list_toolbar" template="catalog/product/list/toolbar.phtml"&gt;
                      &lt;block type="page/html_pager" name="product_list_toolbar_pager" /&gt;
                  &lt;/block&gt;
                  &lt;action method="setToolbarBlockName"&gt;&lt;name&gt;product_list_toolbar&lt;/name&gt;&lt;/action&gt;
              &lt;/block&gt;
          &lt;/reference&gt;
      &lt;/default&gt;
  &lt;/layout&gt;
  </code></pre>
  
  <p>This layout update XML file was referenced in the <code>config.xml</code> for my custom featured module.  I naively assumed that <code>vps_featured.xml</code> would only get incorporated into the page layout when my VPS Featured block was on the page, which would only happen in these few instances on special CMS pages.  Apparently that is not the case.  This broke every other page, I guess because it was overriding the default handle.</p>
  
  <p>So this leads me to question #1:  <strong>When are the layout xml files included in the page layout?  Are they used for ALL pages, regardless of whether or not the module referencing them is actually used?</strong></p>
  
  <p>I then decided to try adding a new layout handle that I could reference when I want in my CMS pages.  I modified my layout XML file so the main part is within <code>&lt;vps_featured_list&gt;</code> tags rather than the <code>&lt;default&gt;</code> tags.  This brought the other pages back to life, but of course, my CMS pages no longer worked because that layout update handle isn't being used on those pages.  I tried adding <code>&lt;update handle="vps_featured_list" /&gt;</code> to the Layout Update XML section of the CMS page, but that didn't work (I didn't expect it to).</p>
  
  <p>So this brings me to question #2:  <strong>What's the correct way to accomplish this?</strong></p>
  
  <p>This doesn't sound like it should be this difficult, but clearly I'm missing something.  I've read all I can find on layouts but they are always simple examples, like "add this to EVERY product page".  I don't want something added to EVERY cms page...just a few of them.  Am I stuck using the Layout Update XML section for the CMS pages in question?  I feel like there has to be a cleaner way.</p>
  
  <p>Thanks,</p>
  
  <p>Brian</p>