class TaskJuggler::JournalEntry

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.

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

new(journal, date, headline, property, sourceFileInfo = nil) click to toggle source

Create a new JournalEntry object.

# File lib/taskjuggler/Journal.rb, line 31
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

to_rText(query) click to toggle source

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

# File lib/taskjuggler/Journal.rb, line 65
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