timesheet.rb
Hipposoft 2008
Describe the behaviour of Timesheet objects. See below for more details.
07-Jan-2008 (ADH): Created.
Return a range of years allowed for a timesheet. Optionally pass ‘true’ if you want an actual Date object range rather than just a year range.
# File app/models/timesheet.rb, line 63 def self.allowed_range( accurate = false ) if ( WorkPacket.significant.count.zero? ) range = ( Date.current.year - 2 )..( Date.current.year + 2 ) else range = self.used_range range = ( range.first - 2 )..( range.last + 2 ) end if ( accurate ) ( Date.new( range.first, 1, 1 ) )..( Date.new( range.last, 12, 31 ) ) else range end end
Class method; as #date_for, but pass explicitly the year, week number and day number of interest. If an optional fourth parameter is ‘true’, returns a Date object rather than a string.
# File app/models/timesheet.rb, line 413 def self.date_for( year, week_number, day_number, as_date = false ) # Get the date of Monday, week 1 in this timesheet's year. # Add as many days as needed to get to Monday of the week # for this timesheet. date = Timesheet.get_first_week_start( year ) date = date + ( ( week_number - 1 ) * 7 ) # Add in the day number offset. date += TimesheetRow::DAY_ORDER.index( day_number ) # Return in DD-Mth-YYYY format, or as a Date object? if ( as_date ) return date else return date.strftime( '%d-%b-%Y') # Or ISO: '%Y-%m-%d' end end
Get the date of the first day of week 1 in the given year. Note that sometimes, this can be in December the previous year. Works on commercial weeks (Mon->Sun). Returns a Date.
# File app/models/timesheet.rb, line 303 def self.get_first_week_start( year ) # Is Jan 1st already in week 1? date = Date.new( year, 1, 1 ) if ( date.cweek == 1 ) # Yes. Check December of the previous year. 31.downto( 25 ) do | day | date = Date.new( year - 1, 12, day ) # If we encounter a date in the previous year which has a week # number > 1, then that's the last week of the previous year. If # we're on Dec 31st that means that week 1 started on Jan 1st, # else in December on if ( date.cweek > 1 ) return ( day == 31 ? Date.new( year, 1, 1 ) : Date.new( year - 1, 12, day + 1 ) ) end end else # No. Walk forward through January until we reach week 1. 2.upto( 7 ) do | day | date = Date.new( year, 1, day ) return date if ( date.cweek == 1 ) end end end
Get the date of the last day of the last week in the given year. Note that sometimes, this can be in January in the following year. Works on commercial weeks (Mon->Sun). Returns a Date.
# File app/models/timesheet.rb, line 341 def self.get_last_week_end( year ) # Is Dec 31st already in week 1 for the next year? date = Date.new( year, 12, 31 ) if ( date.cweek == 1 ) # Yes. Check backwards through December to find the last day # in the higher week number. 30.downto( 25 ) do | day | date = Date.new( year, 12, day ) return Date.new( year, 12, day ) if ( date.cweek > 1 ) end else # No. Check January of the following year to find the end # of the highest numbered week. 1.upto( 6 ) do | day | date = Date.new( year + 1, 1, day ) if ( date.cweek == 1 ) return ( day == 1 ? Date.new( year, 12, 31 ) : Date.new( year + 1, 1, day - 1 ) ) end end end end
Get the number of the last commercial week (Mon->Sun) in the given year. This is usually 52, but is 53 for some years.
# File app/models/timesheet.rb, line 374 def self.get_last_week_number( year ) # Is Dec 31st already in week 1 for the next year? date = Date.new( year, 12, 31 ) if ( date.cweek == 1 ) # Yes. Check backwards through December to find the last day # in the higher week number. 30.downto( 25 ) do | day | date = Date.new( year, 12, day ) return date.cweek if ( date.cweek > 1 ) end else # No, so we have the highest week already. return date.cweek end end
Return a range of years used by all current timesheets, or the allowed range (see above) if there are no work packets. Optionally pass ‘true’ if you want an actual Date object range rather than just a year range.
# File app/models/timesheet.rb, line 82 def self.used_range( accurate = false ) return self.allowed_range( accurate ) if WorkPacket.significant.count.zero? first = WorkPacket.find_earliest_by_tasks() last = WorkPacket.find_latest_by_tasks() if accurate ( first.date.to_date )..( last.date.to_date ) else ( first.date.year )..( last.date.year ) end end
Add a row to the timesheet using the given task object. Does nothing if a row containing that task is already present. The updated timesheet is not saved - the caller must do this.
# File app/models/timesheet.rb, line 258 def add_row( task ) unless self.tasks.include?( task ) timesheet_row = TimesheetRow.new timesheet_row.task = task self.timesheet_rows.push( timesheet_row ) end end
Is the given user permitted to update this timesheet?
# File app/models/timesheet.rb, line 144 def can_be_modified_by?( user ) return true if ( user.admin? ) return false unless ( self.is_permitted_for?( user ) ) return ( not self.committed ) end
Count the hours across all rows on the given day number; 0 is Sunday, 1-6 Monday to Saturday.
# File app/models/timesheet.rb, line 269 def column_sum( day_number ) sum = 0.0 # [TODO] Slow. Surely there's a better way...? self.timesheet_rows.each do | timesheet_row | work_packet = WorkPacket.find_by_timesheet_row_id( timesheet_row.id, :conditions => { :day_number => day_number } ) sum += work_packet.worked_hours if work_packet end return sum end
Return a date string representing this timesheet on the given day number. Day numbers are odd - 0 = Sunday at the end of this timesheet’s week, while 1-6 = Monday at the start of the week through to Saturday inclusive (although this may be changed; see the TimesheetRow model). If an optional second parameter is ‘true’, returns a Date object rather than a string.
# File app/models/timesheet.rb, line 405 def date_for( day_number, as_date = false ) Timesheet.date_for( self.year, self.week_number, day_number, as_date ) end
Back-end to #editable_week and showable_week. See those functions for details. Call with the next/previous week boolean and pass a block; this is given a timesheet or nil; evaluate ‘true’ to return details on the item or ‘false’ to move on to the next week.
# File app/models/timesheet.rb, line 221 def discover_week( nextweek ) year = self.year owner = self.user_id if ( nextweek ) inc = 1 week = self.week_number + 1 limit = Timesheet.get_last_week_number( year ) + 1 return if ( week >= limit ) else inc = -1 week = self.week_number - 1 limit = 0 return if ( week <= limit ) end while ( week != limit ) timesheet = Timesheet.find_by_user_id_and_year_and_week_number( owner, year, week ) if ( yield( timesheet ) ) return { :week_number => week, :timesheet => timesheet } end week += inc end return nil end
Return the next (pass ‘true’) or previous (pass ‘false’) editable week after this one, as a hash with properties ‘week_number’ and ‘timesheet’. The latter will be populated with a timesheet if there is a not committed item in the found week, or nil if the week has no associated timesheet yet. Returns nil altogether if no editable week can be found (e.g. ask for previous from week 1, or all previous weeks have committed timesheets on them).
This operation may involve many database queries so is relatively slow.
# File app/models/timesheet.rb, line 201 def editable_week( nextweek ) discover_week( nextweek ) do | timesheet | ( timesheet.nil? or not timesheet.committed ) end end
Instance method that returns an array of all timesheets owned by this user. Pass an optional conditions hash (will be sent in as “:conditions => <given value>”).
# File app/models/timesheet.rb, line 154 def find_mine( conditions = {} ) Timesheet.find_all_by_user_id( self.user_id, :conditions => conditions ) end
Instance method which returns an array of all committed timesheets owned by this user.
# File app/models/timesheet.rb, line 161 def find_mine_committed( conditions = {} ) conditions.merge!( :committed => true ) return find_mine( conditions ) end
Instance method which returns an array of all uncommitted timesheets owned by this user.
# File app/models/timesheet.rb, line 169 def find_mine_uncommitted( conditions = {} ) conditions.merge!( :committed => false ) return find_mine( conditions ) end
Is the given user permitted to do anything with this timesheet?
# File app/models/timesheet.rb, line 138 def is_permitted_for?( user ) return ( user.privileged? or user.id == self.user.id ) end
As #editable_week, but returns weeks for ‘showable’ weeks - that is, only weeks where a timesheet owned by the current user already exists.
# File app/models/timesheet.rb, line 210 def showable_week( nextweek ) discover_week( nextweek ) do | timesheet | ( not timesheet.nil? ) end end
Return the date of the first day for this timesheet as a string augmented with week number for display purposes.
# File app/models/timesheet.rb, line 295 def start_day() return "#{ self.date_for( TimesheetRow::FIRST_DAY ) } (week #{ self.week_number })" end
Count the total number of worked hours in the whole timesheet.
# File app/models/timesheet.rb, line 288 def total_sum() return self.work_packets.sum( :worked_hours ) end
Return an array of week numbers which can be assigned to the timesheet. Includes the current timesheet’s already allocated week.
# File app/models/timesheet.rb, line 178 def unused_weeks() timesheets = find_mine( :year => self.year ) used_weeks = timesheets.collect do | hash | hash[ :week_number ] end range = 1..Timesheet.get_last_week_number( self.year ) unused_weeks = ( range.to_a - used_weeks ) unused_weeks.push( self.week_number ) unless ( self.week_number.nil? ) return unused_weeks.sort() end