Development

Changeset 19618

You must first sign up to be able to contribute.

Changeset 19618

Show
Ignore:
Timestamp:
06/27/09 21:04:08 (4 years ago)
Author:
bshaffer
Message:

updated readme

Files:

Legend:

Unmodified
Added
Removed
Modified
Copied
Moved

  • plugins/csNavigationPlugin/trunk/README

    r19596 r19618  
    1 = csNavigationPlugin plugin = 
     1csNavigationPlugin 
     2================== 
    23 
    34The csNavigationPlugin is a simple way to handle navigation in your applications. 
    45 
    5 csNavigationPlugin is working on Symfony 1.2. 
     6csNavigationPlugin works with Symfony 1.2. 
    67 
    7 == At a glance == 
     8At a glance 
     9----------- 
     10 
    811 * A navigation object to manage multiple trees. All navigation is located under a single root to represent the sitemap 
    912 * Navigation trees can be segmented by level and iteration (starting root, number of levels drilled down) 
    …… 
    1316 * A component who display the breadcrumbs 
    1417 
    15 == License == 
     18License 
     19------- 
    1620 
    1721The csNavigationPlugin is licensed under the GNU Lesser General Public License (LGPL). 
    1822 
    19 == Installation == 
     23Installation 
     24------------ 
    2025 
    21  * Install the plugin: 
     26*Install the plugin*: 
    2227  
    23  {{{ 
    24  $ symfony plugin-install http://plugins.symfony-project.com/csNavigationPlugin 
    25  $ symfony cc 
    26  }}} 
     28    $ symfony plugin-install http://plugins.symfony-project.com/csNavigationPlugin 
     29    $ symfony cc 
    2730  
    28  * Enable the module csNavigation in settings.yml: 
     31*Enable the module csNavigation in settings.yml*: 
    2932  
    30  {{{ 
    31  all: 
    32    .settings: 
    33      enabled_modules:        [default, csNavigation] 
    34  }}}  
     33    [yml] 
     34    .settings: 
     35      enabled_modules:        [default, csNavigation] 
    3536  
    36 == Usage == 
    37 Include the tree component (in the layout for instance): 
    38 {{{ 
    39 #!php 
    40 <div id="navigarion"> 
    41   <?php include_component('csNavigation', 'tree') ?> 
    42 </div> 
    43 }}} 
     37*Set up your site navigation in navigation.yml*: 
     38 
     39    [yml] 
     40    navigation: 
     41      Home:    
     42        ~route:              @homepage 
     43        item1:  
     44        ~route:            @item1 
     45          child1:            @child1 
     46          child2:            home/child2 
     47        item2:  
     48          ~route:            @item2 
     49          child3:     
     50            ~route:          @child3 
     51            grandchild1:      
     52              ~route:       @grandchild1 
     53              ~protected:   on 
     54            google:          http://www.google.com 
     55 
     56    Foo:                   #multiple navigation roots is supported 
     57      Bar:    @bar 
     58 
     59The csNavigationRoute class supports token routes, internal routes, wildcards (*), and absolute urls.  It also supports  
     60token routes with variables (:slug), and matches these by looking for the variable in the Request.  If this isn't found, 
     61it calls a camelized method on the menu object (csNavigationMenu::getDefaultSlug() in this case).  More information on 
     62the navigation.yml file is below. 
     63 
     64   
     65*Add the csNavigationFilter class to your filters.yml*: 
     66 
     67    [yml] 
     68    csNavigation: 
     69      class: csNavigationFilter      #Added at "insert your own filters here" 
     70   
     71Navigation Tree Usage 
     72--------------------- 
     73 
     74Include the navigation helper in your view/layout 
     75 
     76    [php] 
     77    <?php use_helper('Navigation') ?> 
     78 
     79use the helper function to include your tree (in the layout for instance): 
     80 
     81    [php] 
     82    <?php include_navigation(array('id' => 'navigation')) ?> 
    4483 
    4584specify level and/or iteration (default iteration is 2): 
    46 {{{ 
    47 #!php 
    48 <div id="navigarion"> 
    49   <?php include_component('csNavigation', 'tree', array('level' => 1, 'iteration' => 3)) ?> 
    50 </div> 
    51 }}} 
     85 
     86    [php] 
     87    <?php include_navigation(array('level' => 1, 'iteration' => 3)) ?> 
     88 
     89Breadcrumb Usage 
     90---------------- 
     91 
     92Include the navigation helper in your view/layout 
     93 
     94    [php] 
     95    <?php use_helper('Navigation') ?> 
     96 
    5297 
    5398Include the breadcrumbs component (in the layout for instance): 
    54 {{{ 
    55 #!php 
    56 <p id="breadcrumbs"> 
    57   You are here : 
    58   <?php include_component('csNavigation', 'breadcrumbs') ?> 
    59 </p> 
    60 }}} 
    6199 
    62 ** The CS Navigation plugin Breadcrumb portion borrows heavily from the isicsBreadcrumbs Plugin ** 
    63 == Changelog == 
     100    [php] 
     101    You are here : 
     102    <?php include_breadcrumbs() ?> 
     103 
     104If you want to customize the breadcrumb, you can override the generated breadcrumb by  
     105calling the csBreadcrumbs singleton in your action 
     106 
     107    [php] 
     108    //module/actions/actions.class.php 
     109    csBreadcrumbs::getInstance()->addItem('My Item', '@route');  //Renders home > My Item 
     110    csBreadcrumbs::getInstance()->addItem('Another Item');  //Renders home > My Item > Another Item 
     111 
     112The last item in the list is never a link, so your breadcrumbs can be easily stacked in your modules 
     113 
     114You can also specify the navigation used to generate your breadcrumb by passing the csNavigationMenu  
     115instance or the name of the menu: 
     116 
     117    [php] 
     118    $menu = Doctrine::getTable('csNavigationMenu')->getMenu('Administration'); 
     119    $breadcrumb = new csBreadcrumbs($menu) 
     120    // OR: 
     121    $breadcrumb = new csBreadcrumbs('Administration'); 
     122    $breadcrumb->getItems();   
     123 
     124The __getItems()__ method returns an array of csNavigationItems generated from current navigation's active state; 
     125 
     126The navigation.yml File 
     127----------------------- 
     128 
     129Item attributes are prefixed by a tilde (~) and child items are added as displayed above.  possible attributes are 
     130 
     131  * _route_:     the item route 
     132  * _locked_:    the item cannot be moved, good to solidify core navigation 
     133  * _protected_: requires user authentication 
     134  * any fields added to the csNavigationItem can also be set in the YAML file 
     135 
     136Navigation Settings 
     137------------------- 
     138   
     139    [yml] 
     140    settings: 
     141      database: 
     142        driven:      off                # imports the above yaml file into the database 
     143        locked:      off                # locks the provided yaml file from editting in the database 
     144        branch:      item2              # the branch attribute locks everything outside the branch indicated      
     145      expanding: 
     146        default:            on 
     147        level:              2 
     148 
     149Change your database driven setting to on, and csNavigationPlugin will automatically  
     150convert your YAML navigation file to your database.  This allows you to build-all-reload 
     151and reconstruct your navigation on the fly. You can also set the import settings so  
     152the core navigation cannot be changed by the user, or certain branches cant be changed 
     153 
     154Setting and expanding level will determine how your navigation is displayed by default. 
     155You can chose to have no items expanded until they are active, or expand out to a certain level. 
    64156 
    65157=== 2009-03-29 | 0.9.1 beta ===