mingle-macro-development-toolkit 1.0

data/lib/macro_development_toolkit.rb

@@ -0,0 +1,22 @@
+#Copyright 2008 ThoughtWorks, Inc.  All rights reserved.
+
+$:.unshift(File.dirname(__FILE__)) unless
+  $:.include?(File.dirname(__FILE__)) || $:.include?(File.expand_path(File.dirname(__FILE__)))
+
+module MacroDevelopmentToolkit
+  VERSION = '1.0'
+end
+
+require 'yaml'
+require 'ostruct'
+require 'net/http'
+begin
+  require 'rubygems'
+rescue Exception
+  #ignore
+end    
+require 'active_support'
+
+Dir.glob(File.join("#{File.dirname(__FILE__)}", 'macro_development_toolkit', '**', '*')).reverse.each do |f| 
+  require f unless File.directory?(f)
+end

data/lib/macro_development_toolkit/mingle/card_type.rb

@@ -0,0 +1,41 @@
+module Mingle
+  #Copyright 2008 ThoughtWorks, Inc.  All rights reserved.    
+  
+  #This is a lightweight representation of a card type in Mingle.
+  #From an instance of this class you can the name, color and position of the card type, 
+  #in addition to Property Definitions that are associated with it.
+  class CardType
+    
+    def initialize(full_card_type)
+      @full_card_type = full_card_type
+    end
+    
+    # *returns*: The name of this CardType
+    def name
+      @full_card_type.name
+    end
+    
+    # *returns*: The hex color code for this CardType
+    def color
+      @full_card_type.color.gsub('#', '')
+    end
+
+    # *returns*: The position of this CardType among all the CardTypes on the project.
+    # The first card type has position 1
+    def position
+      @full_card_type.position
+    end
+    
+    # *returns*: The PropertyDefinitions associated with this CardType
+    def property_definitions
+      @card_types_property_definitions_loader.load.collect(&:property_definition)
+    end
+    
+    def to_s
+      "CardType[name=#{name},color=#{color},position=#{position}]"
+    end
+    
+    attr_writer :card_types_property_definitions_loader
+  end
+  
+end

data/lib/macro_development_toolkit/mingle/card_type_property_definition.rb

@@ -0,0 +1,26 @@
+module Mingle
+  #Copyright 2008 ThoughtWorks, Inc.  All rights reserved.    
+  
+  #This is a lightweight representation of the relationship between a card_type 
+  #and a property definition as configured in Mingle.
+  class CardTypePropertyDefinition
+    def initialize(card_type_property_definition)
+      @card_type_property_definition = card_type_property_definition
+    end  
+    
+    def position
+      @card_type_property_definition.position.to_i
+    end  
+
+    def card_type
+      @card_type_loader.load
+    end  
+
+    def property_definition
+      @property_definition_loader.load
+    end
+
+    attr_writer :card_type_loader, :property_definition_loader
+  end
+  
+end

data/lib/macro_development_toolkit/mingle/project.rb

@@ -0,0 +1,80 @@
+module Mingle
+  #Copyright 2008 ThoughtWorks, Inc.  All rights reserved.
+  
+  #This is a lightweight representation of a project.
+  #From an instance of this class you can the name & identifier of the project.
+  #You can also get a list of property definitions and card types on the project,
+  #in addition to information about the team and project variables.
+  #This class also provides an interface to the MQL execution facilities provided by Mingle.
+  class Project
+    
+    def initialize(project, card_query_options)
+      @full_project = project
+      @card_query_options = card_query_options
+    end
+    
+    # *returns*: The identifier of this project
+    def identifier
+      @full_project.identifier
+    end
+  
+    # *returns*: The name of this project
+    def name
+      @full_project.name
+    end
+    
+    # *returns*: A list CardTypes as configured for this project.
+    # There will always be atleast one element in this array.
+    def card_types
+      @card_types_loader.load
+    end
+    
+    # *returns*: An list of PropertyDefinitions as configured for this project. 
+    # This array may be empty
+    def property_definitions
+      @property_definitions_loader.load
+    end
+
+    # *accepts*: The name of a project variable configured for this project
+    #
+    # *returns*: The display value of the PropertyValue(s) that project_variable_name represents
+    def value_of_project_variable(project_variable_name)
+      @project_variables_loader.load.detect { |pv| pv.name == project_variable_name }.value
+    end
+    
+    # *accepts*: A valid MQL string. To see what constitutes valid MQL, 
+    # look here[http://studios.thoughtworks.com/mingle-agile-project-management/2.2/help/index.html]
+    # 
+    # *returns*: The display value of the PropertyValue(s) that project_variable_name represents
+    def execute_mql(mql)
+      CardQuery.parse(mql, @card_query_options).values
+    end
+    
+    # *returns*: The full list of Users who are members of this project
+    def team
+      @team_loader.load
+    end
+      
+    # *accepts*: Any Number
+    # 
+    # *returns*: The number formatted to the precision configured for the project (default 2)
+    def format_number_with_project_precision(number)
+      @full_project.to_num(number)
+    end
+
+    # *accepts*: Any Number
+    # 
+    # *returns*: The number formatted to the precision configured for the project (default 2)
+    def format_date_with_project_date_format(date)
+      @full_project.format_date(date)
+    end
+
+    attr_writer :card_types_loader, :property_definitions_loader, :team_loader, :project_variables_loader
+    
+    private
+    def add_alert(message)
+      @card_query_options[:alert_receiver].alert(message) if @card_query_options[:alert_receiver]
+    end  
+  end
+  
+end

data/lib/macro_development_toolkit/mingle/project_variable.rb

@@ -0,0 +1,23 @@
+module Mingle
+  #Copyright 2008 ThoughtWorks, Inc.  All rights reserved.
+  
+  #This is a lightweight representation of a ProjectVariable in Mingle
+  #which is a mnemonic that represents a particular value for multiple PropertyDefinitions
+  class ProjectVariable
+  
+    def initialize(full_project_variable)
+      @full_project_variable = full_project_variable
+    end
+    
+    # *returns*: The name of this variable
+    def name
+      @full_project_variable.name
+    end
+  
+    # *returns*: The display value of the value configured for this project variable
+    def value
+      @full_project_variable.value
+    end
+  end
+  
+end

data/lib/macro_development_toolkit/mingle/property_definition.rb

@@ -0,0 +1,94 @@
+module Mingle
+  #Copyright 2008 ThoughtWorks, Inc.  All rights reserved.
+
+  #This is a lightweight representation of a ProjectDefinition in Mingle
+  class PropertyDefinition
+    
+    MANAGED_TEXT_TYPE = "Managed text list"
+    ANY_TEXT_TYPE = "Any text"
+    MANAGED_NUMBER_TYPE = "Managed number list"
+    ANY_NUMBER_TYPE = "Any number"
+    DATE_TYPE = "Date"
+    FORMULA_TYPE = "Formula"
+    USER_TYPE = "Automatically generated from the team list"
+    CARD_TYPE = "Card"
+    AGGREGATE_TYPE = "Aggregate"
+    TREE_RELATIONSHIP_TYPE = "Used in card tree"
+        
+    def initialize(full_property_definition)
+      @full_property_definition = full_property_definition
+    end
+    
+    # *returns*: The name of this PropertyDefinition
+    def name
+      @full_property_definition.name
+    end
+    
+    # *returns*: The description of this PropertyDefinition
+    def description
+      @full_property_definition.description
+    end
+    
+    # *returns*: A list of CardTypes that this PropertyDefinition is valid for
+    def card_types
+      @card_types_property_definitions_loader.load.collect(&:card_type).sort_by(&:position)
+    end
+
+    # *returns*: A 
+    def type_description
+      @full_property_definition.type_description
+    end  
+    
+    # *returns*: A list of explicitly defined values that this PropertyDefinition has
+    # This method should ONLY be called for property definitions that are of the following types
+    # - MANAGED_TEXT_TYPE
+    # - MANAGED_NUMBER_TYPE
+    # - USER_TYPE
+    #
+    # Attempting to call this method for the following types will throw an Exception
+    # - ANY_TEXT_TYPE
+    # - ANY_NUMBER_TYPE
+    # - FORMULA_TYPE
+    # - AGGREGATE_TYPE
+    # - CARD_TYPE
+    # - TREE_RELATIONSHIP_TYPE
+    # - DATE_TYPE
+    # 
+    # To get the values for the above types, you can use MQL, such as "SELECT property_name" to get
+    # a list of values
+    def values
+      valid_property_types_to_call_value_on = [MANAGED_TEXT_TYPE, MANAGED_NUMBER_TYPE, USER_TYPE]
+      unless valid_property_types_to_call_value_on.any? {|t| self.type_description == t}
+        raise "Do not call this method for property definitions of types other than MANAGED_TEXT_TYPE, MANAGED_NUMBER_TYPE, USER_TYPE." 
+      end  
+      @values_loader.load
+    end
+
+    # *returns*: True if a property definition has only textual values, such as ones of Un/managed text types
+    def textual?
+      type_description == MANAGED_TEXT_TYPE || type_description == ANY_TEXT_TYPE
+    end  
+    
+    # *returns*: True if a property definition has only numeric values, such as ones of Un/managed number types
+    def numeric?
+      type_description == MANAGED_NUMBER_TYPE || type_description == ANY_NUMBER_TYPE
+    end  
+    
+    # *returns*: True if a property definition has only calculated values, such as ones of Formula & Aggregate types 
+    def calculated?
+      type_description == FORMULA_TYPE || type_description == AGGREGATE_TYPE
+    end  
+    
+    # *returns*: True if a property definition has only numeric values, such as the Date type
+    def date?
+      type_description == DATE_TYPE
+    end
+    
+    def to_s
+      "PropertyDefinition[name=#{name},type=#{type}]"
+    end
+    
+    attr_writer :card_types_property_definitions_loader, :values_loader
+  end
+  
+end

data/lib/macro_development_toolkit/mingle/property_value.rb

@@ -0,0 +1,68 @@
+module Mingle
+  
+  #Copyright 2008 ThoughtWorks, Inc.  All rights reserved.
+  
+  class PropertyValue
+    
+    def initialize(property_value)
+      @property_value = property_value
+    end
+  
+    # *returns*: The display value of this value
+    # Use the result of this method to display this value on the UI
+    # For the various property types, the following are the values you can expect to see
+    # * Managed/Unmanaged text    : The string value of the value
+    # * Managed/Unmanaged numeric : The numeric string representation of the value
+    # * Date                      : The list of values this property has on all cards on the project, formatted using the project date format
+    # * User                      : The name of the user
+    # * Formula                   : Either the date or the numeric value, formatted as above
+    # * Card                      : The number of the card, followed by the name of the card
+    def display_value
+      @property_value.display_value
+    end
+  
+    # *returns*: The identifier that is used to represent this value in the database
+    # You will most likely not have to use this value in your macros
+    # For the various property types, the following are the values you can expect to see
+    # * Managed/Unmanaged text    : The string value of the value
+    # * Managed/Unmanaged numeric : The numeric string representation of the value
+    # * Date                      : The canonical date format, as stored in the database
+    # * User                      : The id of the user in the database
+    # * Formula                   : Either the date or the numeric value, formatted as above
+    # * Card                      : The id of the card in the database
+    def db_identifier
+      @property_value.db_identifier
+    end
+  
+    # *returns*: A representation of this value that is unique and representable in a URL
+    # Use the result of this method if in any links that you want to build to point back into Mingle
+    # For the various property types, the following are the values you can expect to see
+    # * Managed/Unmanaged text    : The string value of the value
+    # * Managed/Unmanaged numeric : The numeric string representation of the value
+    # * Date                      : The list of values this property has on all cards on the project, formatted using the project date format
+    # * User                      : The login of the user
+    # * Formula                   : Either the date or the numeric value, formatted as above
+    # * Card                      : The number of the card, followed by the name of the card
+    def url_identifier
+      @property_value.url_identifier
+    end
+  
+    # *returns*: The hex color code for this PropertyValue
+    def color
+      @property_value.color.gsub('#', '')
+    end
+
+    # *returns*: The PropertyDefinition that this value belongs to
+    def property_definition
+      @property_definition_loader.load
+    end  
+  
+    def to_s
+      "PropertyValue[display_value=#{display_value},db_identifier=#{db_identifier},url_identifier=#{url_identifier}]"
+    end
+
+    attr_writer :property_definition_loader
+    
+  end
+      
+end

data/lib/macro_development_toolkit/mingle/user.rb

@@ -0,0 +1,29 @@
+module Mingle
+
+   #Copyright 2008 ThoughtWorks, Inc.  All rights reserved.
+  
+    class User
+        
+    def initialize(full_user)
+      @full_user = full_user
+    end
+    
+    def login
+      @full_user.login
+    end
+    
+    def name
+      @full_user.name
+    end
+    
+    def version_control_user_name
+      @full_user.version_control_user_name
+    end
+    
+    def email
+      @full_user.email
+    end
+  
+  end
+  
+end

data/lib/macro_development_toolkit/mingle_model_loader.rb

@@ -0,0 +1,169 @@
+#Copyright 2008 ThoughtWorks, Inc.  All rights reserved.
+
+#MingleModelLoaders understand how to load a graph of lightweight objects from
+#the Mingle model objects at runtime, when the custom macro is deployed into production.
+module MingleModelLoaders
+  class Base
+    def initialize(project, macro_context=nil, alert_receiver=nil)
+      @project = project
+      @macro_context = macro_context
+      @alert_receiver = alert_receiver
+    end
+
+    def card_types_property_definitions_by_card_type_id_loader(card_type_id)
+      LoadCardTypesPropertyDefinitionsByCardTypeId.new(card_type_id, @project)
+    end  
+  
+    def card_types_property_definitions_by_property_definition_id_loader(property_definition_id)
+      LoadCardTypesPropertyDefinitionsByPropertyDefinitionId.new(property_definition_id, @project)
+    end
+  
+    def values_by_property_definition_id_loader(property_definition_id)
+      LoadValuesByPropertyDefinitionId.new(property_definition_id, @project)
+    end  
+
+    def card_type_by_id_loader(card_type_id)
+      LoadCardTypeById.new(card_type_id, @project)
+    end
+  
+    def property_definition_by_id_loader(property_definition_id)
+      LoadPropertyDefinitionById.new(property_definition_id, @project)
+    end
+    
+    def card_types_by_project_id_loader
+      LoadCardTypesByProjectId.new(@project)
+    end  
+
+    def property_definitions_by_project_id_loader
+      LoadPropertyDefinitionsByProjectId.new(@project)
+    end  
+    
+    def team_by_project_id_loader
+      LoadTeamByProjectId.new(@project)
+    end
+    
+    def project_variables_by_project_id_loader
+      LoadProjectVariablesByProjectId.new(@project)
+    end    
+  end
+
+  class ProjectLoader < Base
+    def project
+      project = Mingle::Project.new(@project, :content_provider => @macro_context[:content_provider], :alert_receiver => @alert_receiver)
+      project.card_types_loader = card_types_by_project_id_loader
+      project.property_definitions_loader = property_definitions_by_project_id_loader
+      project.team_loader = team_by_project_id_loader
+      project.project_variables_loader = project_variables_by_project_id_loader
+      project
+    end
+  end
+
+  class LoadCardTypesByProjectId < Base
+    def load
+      @project.card_types.collect do |ct|
+        card_type = Mingle::CardType.new(ct)
+        card_type.card_types_property_definitions_loader = card_types_property_definitions_by_card_type_id_loader(ct.id)
+        card_type
+      end.sort_by(&:position)
+    end  
+  end
+
+  class LoadPropertyDefinitionsByProjectId < Base
+    def load
+      @project.all_property_definitions.collect do |pd|
+        property_definition = Mingle::PropertyDefinition.new(pd)
+        property_definition.card_types_property_definitions_loader = card_types_property_definitions_by_property_definition_id_loader(pd.id)
+        property_definition.values_loader = values_by_property_definition_id_loader(pd.id)
+        property_definition
+      end
+    end  
+  end
+
+  class LoadCardTypesPropertyDefinitionsByCardTypeId < Base
+    def initialize(card_type_id, fixture_file_name)
+      super(fixture_file_name)
+      @card_type_id = card_type_id
+    end  
+  
+    def load
+      @project.card_types.find(@card_type_id).card_types_property_definitions.collect do |ctpd|
+        card_type_property_definition = Mingle::CardTypePropertyDefinition.new(ctpd)
+        card_type_property_definition.card_type_loader = card_type_by_id_loader(ctpd.card_type_id)
+        card_type_property_definition.property_definition_loader = property_definition_by_id_loader(ctpd.property_definition_id)
+        card_type_property_definition
+      end.sort_by(&:position).compact
+    end  
+
+  end  
+
+  class LoadCardTypesPropertyDefinitionsByPropertyDefinitionId < Base
+    def initialize(property_definition_id, fixture_file_name)
+      super(fixture_file_name)
+      @property_definition_id = property_definition_id
+    end  
+
+    def load
+      @project.all_property_definitions.detect { |pd| pd.id == @property_definition_id }.card_types_property_definitions do |ctpd|
+        card_type_property_definition = Mingle::CardTypePropertyDefinition.new(ctpd)
+        card_type_property_definition.card_type_loader = card_type_by_id_loader(ctpd.card_type_id)
+        card_type_property_definition.property_definition_loader = property_definition_by_id_loader(ctpd.property_definition_id)
+        card_type_property_definition
+      end.compact.sort_by(&:position).compact
+    end  
+
+  end
+
+  class LoadCardTypeById < Base
+    def initialize(card_type_id, fixture_file_name)
+      super(fixture_file_name)
+      @card_type_id = card_type_id
+    end  
+
+    def load
+      ct = Mingle::CardType.new(@project.card_types.find(@card_type_id))
+      ct.card_types_property_definitions_loader = card_types_property_definitions_by_card_type_id_loader(@card_type_id)
+      ct
+    end  
+  end  
+
+  class LoadPropertyDefinitionById < Base
+    def initialize(property_definition_id, fixture_file_name)
+      super(fixture_file_name)
+      @property_definition_id = property_definition_id
+    end
+
+    def load
+      pd = Mingle::PropertyDefinition.new(@project.all_property_definitions.detect { |pd| pd.id == @property_definition_id })
+      pd.card_types_property_definitions_loader = card_types_property_definitions_by_property_definition_id_loader(@property_definition_id)
+      pd.values_loader = values_by_property_definition_id_loader(@property_definition_id)
+      pd
+    end  
+  end
+
+  class LoadValuesByPropertyDefinitionId < Base
+    def initialize(property_definition_id, fixture_file_name)
+      super(fixture_file_name)
+      @property_definition_id = property_definition_id
+    end
+  
+    def load
+      @project.all_property_definitions.detect { |pd| pd.id == @property_definition_id }.light_property_values.collect do |pv|
+        property_value = Mingle::PropertyValue.new(pv) 
+        property_value.property_definition_loader = property_definition_by_id_loader(@property_definition_id)
+        property_value
+      end.compact
+    end  
+  end
+  
+  class LoadTeamByProjectId < Base
+    def load
+      @project.users.collect { |user| Mingle::User.new(user) }
+    end  
+  end
+
+  class LoadProjectVariablesByProjectId < Base
+    def load
+      @project.project_variables.collect { |plv| Mingle::ProjectVariable.new(plv) }
+    end  
+  end
+end