Module | TrackRecordSections |
In: |
lib/track_record_sections.rb
|
File: | track_record_sections.rb |
(C): | Hipposoft 2008, 2009 |
Purpose: | Mixin providing abstract section handling for various bits of TrackRecord code. |
30-Jun-2008 (ADH): Created.
Return the group name inferred from the given task title, or ‘nil’ for no apparent group name in the task title. See "new_group?" for details. The method is called "group_title" rather than "group_name" for symmetry with "section_title" - it‘s more natural when writing caller code to remember (or guess at!) a name of "group_title".
# File lib/track_record_sections.rb, line 107 107: def sections_group_title( task ) 108: this_group = nil 109: task_title = task.title || '' 110: colon = task_title.index( ':' ) 111: this_group = task_title[ 0..( colon - 1 ) ] unless ( colon.nil? ) 112: 113: return this_group 114: end
Initialise the section discovery mechanism. Call this before processing rows. Then, for each row, call "new_section?" to find out if a new section has been entered with the given row, "section_title" to discover its title, then "new_group?" to find out if there is also a new group within the section (if you wish to make such a distinction).
Instance variables are used to record progress across calls. These are:
@sections_last_customer (internal state) @sections_last_project (internal state) @sections_last_group (internal state) @sections_current_index (internal state)
Calling code must avoid these variable names.
Each new section is given a monotonically rising index value, starting at zero. Use the "section_index" method to read the current section‘s index.
# File lib/track_record_sections.rb, line 31 31: def sections_initialise_sections 32: @sections_last_customer = false 33: @sections_last_project = false 34: @sections_last_group = false 35: @sections_current_index = -1 36: end
Similar to "new_section?", except returns ‘true’ when the task title indicates a group. A task title includes a group name if the title has at least one ":" (colon) character in it. Any part of the title before the first colon is considered a group name. View code usually makes only a subtle disctinction for changes in group, e.g. an extra vertical spacer, but if you want to explicitly show new group names then you can do so by calling "group_title" to recover the name string.
Unlike sections, groups are not given unique indices.
# File lib/track_record_sections.rb, line 92 92: def sections_new_group?( task ) 93: this_group = sections_group_title( task ) 94: 95: changed = ( this_group != @sections_last_group ) 96: @sections_last_group = this_group if changed 97: 98: return changed 99: end
See "initialise_sections" for details; call here, passing a task related to the currently processed row, to find out if this task (and therefore its associated row) are the first row in a new section. Returns ‘true’ if so, else ‘false’.
# File lib/track_record_sections.rb, line 43 43: def sections_new_section?( task ) 44: this_project = task.project 45: this_customer = this_project.nil? ? nil : this_project.customer 46: 47: changed = ( this_customer != @sections_last_customer or this_project != @sections_last_project ) 48: 49: if ( changed ) 50: @sections_last_customer = this_customer 51: @sections_last_project = this_project 52: @sections_last_group = sections_group_title( task ) 53: @sections_current_index += 1 54: end 55: 56: return changed 57: end
Return the section index of the current section. Call any time after at least on prior call to "new_section?" (regardless of the return value of that prior call).
# File lib/track_record_sections.rb, line 78 78: def sections_section_index 79: return @sections_current_index 80: end
If "new_section?" returns ‘true’, call here to return a title appropriate for this section (it‘ll be based on customer and project name set up by the prior call to "new_section?"). If using in an HTML view, ensure you escape the output using "h" / "html_escape".
# File lib/track_record_sections.rb, line 64 64: def sections_section_title 65: if ( @sections_last_project.nil? ) 66: return 'No customer, no project' 67: elsif ( @sections_last_customer.nil? ) 68: return "(No customer) #{ @sections_last_project.title }" 69: else 70: return "Customer #{ @sections_last_customer.title } - #{ @sections_last_project.title }" 71: end 72: end