navGATE

= navGATE

This gem is provided as is.

This gem allows for the ease of navigation building, from preset lists, from active model databases (eg, categories), from yaml files; but it's not just for the ease of use it's also that you can have multiple navigation menus for differant controllers, or the same menu for differant controllers. However you want it, it's up to you.

This gem was built with Rails in mind.

lastly the gem is up on rubygems.org

==Setup in the Application controller you have to include NavGate::NavGateHelpers first.

===For Rails You next have to add a before_filter and helper method to the application controller

Just add: helper_method :render_navigation before_filter :make_menu

To your list of filters and helper methods in the application controller, thats it, you can now use the helper method and the gem to build your navigations. ==For non Rails For non rails version of NavGATE the helpers change, instead they work like so:

make_menu(selection, controller)

render_navigation(selection, controller, options = nil)

You have to pass the controller (or page it matches) and the current selection, in rails they would pass automatically as params[:controller] and params[:selection] respectively (selection being the currently selected nav item).

==Building the menus

When building the menu there are multiple options available, building the menu is done in an initializer file in the configs directory.

There are several options you can pass through, if you are building the menu with the object builder directly then two options must be present, those being 'selection' and 'controller', the rest are optional.

Also note, you can pass multiple NavGate::builders as you need, just match them to there controllers and they should render properly. ===Options

selection: This is used to build the menu options. There are two ways to use this, the first is to use an array of strings containing the menu options a person can select; the second is to pull from a database table, to do this pass a hash with the key being the name of the model and it's value being the field containing it's name

Default: This is used to give the menu a default selection for when the user has not selected anything. Pass a string containing the name of the default selection, if no string is passed then the first item from selection is used.

prefix: This is used when you have a prefix before the target in the URL, eg: if your links render out as "host.com/books" without a prefix; with a prefix of 'shelf' it will render out as "host.com/shelf/books". Namespacing is ignored within this gem, it only looks at the controller's name and nothing else when controller matching.

controller: This is used to match the menu to a controller, when deciding which menu to render, it can also be an array of strings; it matches this attribute to the current controller.

by_id: This is used when you are using a database model to build the menu and you want to link with IDs rather then the selection list. To use it simply set it to true.

css_class: This is used when you want to hard code the CSS class selector into the menu rather then from the view.

css_selected: the css override for the selected that's currently selected. if no override is passed then the link is simply not rendered out, as with css_class it overrides the one passed in the view, but only for the selected link

examples:

===Building menu object from scratch The default option doesn't have to be the first in the selection list. NavGate.configure do |build| build.navs = [ NavGate::Builder.new do |options| options[:selection] = %w(selection site_settings users images misc) options[:default] = 'users' options[:prefix] = = 'admin' options[:controller] = 'admin_panel' options[:css_class] = 'nav button' end ] end

===Building menu object from database fields Be sure to pass it as {model_name: :field}. Also note you can pass an array of controllers as well as just a string of one controller which in this case is done via a split command, %w() also works

NavGate.configure do |build| build.navs = [ NavGate::Builder.new do |options| options[:selection] = {categories: :title } options[:prefix] = 'shop_category' options[:controller] = "front_page side_page about_page".split(" ") options[:by_id] = true end ] end ===Building multiple menus

NavGate.configure do |build| build.navs = [ NavGate::Builder.new do |options| options[:selection] = %w(selection site_settings users images misc) options[:default] = 'users' options[:prefix] = = 'admin' options[:controller] = 'admin_panel' options[:css_class] = 'nav button' end, NavGate::Builder.new do |options| options[:selection] = %w(welcome about_us gallery news) options[:default] = 'news' options[:controller] = 'front_page' options[:css_class] = 'nav button' end ] end

=== Using a yml file to build the menu There is also a third option to build the menu, you can use a structured yml file, there is an example yaml file in the config directory called "build_menu.yml". when using this method you are unable to use a database model to create the menu.

===Building from yaml file, Initializing the object: NavGate.configure do |build| build.navs = "#{Rails.root}/config/build_menu.yml" end

The yaml file: nav_1: selection: welcome about_us gallery default: welcome prefix: main controller: front_page nav_2: selection: settings users misc default: settings preix: back_end controller: admin_panel

==Ignoring Controllers Sometimes you're going to want to ignore controllers that don't any gui. Doing that is simple, when you're building the menu just pass an Array to build like so build.ignoring = ['controllers','to','ignore'] before or after you pass through the navs.

==Rendering the menu

To render the menu use the provided helper render_navigation(options); options is a hash that is used to build any html options you might want such as 'class='some_css_class', it can also take two extra options, 'styling:' and 'wrap:'.

===Options

Styling: This is how the navigation can be styled, it can either be ':vertical’ or a character that you wish to use for spacing such as '|' or ':' and so on, it can only be vertical or a spacing character.

Wrap: This allows you to wrap each link in a html tag, wrap can itself take two differant options, either a string containing the tag's name (without "<>", only the tag name) or an Array containing the tag name and it's class.

example: render_navigation({:class => "'nav button'", styling: :vertical, wrap: ['li','test']}) %>

note: There is no point in passing a class here if you have one set when you first build the menu, it will just be overridden, unless of course you're using multiple menus and some of them don't have css overides then they will take this option up.

==Using the selection to automatically render a matching partial

naveGATE is set up so you can use it to render out a partial using @selected, to do this you have to pass a route param of :selection in the route, then you can use <%= render @selected %> to automatically select either the default selection or the current selection.

That said you don't have use this feature, it will still route to whatever url you set up as a normal url, but @selected won't work without :selection example:

routes.rb get "/:selection", to: "front_page#index" root to: "front_page#index"

front_page/index.html.erb <%= render @selected %>

resulting url host.com/books host.com/games

routes to the root but the partials rendered would be respectively _books.html.erb _games.html.erb