middleman-pagegroups
This gem provides advanced navigation tools and helpers for grouping pages by topic and navigating between them. It includes support for tables of content, related pages, breadcrumbs, and more.
It is standalone and can be used in any Middleman project.
Top Level Namespace
Defined Under Namespace
Classes: MiddlemanPageGroups
Class: MiddlemanPageGroups
- Inherits:
-
Middleman::Extension
- Object
- Middleman::Extension
- MiddlemanPageGroups
- Defined in:
- lib/middleman-pagegroups/extension.rb
Overview
This extension provides advanced navigation tools and helpers for grouping pages by topic and navigating between them. It includes support for tables of content, related pages, breadcrumbs, and more.
Extension Configuration (collapse)
-
- (Boolean) options[:extend_page_class]=
If true then the default Middleman
page_class
helper will be extended to include simplegroup
andpage_name
for each resource. -
- (String) options[:nav_breadcrumbs_alt_class]=
Default css class for the
nav_breadcrumbs_alt
helper/partial. -
- (String) options[:nav_breadcrumbs_alt_label]=
Default “current page” label for the
nav_breadcrumbs_alt
helper/partial. -
- (String) options[:nav_breadcrumbs_class]=
Default css class for the
nav_breadcrumbs
helper/partial. -
- (String) options[:nav_brethren_class]=
Default css class for the
nav_brethren
helper/partial. -
- (String) options[:nav_brethren_index_class]=
Default css class for the
nav_brethren_index
helper/partial. -
- (String) options[:nav_legitimate_children_class]=
Default css class for the
nav_legitimate_children
helper/partial. -
- (String) options[:nav_prev_next_class]=
Default css class for the
nav_prev_next
helper/partial. -
- (String) options[:nav_prev_next_label_next]=
Default “next” label text for the
nav_prev_next
helper/partial. -
- (String) options[:nav_prev_next_label_prev]=
Default “previous” label text for the
nav_prev_next
helper/partial. -
- (String) options[:nav_toc_index_class]=
Default css class for the
nav_toc_index
helper/partial. -
- (Boolean) options[:strip_file_prefixes]=
If
true
leading numbers used for sorting files will be removed for presentation purposes.
Extended Helpers (collapse)
-
- (String) page_classes
Extend the built-in page_classes to include the naked group and page name.
Helpers (collapse)
-
- (String) nav_breadcrumbs(locals = {})
Generates a breadcrumbs structure as an ``.
-
- (String) nav_breadcrumbs_alt(locals = {})
Generates the breadcrumbs structure, alternate form, wherein the trailing element consists of a label indicating “current page,” as an ``.
-
- (String) nav_brethren(locals = {})
Generates a fuller list of related topics as a ``, with a link to the page as the definition term and the page’s front matter
:blurb
as the definition definition. -
- (String) nav_brethren_index(locals = {})
Generates a condensed list of related topics as an ``, omitting the
:blurb
front matter data. -
- (String) nav_legitimate_children(locals = {})
Generates a fuller list of child topics as a ``, with a link to the page as the definition term and the page’s front matter
:blurb
as the definition definition. -
- (String) nav_prev_next(locals = {})
Generates a previous and next item as two anchors nested within a ``.
-
- (String) nav_toc_index(locals = {})
Generate a nested `` structure representing the complete table of contents from any particular starting point.
CSS Class Helpers (collapse)
-
- (String) nav_breadcrumbs_alt_class
Returns the value of the the extension option
options[:nav_breadcrumbs_alt_class]
. -
- (String) nav_breadcrumbs_alt_label
Returns the value of the the extension option
options[:nav_breadcrumbs_alt_label]
. -
- (String) nav_breadcrumbs_class
Returns the value of the the extension option
options[:nav_breadcrumbs_class]
. -
- (String) nav_brethren_class
Returns the value of the the extension option
options[:nav_brethren_class]
. -
- (String) nav_brethren_index_class
Returns the value of the the extension option
options[:nav_brethren_index_class]
. -
- (String) nav_legitimate_children_class
Returns the value of the the extension option
options[:nav_legitimate_children_class]
. -
- (String) nav_prev_next_class
Returns the value of the the extension option
options[:nav_prev_next_class]
. -
- (String) nav_prev_next_label_next
Returns the value of the the extension option
options[:nav_prev_next_label_next]
. -
- (String) nav_prev_next_label_prev
Returns the value of the the extension option
options[:nav_prev_next_label_prev]
. -
- (String) nav_toc_index_class
Returns the value of the the extension option
options[:nav_toc_index_class]
.
Resource Extensions (collapse)
-
- (Array<Sitemap::Resource>) resource.breadcrumbs
Returns an array of resources leading to this resource.
-
- (Array<Sitemap::Resource>) resource.brethren
Returns an array of all of the siblings of this page, taking into account their eligibility for display.
-
- (Sitemap::Resource) resource.brethren_next
Returns the next sibling based on order, or
nil
if there is no next sibling. -
- (Sitemap::Resource) resource.brethren_previous
Returns the previous sibling based on order, or
nil
if there is no previous sibling. -
- (Integer) resource.group_count
Returns the quantity of pages in the current page’s group, including this current page, i.e., the number of
brethren + 1
. -
- (Array<Sitemap::Resource>) resource.legitimate_children
Returns an array of all of the children of this resource, taking into account their eligibility for display.
-
- (Boolean) resource.navigator_eligible?
Determines whether a page is eligible to include a previous/next page control.
-
- (String) resource.page_group
Make
page_group
available for each resource. -
- (String) resource.page_name
Make
page_name
available for each resource. -
- (Integer, Nil) resource.page_sequence
Returns the page sequence amongst all of the brethren, and can be used as a page number surrogate.
-
- (Sitemap::Resource) resource.parent
Return the parent of the resource.
-
- (Integer) resource.sort_order
Returns the page sort order or 0 if no page sort order was applied.
Instance Attribute Details
- (Boolean) options[:extend_page_class]=(value)
If true then the default Middleman page_class
helper will be extended
to include simple group
and page_name
for each resource.
|
# File 'lib/middleman-pagegroups/extension.rb', line 41
|
- (String) options[:nav_breadcrumbs_alt_class]=(value)
Default css class for the nav_breadcrumbs_alt
helper/partial.
|
# File 'lib/middleman-pagegroups/extension.rb', line 53
|
- (String) options[:nav_breadcrumbs_alt_label]=(value)
Default “current page” label for the nav_breadcrumbs_alt
helper/partial.
|
# File 'lib/middleman-pagegroups/extension.rb', line 59
|
- (String) options[:nav_breadcrumbs_class]=(value)
Default css class for the nav_breadcrumbs
helper/partial.
|
# File 'lib/middleman-pagegroups/extension.rb', line 47
|
- (String) options[:nav_brethren_class]=(value)
Default css class for the nav_brethren
helper/partial.
|
# File 'lib/middleman-pagegroups/extension.rb', line 65
|
- (String) options[:nav_brethren_index_class]=(value)
Default css class for the nav_brethren_index
helper/partial.
|
# File 'lib/middleman-pagegroups/extension.rb', line 71
|
- (String) options[:nav_legitimate_children_class]=(value)
Default css class for the nav_legitimate_children
helper/partial.
|
# File 'lib/middleman-pagegroups/extension.rb', line 77
|
- (String) options[:nav_prev_next_class]=(value)
Default css class for the nav_prev_next
helper/partial.
|
# File 'lib/middleman-pagegroups/extension.rb', line 83
|
- (String) options[:nav_prev_next_label_next]=(value)
Default “next” label text for the nav_prev_next
helper/partial.
|
# File 'lib/middleman-pagegroups/extension.rb', line 95
|
- (String) options[:nav_prev_next_label_prev]=(value)
Default “previous” label text for the nav_prev_next
helper/partial.
|
# File 'lib/middleman-pagegroups/extension.rb', line 89
|
- (String) options[:nav_toc_index_class]=(value)
Default css class for the nav_toc_index
helper/partial.
|
# File 'lib/middleman-pagegroups/extension.rb', line 101
|
- (Boolean) options[:strip_file_prefixes]=(value)
If true
leading numbers used for sorting files will be removed for
presentation purposes. This makes it possible to neatly organize your
source files in their presentation order on your filesystem but output
nice filenames without ugly prefix numbers.
|
# File 'lib/middleman-pagegroups/extension.rb', line 33
|
CSS Class Helpers
- (String) nav_breadcrumbs_alt_class
Returns the value of the the extension option
options[:nav_breadcrumbs_alt_class]
.
Both the built-in helpers and the partials (if you install them) use these helpers in order to access the configuration values. When writing your own partials it is generally unnecessary to use these helpers; you can simply assign your own class name.
The provided helpers and partials use CSS classes, and if the class names collide with your own class names or fail to meet with your naming standards, then they can be changed using the extension options.
711 712 713 |
# File 'lib/middleman-pagegroups/extension.rb', line 711 def extensions[:MiddlemanPageGroups].[:nav_breadcrumbs_alt_class] end |
- (String) nav_breadcrumbs_alt_label
Returns the value of the the extension option
options[:nav_breadcrumbs_alt_label]
.
Both the built-in helpers and the partials (if you install them) use these helpers in order to access the configuration values. When writing your own partials it is generally unnecessary to use these helpers; you can simply assign your own class name.
The provided helpers and partials use CSS classes, and if the class names collide with your own class names or fail to meet with your naming standards, then they can be changed using the extension options.
724 725 726 |
# File 'lib/middleman-pagegroups/extension.rb', line 724 def extensions[:MiddlemanPageGroups].[:nav_breadcrumbs_alt_label] end |
- (String) nav_breadcrumbs_class
Returns the value of the the extension option
options[:nav_breadcrumbs_class]
.
Both the built-in helpers and the partials (if you install them) use these helpers in order to access the configuration values. When writing your own partials it is generally unnecessary to use these helpers; you can simply assign your own class name.
The provided helpers and partials use CSS classes, and if the class names collide with your own class names or fail to meet with your naming standards, then they can be changed using the extension options.
698 699 700 |
# File 'lib/middleman-pagegroups/extension.rb', line 698 def extensions[:MiddlemanPageGroups].[:nav_breadcrumbs_class] end |
- (String) nav_brethren_class
Returns the value of the the extension option
options[:nav_brethren_class]
.
Both the built-in helpers and the partials (if you install them) use these helpers in order to access the configuration values. When writing your own partials it is generally unnecessary to use these helpers; you can simply assign your own class name.
The provided helpers and partials use CSS classes, and if the class names collide with your own class names or fail to meet with your naming standards, then they can be changed using the extension options.
737 738 739 |
# File 'lib/middleman-pagegroups/extension.rb', line 737 def nav_brethren_class extensions[:MiddlemanPageGroups].[:nav_brethren_class] end |
- (String) nav_brethren_index_class
Returns the value of the the extension option
options[:nav_brethren_index_class]
.
Both the built-in helpers and the partials (if you install them) use these helpers in order to access the configuration values. When writing your own partials it is generally unnecessary to use these helpers; you can simply assign your own class name.
The provided helpers and partials use CSS classes, and if the class names collide with your own class names or fail to meet with your naming standards, then they can be changed using the extension options.
750 751 752 |
# File 'lib/middleman-pagegroups/extension.rb', line 750 def nav_brethren_index_class extensions[:MiddlemanPageGroups].[:nav_brethren_index_class] end |
- (String) nav_legitimate_children_class
Returns the value of the the extension option
options[:nav_legitimate_children_class]
.
Both the built-in helpers and the partials (if you install them) use these helpers in order to access the configuration values. When writing your own partials it is generally unnecessary to use these helpers; you can simply assign your own class name.
The provided helpers and partials use CSS classes, and if the class names collide with your own class names or fail to meet with your naming standards, then they can be changed using the extension options.
763 764 765 |
# File 'lib/middleman-pagegroups/extension.rb', line 763 def nav_legitimate_children_class extensions[:MiddlemanPageGroups].[:nav_legitimate_children_class] end |
- (String) nav_prev_next_class
Returns the value of the the extension option
options[:nav_prev_next_class]
.
Both the built-in helpers and the partials (if you install them) use these helpers in order to access the configuration values. When writing your own partials it is generally unnecessary to use these helpers; you can simply assign your own class name.
The provided helpers and partials use CSS classes, and if the class names collide with your own class names or fail to meet with your naming standards, then they can be changed using the extension options.
776 777 778 |
# File 'lib/middleman-pagegroups/extension.rb', line 776 def nav_prev_next_class extensions[:MiddlemanPageGroups].[:nav_prev_next_class] end |
- (String) nav_prev_next_label_next
Returns the value of the the extension option
options[:nav_prev_next_label_next]
.
Both the built-in helpers and the partials (if you install them) use these helpers in order to access the configuration values. When writing your own partials it is generally unnecessary to use these helpers; you can simply assign your own class name.
The provided helpers and partials use CSS classes, and if the class names collide with your own class names or fail to meet with your naming standards, then they can be changed using the extension options.
802 803 804 |
# File 'lib/middleman-pagegroups/extension.rb', line 802 def nav_prev_next_label_next extensions[:MiddlemanPageGroups].[:nav_prev_next_label_next] end |
- (String) nav_prev_next_label_prev
Returns the value of the the extension option
options[:nav_prev_next_label_prev]
.
Both the built-in helpers and the partials (if you install them) use these helpers in order to access the configuration values. When writing your own partials it is generally unnecessary to use these helpers; you can simply assign your own class name.
The provided helpers and partials use CSS classes, and if the class names collide with your own class names or fail to meet with your naming standards, then they can be changed using the extension options.
789 790 791 |
# File 'lib/middleman-pagegroups/extension.rb', line 789 def nav_prev_next_label_prev extensions[:MiddlemanPageGroups].[:nav_prev_next_label_prev] end |
- (String) nav_toc_index_class
Returns the value of the the extension option
options[:nav_toc_index_class]
.
Both the built-in helpers and the partials (if you install them) use these helpers in order to access the configuration values. When writing your own partials it is generally unnecessary to use these helpers; you can simply assign your own class name.
The provided helpers and partials use CSS classes, and if the class names collide with your own class names or fail to meet with your naming standards, then they can be changed using the extension options.
815 816 817 |
# File 'lib/middleman-pagegroups/extension.rb', line 815 def nav_toc_index_class extensions[:MiddlemanPageGroups].[:nav_breadcrumbs_alt_class] end |
Extended Helpers
- (String) page_classes
Extend the built-in page_classes to include the naked
group and page name. The features of this helper are
enabled only if options[:extend_page_class]
is
true
.
495 496 497 498 499 500 501 |
# File 'lib/middleman-pagegroups/extension.rb', line 495 def page_classes if extensions[:MiddlemanPageGroups].[:extend_page_class] "#{current_page.page_name} #{current_page.page_group} #{super}" else super end end |
Helpers
- (String) nav_breadcrumbs(locals = {})
Generates a breadcrumbs structure as an <ul>
. The
trailing element is the current page.
521 522 523 524 |
# File 'lib/middleman-pagegroups/extension.rb', line 521 def ( locals = {} ) locals[:klass] = locals.delete(:class) if locals.key?(:class) Haml::Engine.new(MMPartials::MM_BREADCRUMBS).render(self, locals) end |
- (String) nav_breadcrumbs_alt(locals = {})
Generates the breadcrumbs structure, alternate form,
wherein the trailing element consists of a label
indicating “current page,” as an <ul>
.
540 541 542 543 |
# File 'lib/middleman-pagegroups/extension.rb', line 540 def ( locals = {} ) locals[:klass] = locals.delete(:class) if locals.key?(:class) Haml::Engine.new(MMPartials::MM_BREADCRUMBS_ALT).render(self, locals) end |
- (String) nav_brethren(locals = {})
Generates a fuller list of related topics as a <dl>
,
with a link to the page as the definition term and the
page’s front matter :blurb
as the definition
definition.
560 561 562 563 |
# File 'lib/middleman-pagegroups/extension.rb', line 560 def nav_brethren( locals = {} ) locals[:klass] = locals.delete(:class) if locals.key?(:class) Haml::Engine.new(MMPartials::MM_BRETHREN).render(self, locals) end |
- (String) nav_brethren_index(locals = {})
Generates a condensed list of related topics as an
<ul>
, omitting the :blurb
front matter data.
579 580 581 582 |
# File 'lib/middleman-pagegroups/extension.rb', line 579 def nav_brethren_index(locals = {}) locals[:klass] = locals.delete(:class) if locals.key?(:class) Haml::Engine.new(MMPartials::MM_BRETHREN_INDEX).render(self, locals) end |
- (String) nav_legitimate_children(locals = {})
Generates a fuller list of child topics as a <dl>
,
with a link to the page as the definition term and the
page’s front matter :blurb
as the definition
definition.
600 601 602 603 |
# File 'lib/middleman-pagegroups/extension.rb', line 600 def nav_legitimate_children(locals = {}) locals[:klass] = locals.delete(:class) if locals.key?(:class) Haml::Engine.new(MMPartials::MM_LEGITIMATE_CHILDREN).render(self, locals) end |
- (String) nav_prev_next(locals = {})
Generates a previous and next item as two anchors
nested within a <div>
. With appropriate CSS this
can be rendered as a set of navigation buttons.
621 622 623 624 |
# File 'lib/middleman-pagegroups/extension.rb', line 621 def nav_prev_next(locals = {}) locals[:klass] = locals.delete(:class) if locals.key?(:class) Haml::Engine.new(MMPartials::MM_PREV_NEXT).render(self, locals) end |
- (String) nav_toc_index(locals = {})
Generate a nested <ul>
structure representing the
complete table of contents from any particular
starting point.
641 642 643 644 645 646 647 648 649 650 651 652 653 654 655 656 657 658 659 660 661 662 663 664 665 666 667 668 669 670 671 |
# File 'lib/middleman-pagegroups/extension.rb', line 641 def nav_toc_index( locals = {} ) recurse = locals.key?(:recurse) && locals[:recurse] return if recurse && locals[:start].nil? commence = locals[:start] || current_page pages = commence.legitimate_children if recurse unless pages.to_a.empty? haml_tag :ul do pages.each do |p| haml_tag :li do haml_concat link_to p.data.title, p nav_toc_index :start => p, :recurse => true end end end end else capture_haml do locals[:klass] = locals.delete(:class) if locals.key?(:class) haml_tag :ul, :class => (locals.key?(:klass) && locals[:klass]) || nav_toc_index_class do haml_tag :li do haml_concat link_to commence.data.title, commence nav_toc_index :start => commence, :recurse => true end end end # capture_haml end end |
Resource Extensions
- (Array<Sitemap::Resource>) resource.breadcrumbs
Returns an array of resources leading to this resource.
159 160 161 162 163 |
# File 'lib/middleman-pagegroups/extension.rb', line 159 def resource. hierarchy = [] << self hierarchy.unshift hierarchy.first.parent while hierarchy.first.parent hierarchy end |
- (Array<Sitemap::Resource>) resource.brethren
Returns an array of all of the siblings of this page, taking into account their eligibility for display.
- is not already the current page.
- has a
sort_order
. - is not ignored.
The returned array will be sorted by each item’s
sort_order
.
159 160 161 162 163 |
# File 'lib/middleman-pagegroups/extension.rb', line 159 def resource.brethren self.siblings .find_all { |p| p.sort_order && p.sort_order != 0 && !p.ignored && p != self } .sort_by { |p| p.sort_order } end |
- (Sitemap::Resource) resource.brethren_next
Returns the next sibling based on order, or nil
if
there is no next sibling.
159 160 161 162 163 164 165 |
# File 'lib/middleman-pagegroups/extension.rb', line 159 def resource.brethren_next if self.sort_order == 0 return nil else return self.brethren.find { |p| p.sort_order > self.sort_order } end end |
- (Sitemap::Resource) resource.brethren_previous
Returns the previous sibling based on order, or nil
if there is no previous sibling.
159 160 161 162 163 164 165 |
# File 'lib/middleman-pagegroups/extension.rb', line 159 def resource.brethren_previous if self.sort_order == 0 return nil else return self.brethren.reverse.find { |p| p.sort_order < self.sort_order } end end |
- (Integer) resource.group_count
Returns the quantity of pages in the current page’s
group, including this current page, i.e., the number
of brethren + 1
.
159 160 161 |
# File 'lib/middleman-pagegroups/extension.rb', line 159 def resource.group_count self.brethren.count + 1 end |
- (Array<Sitemap::Resource>) resource.legitimate_children
Returns an array of all of the children of this resource, taking into account their eligibility for display. Each child is legitimate if it:
- has a sort_order.
- is not ignored.
The returned array will be sorted by each item’s
sort_order
.
159 160 161 162 163 |
# File 'lib/middleman-pagegroups/extension.rb', line 159 def resource.legitimate_children self.children .find_all { |p| p.sort_order && p.sort_order != 0 && !p.ignored } .sort_by { |p| p.sort_order } end |
- (Boolean) resource.navigator_eligible?
Determines whether a page is eligible to include a previous/next page control. This is based on:
- The group is set to allow navigation via the
:navigate
front matter key. - This page is not excluded from navigation via the
use of
:navigator => false
in its front matter. - This page has a
sort_order
.
159 160 161 162 163 164 |
# File 'lib/middleman-pagegroups/extension.rb', line 159 def resource.navigator_eligible? group_navigates = self.parent && self.parent.data['navigate'] == true self_navigates = !( self.data.key?('navigator') && self.data['navigator'] == false ) group_navigates && self_navigates && self.sort_order != 0 end |
- (String) resource.page_group
Make page_group
available for each resource.
Useful for for assigning classes, and/or group
conditionals.
159 160 161 162 163 164 165 |
# File 'lib/middleman-pagegroups/extension.rb', line 159 def resource.page_group result = File.basename( File.split( self.destination_path )[0] ) if result == '.' result = @app.config[:source] end result end |
- (String) resource.page_name
Make page_name
available for each resource. This is
the file’s base name after any renaming has occurred.
Useful for assigning classes, etc.
159 160 161 |
# File 'lib/middleman-pagegroups/extension.rb', line 159 def resource.page_name File.basename( self.destination_path, '.*' ) end |
- (Integer, Nil) resource.page_sequence
Returns the page sequence amongst all of the brethren,
and can be used as a page number surrogate. The first
page is 1. Pages without a sort order will have a nil
page_sequence
.
159 160 161 162 163 164 165 166 167 168 169 |
# File 'lib/middleman-pagegroups/extension.rb', line 159 def resource.page_sequence if self.sort_order == 0 return nil else self.siblings .find_all { |p| p.sort_order && p.sort_order != 0 && !p.ignored } .push(self) .sort_by { |p| p.sort_order } .find_index(self) + 1 end end |
- (Sitemap::Resource) resource.parent
Return the parent of the resource. This implementation corrects a bug in Middleman as of 4.1.7 wherein Middleman doesn’t return the parent if the the directory has been renamed for output.
159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 |
# File 'lib/middleman-pagegroups/extension.rb', line 159 def resource.parent root = path.sub(/^#{::Regexp.escape(traversal_root)}/, '') parts = root.split('/') tail = parts.pop is_index = (tail == @app.config[:index_file]) if parts.empty? return is_index ? nil : @store.find_resource_by_path(@app.config[:index_file]) end test_expr = parts.join('\\/') # eponymous reverse-lookup found = @store.resources.find do |candidate| candidate.path =~ %r{^#{test_expr}(?:\.[a-zA-Z0-9]+|\/)$} end if found found else parts.pop if is_index @store.find_resource_by_path("#{parts.join('/')}/#{@app.config[:index_file]}") end end |
- (Integer) resource.sort_order
Returns the page sort order or 0 if no page sort order was applied.
Pages without a sort order can still be linked to; they simply aren’t brethren or legitimate children, and so don’t participate in any of the automatic navigation features.
159 160 161 |
# File 'lib/middleman-pagegroups/extension.rb', line 159 def resource.sort_order [:sort_order] end |