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 · Last modified: 2011/10/19 19:12 by unirgy