User Tools

Site Tools


uscaffold

Differences

This shows you the differences between two versions of the page.

Link to this comparison view

Both sides previous revision Previous revision
uscaffold [2011/02/03 04:03]
unirgy
uscaffold [2011/10/19 19:12] (current)
unirgy
Line 1: Line 1:
 +====== uScaffold ======
 +
 +===== What is it? =====
 +
 +uScaffold is a simple Magento extension that was created for personal use to assist with rapid prototyping of custom Magento extensions.
 +
 +It will attempt to generate a standard Magento configuration based on simple hints from custom extension declaration XML file.
 +
 +This extension is geared towards developers, who are learning Magento or just wish to speed up their extension development.
 +
 +===== How do I get it? =====
 +
 +Download the archive from this link and unpack into Magento root folder:
 +http://download.unirgy.com/Unirgy_Scaffold-latest.zip
 +
 +Disable or refresh cache as needed.
 +
 +===== How does it work? (by example) =====
 +
 +==== Initialize extension with uScaffold support ====
 +After installation of the extension, create a new file as you would normally do for a custom extension:
 +<file xml app/etc/modules/Custom_Extension.xml>
 +<?xml version="1.0"?>
 +<config>
 +  <modules>
 +    <Custom_Extension>
 +      <active>true</active>
 +      <codePool>local</codePool>
 +      
 +      <!-- THIS PART IS CUSTOM FOR SCAFFOLDING -->
 +      <scaffold code="customext"/>
 +      <!-- END SCAFFOLDING -->
 +
 +    </Custom_Extension>
 +  </modules>
 +</config>
 +</file>
 +
 +After you save, uScaffold will generate basic configuration for the module, which encompasses models, helpers and blocks.
 +Now you can just create PHP files as you usually would do for magento, without worrying about the configuration for them.
 +Take note: You DO NOT need to create ''app/code/local/Custom/Extension/etc/config.xml''.
 +
 +<file php app/code/local/Custom/Extension/Model/Test.php>
 +<?php
 +
 +class Custom_Extension_Model_Test extends Varien_Object
 +{
 +}
 +</file>
 +
 +The models, helpers and blocks are referenced by the ''code'' attribute, in this case ''customext''.
 +
 +<code php>
 +<?php
 +
 +$model = Mage::getModel('customext/test');
 +$helper = Mage::helper('customext');
 +</code>
 +<code xml>
 +<layout>
 +  <default>
 +    <reference name="content">
 +      <block type="customext/your_block"/>
 +    </reference>
 +  </default>  
 +</layout>
 +</code>
 +
 +If you do not have any special logic for helper, you do not need to create Helper/Data.php file, and still use ''<?php echo $this->__('...') ?>'' in your blocks.
 +
 +==== Working with DB tables ====
 +
 +Your module needs DB tables support?
 +No problem.
 +
 +<file xml app/etc/modules/Custom_Extension.xml>
 +<?xml version="1.0"?>
 +...
 +      <!-- THIS PART IS CUSTOM FOR SCAFFOLDING -->
 +      <scaffold code="customext">
 +        <tables>
 +          <test1/>
 +          <test2 table="custom_test"/>
 +        </tables>
 +      </scaffold>
 +      <!-- END SCAFFOLDING -->
 +...
 +</file>
 +
 +All the configuration for setup, read and write connections are made automatically, using core DB connections.
 +If ''table'' attribute is not specified, the table name will be the same as table entity code (''test1'').
 +
 +==== Event observers ====
 +
 +<file xml app/etc/modules/Custom_Extension.xml>
 +...
 +      <!-- THIS PART IS CUSTOM FOR SCAFFOLDING -->
 +      <scaffold code="customext">
 +        <observers>
 +          <customer_load_after/>
 +          <sales_order_save_before/>
 +        </observers>
 +      </scaffold>
 +      <!-- END SCAFFOLDING -->
 +...
 +</file>
 +
 +Doing the above will generate configuration to trigger an observer from your PHP model. All you have to do is to add this file:
 +
 +<file php app/code/local/Custom/Extension/Model/Observer.php>
 +<?php
 +class Custom_Extension_Model_Observer
 +{
 +  public function customer_load_after($observer)
 +  {
 +  //...
 +  }
 +  
 +  public function sales_order_save_before($observer)
 +  {
 +  //...
 +  }
 +}
 +</file>
 +
 +==== Frontend development ====
 +
 +<file xml app/etc/modules/Custom_Extension.xml>
 +...
 +      <!-- THIS PART IS CUSTOM FOR SCAFFOLDING -->
 +      <scaffold code="customext">
 +        <frontend/>
 +      </scaffold>
 +      <!-- END SCAFFOLDING -->
 +...
 +</file>
 +
 +BAM! layout updates are loaded from ''layouts/customext.xml'' and translations are loaded from ''Custom_Extension.csv''
 +
 +Do you need to run controllers for your module?
 +
 +<file xml app/etc/modules/Custom_Extension.xml>
 +...
 +      <!-- THIS PART IS CUSTOM FOR SCAFFOLDING -->
 +      <scaffold code="customext">
 +        <frontend>
 +          <controllers/>
 +        </frontend>
 +      </scaffold>
 +      <!-- END SCAFFOLDING -->
 +...
 +</file>
 +
 +Frontend only events?
 +
 +<file xml app/etc/modules/Custom_Extension.xml>
 +...
 +      <!-- THIS PART IS CUSTOM FOR SCAFFOLDING -->
 +      <scaffold code="customext">
 +        <frontend>
 +          <observers>
 +            <customer_load_after/>
 +            <sales_order_save_before/>
 +          </observers>
 +        </frontend>
 +      </scaffold>
 +      <!-- END SCAFFOLDING -->
 +...
 +</file>
 +
 +NOTE: frontend specific observer method should start with ''FRONTEND_'':
 +<code php>
 +  public function FRONTEND_customer_load_after($observer)
 +  {
 +  //...
 +  }
 +</code>
 +
 +==== Admin development ====
 +
 +Similar to frontend:
 +
 +<file xml app/etc/modules/Custom_Extension.xml>
 +...
 +      <!-- THIS PART IS CUSTOM FOR SCAFFOLDING -->
 +      <scaffold code="customext">
 +        <adminhtml>
 +          <controllers/>
 +          <observers>
 +            <customer_load_after/>
 +            <sales_order_save_before/>
 +          </observers>
 +        </adminhtml>
 +      </scaffold>
 +      <!-- END SCAFFOLDING -->
 +...
 +</file>
 +
 +NOTE: admin specific observer method should start with ''ADMIN_'':
 +<code php>
 +  public function ADMIN_customer_load_after($observer)
 +  {
 +  //...
 +  }
 +</code>
 +
 +But wait, there's more!
 +
 +<file xml app/etc/modules/Custom_Extension.xml>
 +...
 +      <!-- THIS PART IS CUSTOM FOR SCAFFOLDING -->
 +      <scaffold code="customext">
 +        <adminhtml>
 +          <nav>
 +            <system>
 +              <test title="Test" sort_order="10" action="sometestadmin/adminhtml_test/index"/>
 +            </system>
 +          </nav>
 +          <config>
 +            <test title="Test"/>
 +          </config>
 +        </adminhtml>
 +      </scaffold>
 +      <!-- END SCAFFOLDING -->
 +...
 +</file>
 +
 +The code above will create admin menu entry and related ACL entry.
 +
 +===== Moving from scaffolding to production =====
 +
 +The uScaffold is not made for the production deployment, and as such is not recommended to be bundled with your extensions.
 +To retrieve automatically generated configuration, add ''output'' attribute to your scaffold declaration:
 +
 +<file xml app/etc/modules/Custom_Extension.xml>
 +...
 +      <!-- THIS PART IS CUSTOM FOR SCAFFOLDING -->
 +      <scaffold code="customext" output="true">
 +        <!-- ... -->
 +      </scaffold>
 +      <!-- END SCAFFOLDING -->
 +...
 +</file>
 +
 +Refresh the page and you'll find ''var/uscaffold/Custom_Extension/config.xml'' file, containing the full Magento config file.
 +
 +Just copy it to ''app/code/local/Custom/Extension/etc/config.xml'', and you're ready for production!
 +
 +===== Wishlist =====
 +
 +  * etc/system.xml scaffolding
 +  * Automatic emulation of basic model classes (Model/*, Model/Mysql4/*, Model/Mysql4/Collection/*)
 +
 +===== FAQ =====
 +
 +== Why the method names for event observers are not in Zend convention? ==
 +
 +In my personal experience it is much easier to maintain event observers and method names when they're the same.
 +Usually they're in 1-to-1 relationship and making them different names only adds to complexity
 +
 +== Why not to use admin routers as additional modules? ==
 +
 +There are still many stores that run Magento 1.3.x, where admin router modules are not available.
 +I was trying to make the scaffold as compatible as possible.
 +Most probably, in future versions it will be replaced with admin router modules or added as a configuration option.
 +
 +===== Example uScaffold configuration vs full Magento configuration =====
 +
 +==== uScaffold configuration ====
 +
 +<file xml app/etc/modules/Custom_Extension.xml>
 +<?xml version="1.0"?>
 +<config>
 +    <modules>
 +        <Custom_Extension>
 +            <active>true</active>
 +            <codePool>local</codePool>
 +
 +            <scaffold code="customext" output="true">
 +                <tables>
 +                    <test table="sometest_test"/>
 +                </tables>
 +                <frontend>
 +                    <controllers/>
 +                    <observers>
 +                        <checkout_cart_add/>
 +                    </observers>
 +                </frontend>
 +                <adminhtml>
 +                    <controllers/>
 +                    <nav>
 +                        <system>
 +                            <test title="Test" sort_order="10" action="sometestadmin/adminhtml_test/index"/>
 +                        </system>
 +                    </nav>
 +                    <config>
 +                        <test title="Test"/>
 +                    </config>
 +                </adminhtml>
 +                <observers>
 +                    <customer_load_after/>
 +                    <sales_order_save_before/>
 +                </observers>
 +            </scaffold>
 +            
 +        </Custom_Extension>
 +    </modules>
 +</config>
 +</file>
 +
 +==== Automatically generated full Magento configuration ====
 +
 +<file xml var/uscaffold/Custom_Extension/config.xml>
 +<?xml version="1.0"?>
 +<config>
 +   <global>
 +      <models>
 +         <customext>
 +            <class>Custom_Extension_Model</class>
 +            <resourceModel>customext_mysql4</resourceModel>
 +         </customext>
 +         <customext_mysql4>
 +            <class>Custom_Extension_Model_Mysql4</class>
 +            <entities>
 +               <test>
 +                  <table>sometest_test</table>
 +               </test>
 +            </entities>
 +         </customext_mysql4>
 +      </models>
 +      <helpers>
 +         <customext>
 +            <class>Custom_Extension_Helper</class>
 +            <rewrite>
 +               <data>Mage_Core_Helper_Data</data>
 +            </rewrite>
 +         </customext>
 +      </helpers>
 +      <blocks>
 +         <customext>
 +            <class>Custom_Extension_Block</class>
 +         </customext>
 +      </blocks>
 +      <resources>
 +         <customext_setup>
 +            <setup>
 +               <module>Custom_Extension</module>
 +            </setup>
 +            <connection>
 +               <use>core_setup</use>
 +            </connection>
 +         </customext_setup>
 +         <customext_write>
 +            <connection>
 +               <use>core_write</use>
 +            </connection>
 +         </customext_write>
 +         <customext_read>
 +            <connection>
 +               <use>core_read</use>
 +            </connection>
 +         </customext_read>
 +      </resources>
 +      <events>
 +         <customer_load_after>
 +            <observers>
 +               <customext>
 +                  <type>singleton</type>
 +                  <model>customext/observer</model>
 +                  <method>customer_load_after</method>
 +               </customext>
 +            </observers>
 +         </customer_load_after>
 +         <sales_order_save_before>
 +            <observers>
 +               <customext>
 +                  <type>singleton</type>
 +                  <model>customext/observer</model>
 +                  <method>sales_order_save_before</method>
 +               </customext>
 +            </observers>
 +         </sales_order_save_before>
 +      </events>
 +   </global>
 +   <frontend>
 +      <layout>
 +         <updates>
 +            <customext>
 +               <file>customext.xml</ file>
 +            </customext>
 +         </updates>
 +      </layout>
 +      <translate>
 +         <modules>
 +            <Custom_Extension>
 +               <files>
 +                  <default>Custom_Extension.csv</default>
 +               </files>
 +            </Custom_Extension>
 +         </modules>
 +      </translate>
 +      <routers>
 +         <customext>
 +            <use>standard</use>
 +            <args>
 +               <module>Custom_Extension</module>
 +               <frontName>customext</frontName>
 +            </args>
 +         </customext>
 +      </routers>
 +      <events>
 +         <checkout_cart_add>
 +            <observers>
 +               <customext>
 +                  <type>singleton</type>
 +                  <model>customext/observer</model>
 +                  <method>checkout_cart_add</method>
 +               </customext>
 +            </observers>
 +         </checkout_cart_add>
 +      </events>
 +   </frontend>
 +   <adminhtml>
 +      <layout>
 +         <updates>
 +            <customext>
 +               <file>customext.xml</ file>
 +            </customext>
 +         </updates>
 +      </layout>
 +      <translate>
 +         <modules>
 +            <Custom_Extension>
 +               <files>
 +                  <default>Custom_Extension.csv</default>
 +               </files>
 +            </Custom_Extension>
 +         </modules>
 +      </translate>
 +      <menu>
 +         <system>
 +            <children>
 +               <test>
 +                  <title>Test</title>
 +                  <sort_order>10</sort_order>
 +                  <action>sometestadmin/adminhtml_test/index</action>
 +                  <children/>
 +               </test>
 +            </children>
 +         </system>
 +      </menu>
 +      <acl>
 +         <resources>
 +            <admin>
 +               <children>
 +                  <system>
 +                     <children>
 +                        <test>
 +                           <title>Test</title>
 +                           <sort_order>10</sort_order>
 +                           <children/>
 +                        </test>
 +                        <config>
 +                           <children>
 +                               <test>
 +                                   <title>Test</title>
 +                               </test>
 +                           </children>
 +                        </config>
 +                     </children>
 +                  </system>
 +               </children>
 +            </admin>
 +         </resources>
 +      </acl>
 +   </adminhtml>
 +   <admin>
 +      <routers>
 +         <customextadmin>
 +            <use>admin</use>
 +            <args>
 +               <module>Custom_Extension</module>
 +               <frontName>customextadmin</frontName>
 +            </args>
 +         </customextadmin>
 +      </routers>
 +   </admin>
 +</config>
 +</file>
 +
 +====== CHANGELOG ======
 +
 +===== 0.6.0 =====
 +  * Fixed copy/pasta mistake in declaring admin routers
 +  * Fixed declaring mysql4 models
 +  * Fixed typo in helpers declaration
 +  * Added configuration ACL entries
 +
 +===== 0.5.0 =====
 +  * Initial release
  
uscaffold.txt · by unirgy