Development

Changeset 14457

You must first sign up to be able to contribute.

Changeset 14457

Show
Ignore:
Timestamp:
01/04/09 19:03:07 (4 years ago)
Author:
boutell
Message:

Released

Files:

Legend:

Unmodified
Added
Removed
Modified
Copied
Moved

  • plugins/pkAdminQuickCreatePlugin/trunk/README

    r14456 r14457  
    1 = pkAdminQuickCreatePlugin = 
     1# pkAdminQuickCreatePlugin # 
    22 
    33Many admin generator forms involve making associations between the object being edited and related objects. For instance, when adding an event to a calendar, you may need to associate that event with a DJ or a band. 
    …… 
    55Symfony's admin generator can provide pulldowns to select these, but what if they don't already exist? pkAdminQuickCreatePlugin makes it easy to implement "quick create" buttons, like this: 
    66 
    7     Select Band: [Band Menu] OR... [Add a New Band] 
    8  
    9     When the user clicks "Add a New Band," the state of the form is saved and the user is diverted to the edit action of the band admin module. When the user saves a new band, they are automatically redirected back to the edit action of the event admin module, with all of their form fields restored and the newly created band preselected from the band menu. The cancel ("list") button also redirects appropriately. (We recommend relabeling them "save" and "cancel" via custom templates.) 
    10  
    11     Solutions to keep the user from becoming confused about the process and avoid certain implementation pitfalls are discussed below. 
    12  
    13     Diversions can be nested, so it's possible to add a guitarist while adding a band while adding an event, although it is certainly true that the potential for user confusion increases as one goes along. 
    14  
    15     This greatly increases the user-friendliness of the admin generator with a minimum of new effort on your part. 
    16  
    17 == Requirements == 
     7    Select Band: Band Menu OR... Add a New Band 
     8 
     9  When the user clicks "Add a New Band," the state of the form is saved and the user is diverted to the edit action of the band admin module. When the user saves a new band, they are automatically redirected back to the edit action of the event admin module, with all of their form fields restored and the newly created band preselected from the band menu. The cancel ("list") button also redirects appropriately. (We recommend relabeling them "save" and "cancel" via custom templates.) 
     10 
     11Solutions to keep the user from becoming confused about the process and avoid certain implementation pitfalls are discussed below. 
     12 
     13Diversions can be nested, so it's possible to add a guitarist while adding a band while adding an event, although it is certainly true that the potential for user confusion increases as one goes along. 
     14 
     15This greatly increases the user-friendliness of the admin generator with a minimum of new effort on your part. 
     16 
     17## Requirements ## 
    1818 
    1919pkAdminQuickCreatePlugin requires Propel. It has only been tested with 
    …… 
    2222admin generator arena. 
    2323 
    24 == Usage == 
     24## Usage ## 
    2525 
    2626To take advantage of pkAdminQuickCreatePlugin you will need to make 
    2727changes to your code in four places: 
    2828 
    29 1. The action class of the admin generator module you are 
    30 coming from (events, in my example). I'll call this the "source" module. 
    31  
    32 2. The templates of that module. 
    33  
    34 3. The action class of the admin generator module you are 
    35 going to (bands, in my example). I'll call this the "destination" module. 
    36  
    37 4. Technically optional, but essential for your users to understand what  
    38 is going on: change the templates of your destination module. 
    39  
    40 === Step One: The Source Module's Action Class === 
     29* The action class of the admin generator module you are 
     30  coming from (events, in my example). I'll call this the "source" module. 
     31 
     32* The templates of that module. 
     33 
     34* The action class of the admin generator module you are 
     35  going to (bands, in my example). I'll call this the "destination" module. 
     36 
     37* Technically optional, but essential for your users to understand what  
     38  is going on: change the templates of your destination module. 
     39 
     40### Step One: The Source Module's Action Class ### 
    4141 
    4242Add the following code to your source module's action class, replacing 
    …… 
    5252            'type' => 'Band', 
    5353            'field' => 'band_id', 
    54 '           'module' => 'band' 
     54            'module' => 'band' 
    5555          ) 
    5656        ) 
    …… 
    7272validation checks as well after that call. 
    7373 
    74 === Step Two: The Source Module's Templates === 
     74### Step Two: The Source Module's Templates ### 
    7575 
    7676The source module will need a custom partial for the field containing 
    …… 
    8282      display: 
    8383        # Leading underscore means "use the partial" 
     84        # Please use a dash, not an asterisk, I have no idea 
     85        # why markdown is rendering an asterisk 
    8486        - _band_id 
    8587        # More fields etc 
    …… 
    157159 
    158160    quick_create_tag('Band', 'band_id',  
    159       array('label' => 'Add a New Band')) 
     161      array('label' => 'Add a New Band')); 
    160162 
    161163As before, the last two parameters are optional, as long as you are 
    …… 
    163165generates for you. 
    164166 
    165 === Step Three: The Destination Module's Actions == 
     167### Step Three: The Destination Module's Actions ### 
    166168 
    167169The destination admin generator module (the `band` module, in our 
    …… 
    212214clicking "List" rather than "Save" or "Save and List." 
    213215 
    214 === Step Four: Destination Module Templates === 
     216### Step Four: Destination Module Templates ### 
    215217 
    216218Technically, we're done at this point. We can start the creation of 
    …… 
    249251`_edit_header.php` template like this: 
    250252 
    251 <?php if (pkAdminQuickCreateTools::active()): ?> 
    252 <p><b>You are adding a band as part of a new event.</b> When you click 
    253 Save you will be returned to the event form. If you decide not to add a new 
    254 band, click Cancel. 
    255 </p> 
    256 <?php endif ?> 
    257  
    258 == Pitfalls: Ensuring Consistent Results == 
     253    <?php if (pkAdminQuickCreateTools::active()): ?> 
     254    <p><b>You are adding a band as part of a new event.</b> When you click 
     255    Save you will be returned to the event form. If you decide not to add a new 
     256    band, click Cancel. 
     257    </p> 
     258    <?php endif ?> 
     259 
     260## Pitfalls: Ensuring Consistent Results ## 
    259261 
    260262By its very nature, the web is a stateless system in which users can 
    …… 
    273275previously been in progress. 
    274276 
    275 == Credits == 
     277## Changelog ## 
     278 
     279### 0.5.2 ### 
     280 
     281Markdown fixes in documentation. No code changes. 
     282 
     283### 0.5.1 ### 
     284 
     285Markdown fixes in documentation. No code changes. 
     286 
     287### 0.5.0 ### 
     288 
     289First release. 
     290 
     291## Credits ## 
    276292 
    277293Tom Boutell 

  • plugins/pkAdminQuickCreatePlugin/trunk/package.xml

    r14456 r14457  
    1717 <time>12:43:00</time> 
    1818 <version> 
    19   <release>0.5.0</release> 
     19  <release>0.5.2</release> 
    2020  <api>0.5.0</api> 
    2121 </version>