Class TaskJuggler::JournalEntry
In: lib/taskjuggler/Journal.rb
Parent: Object

A JournalEntry stores some RichText strings to describe a status or a property of the project at a certain point in time. Additionally, the entry can contain a reference to a Resource as author and an alert level. The text is structured in 3 different elements, a headline, a short summary and a longer text segment. The headline is mandatory, the summary and details sections are optional.

Methods

new   to_rText  

Attributes

alertLevel  [RW] 
author  [RW] 
date  [R] 
details  [RW] 
flags  [RW] 
headline  [R] 
moderators  [RW] 
property  [R] 
sourceFileInfo  [R] 
summary  [RW] 
timeSheetRecord  [RW] 

Public Class methods

Create a new JournalEntry object.

[Source]

# File lib/taskjuggler/Journal.rb, line 29
    def initialize(journal, date, headline, property, sourceFileInfo = nil)
      # A reference to the Journal object this entry belongs to.
      @journal = journal
      # The date of the entry.
      @date = date
      # A very short description. Should not be longer than about 40
      # characters.
      @headline = headline
      # A reference to a PropertyTreeNode object.
      @property = property
      # Source file location of this entry of type SourceFileInfo
      @sourceFileInfo = sourceFileInfo
      # A reference to a Resource.
      @author = nil
      # A list of Resource objects that have moderated this entry.
      @moderators = []
      # An introductory or summarizing RichText paragraph.
      @summary = nil
      # A RichText of arbitrary length.
      @details = nil
      # The alert level.
      @alertLevel = 0
      # A list of flags.
      @flags = []
      # A reference to a time sheet record that was used to create this
      # JournalEntry object.
      @timeSheetRecord = nil

      # Add the new entry to the journal.
      @journal.addEntry(self)
    end

Public Instance methods

Convert the entry into a RichText string. The formatting is controlled by the Query parameters.

[Source]

# File lib/taskjuggler/Journal.rb, line 63
    def to_rText(query)
      # We use the alert level a sortable and numerical result.
      if query.journalAttributes.include?('alert')
        levelRecord = query.project['alertLevels'][alertLevel]
        if query.selfContained
          alertName = "<nowiki>[</nowiki><fcol:#{levelRecord.color}><nowiki>" +
                      "#{levelRecord.name}</nowiki></fcol><nowiki>]</nowiki>"
        else
          alertName = "[[File:icons/flag-#{levelRecord.id}.png|" +
          "alt=[#{levelRecord.name}]|text-bottom]] "
        end
      else
        alertName = ''
      end

      # The String that will hold the result as RichText markup.
      rText = ''

      # Markup to use for headlines.
      hlMark = '==='

      if query.journalAttributes.include?('property') && @property
        if @property.is_a?(Task)
          # Include the alert level, task name and ID.
          rText += "#{hlMark} #{alertName} <nowiki>#{@property.name}</nowiki>"
          if query.journalAttributes.include?('propertyid')
            rText += " (ID: #{@property.fullId})"
          end
          rText += " #{hlMark}\n\n"

          if query.journalAttributes.include?('timesheet') && @timeSheetRecord
            # Include the reported time sheet data for this task.
            rText += "'''Work:''' #{@timeSheetRecord.actualWorkPercent.to_i}% "
            if @timeSheetRecord.actualWorkPercent !=
               @timeSheetRecord.planWorkPercent
              rText += "(#{@timeSheetRecord.planWorkPercent.to_i}%) "
            end
            if @timeSheetRecord.remaining
              rText += "'''Remaining:''' #{@timeSheetRecord.actualRemaining}d "
              if @timeSheetRecord.actualRemaining !=
                 @timeSheetRecord.planRemaining
                rText += "(#{@timeSheetRecord.planRemaining}d) "
              end
            else
              rText += "'''End:''' " +
                "#{@timeSheetRecord.actualEnd.to_s(query.timeFormat)} "
              if @timeSheetRecord.actualEnd != @timeSheetRecord.planEnd
                rText += "(#{@timeSheetRecord.planEnd.to_s(query.timeFormat)}) "
              end
            end
            rText += "\n\n"
          end
        elsif !(@timeSheetRecord = @timeSheetRecord).nil? &&
              @timeSheetRecord.task.is_a?(String)
          # There is only an entry in the timesheet, but we don't have a
          # corresponding Task in the Project. This must be a new task created
          # by the timesheet submitter.
          rText += "#{hlMark} #{alertName} <nowiki>[New Task] " +
                   "#{@timeSheetRecord.name}</nowiki>"
          if query.journalAttributes.include?('propertyid')
            rText += " (ID: #{@timeSheetRecord.task})"
          end
          rText += " #{hlMark}\n\n"

          if query.journalAttributes.include?('timesheet') && @timeSheetRecord
            # We don't have any plan data since it's a new task. Just include
            # the reported time sheet actuals.
            rText += "'''Work:''' #{@timeSheetRecord.actualWorkPercent}% "
            if @timeSheetRecord.remaining
              rText += "'''Remaining:''' #{@timeSheetRecord.actualRemaining}d "
            else
              rText += "'''End:''' " +
                       "#{@timeSheetRecord.actualEnd.to_s(query.timeFormat)} "
            end
            rText += "\n\n"
          end
        else
          # Property must be a Resource
          rText += "#{hlMark} #{alertName} Personal Notes #{hlMark}\n\n"
        end

        # We've shown the alert now. Don't show it again with the headline.
        alertName = ''
        # Increase level for subsequent headlines.
        hlMark += '='
      end

      if query.journalAttributes.include?('headline')
        rText += "#{hlMark} #{alertName}<nowiki>" + @headline +
                 "</nowiki> #{hlMark}\n\n"
      end

      showDate = query.journalAttributes.include?('date')
      showAuthor = query.journalAttributes.include?('author') && @author
      if showDate || showAuthor
        rText += "''Reported "
      end
      if showDate
        rText += "on #{@date.to_s(query.timeFormat)} "
      end
      if showAuthor
        rText += "by <nowiki>#{@author.name}</nowiki>"
      end
      rText += "''\n\n" if showDate || showAuthor

      if query.journalAttributes.include?('flags') && !@flags.empty?
        rText += "''Flags:'' #{@flags.join(', ')}\n\n"
      end

      if query.journalAttributes.include?('summary') && @summary
        rText += @summary.richText.inputText + "\n\n"
      end
      if query.journalAttributes.include?('details') && @details
        rText += @details.richText.inputText + "\n\n"
      end
      rText
    end

[Validate]