mingle_macro_models 1.3.4

data/lib/mingle_macro_models.rb

@@ -0,0 +1,5 @@
+#Copyright 2012 ThoughtWorks, Inc.  All rights reserved.
+
+Dir.glob(File.join(File.dirname(__FILE__), "mingle_macro_models", "*.rb")).each do |file|
+  require file
+end

data/lib/mingle_macro_models/card_type.rb

@@ -0,0 +1,41 @@
+module Mingle
+  # Copyright 2009 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/mingle_macro_models/card_type_property_definition.rb

@@ -0,0 +1,26 @@
+module Mingle
+  # Copyright 2010 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/mingle_macro_models/project.rb

@@ -0,0 +1,168 @@
+module Mingle
+  # Copyright 2010 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
+    
+    VERSION_ONE = 'v1'
+    VERSION_TWO = 'v2'
+    
+    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 at least one element in this list.
+    def card_types
+      @card_types_loader.load.collect(&:card_type)
+    end
+    
+    # *returns*: An list of PropertyDefinitions as configured for this project, which may be empty
+    def property_definitions
+      @property_definitions_loader.load.collect(&:property_definition)
+    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/3.0/help/index.html]
+    # 
+    # *returns*: An Array of Hashes, in which each Hash represents one row of results from the MQL execution
+    # The keys in the Hash are the names of the properties selected, with all the alphanumeric characters
+    # downcased and all the spaces and special characters replaced with underscores(_).
+    # 
+    # Executing a mql statement with explictly supplied property names will return results as follows
+    # mql = select number,"defect status" where type=defect
+    #
+    # [
+    #   {"number"=>"106", "defect_status"=>"Fixed"}, 
+    #   {"number"=>"70", "defect_status"=>"Fixed"}, 
+    #   {"number"=>"69", "defect_status"=>"New"}, 
+    #   {"number"=>"68", "defect_status"=>"In Progress"},
+    #   ...
+    #   ...
+    # ]
+    #
+    # If aggregate functions are selected, the values look as below
+    # mql = select "defect status", count(*) where type=defect group by "defect status"
+    #
+    # [
+    #   {"count"=>"14", "defect_status"=>"New"}, 
+    #   {"count"=>"3", "defect_status"=>"Open"}, 
+    #   {"count"=>"1", "defect_status"=>"In Progress"}, 
+    #   {"count"=>"2", "defect_status"=>"Fixed"}, 
+    #   {"count"=>"1", "defect_status"=>"Closed"}
+    # ]
+    #
+    # If no columns are explicitly provided, the results contain the raw column names specific
+    # properties. It is not possible to interpret these results in the general case with the current
+    # version of the macro development toolkit, so this is not a particularly useful form of
+    # MQL to execute. The documentation here is provided here just for completeness and should
+    # not be used as a recommended way of using this call. The structure of this response is
+    # subject to change in future versions of the toolkit.
+    #
+    # mql = type=defect
+    #
+    # {
+    #   "cp_testing_status"=>"Ready to Be Tested", 
+    #   "cp_actual_effort"=>nil, 
+    #   "created_at"=>"2009-09-09 21:45:34", 
+    #   "cp_story_count"=>nil, 
+    #   "caching_stamp"=>"2", 
+    #   "cp_release_card_id"=>"2", 
+    #   "cp_risk_liklihood"=>nil, 
+    #   "cp_build_completed"=>"452", 
+    #   "cp_closed"=>nil, 
+    #   "has_macros"=>"f", 
+    #   "description"=>"", 
+    #   "cp_release_start_date"=>nil, 
+    #   "cp_risk_status"=>nil, 
+    #   "cp_story_time_to_life"=>nil, 
+    #   "cp_total_open_iterations"=>nil, 
+    #   "cp_defect_time_to_life"=>"50.00", 
+    #   "cp_development_started_on"=>nil, 
+    #   "card_type_name"=>"Defect", 
+    #   "cp_added_to_scope_on"=>nil, 
+    #   "cp_owner_user_id"=>nil, 
+    #   "cp_added_to_scope_card_id"=>nil, 
+    #   "cp_type_of_test"=>nil, 
+    #   "cp_velocity"=>nil, 
+    #   "cp_feature_card_id"=>"60"
+    # }
+    #
+    # Note: In versions of the toolkit beyond 1.3, the keys for the aggregate function 
+    # (such as COUNT, SUM etc.) have been normalized to follow the same conventions as a 
+    # property name, i.e. lowecase and stripped of all spaces. 
+    # If you wish to get the results in the old form, set the optional second parameter
+    # of this call to be Project::VERSION_ONE, while you transition your macros to use the new form.
+    # The old version of response will be deprecated in a future version of Mingle and the toolkit.
+    def execute_mql(mql, version = VERSION_TWO)
+      @full_project.with_active_project do
+        CardQuery.parse(mql, @card_query_options).values_for_macro(:api_version => version)
+      end
+    end
+    
+    # The macros on a page determine whether the page content is cached.  Macros that use certain MQL concepts
+    # (for example TODAY, CURRENT USER, or cross-project functionality) should report that they cannot be
+    # cached so that the page they are on is not cached.  This method indicates whether a MQL query uses
+    # those concepts, and can be used by a macro to determine whether or not to report that it should be
+    # cached.
+    #
+    # *accepts*: A valid MQL string. To see what constitutes valid MQL, 
+    # look here[http://studios.thoughtworks.com/mingle-agile-project-management/3.0/help/index.html]
+    # 
+    # *returns*: A boolean indicating whether the data pertaining to the MQL can be cached
+    def can_be_cached?(mql)
+      @full_project.with_active_project do
+        CardQuery.parse(mql, @card_query_options).can_be_cached?
+      end
+    end
+    
+    # *returns*: The full list of Users who are members of this project
+    def team
+      @team_loader.load
+    end
+      
+    # *accepts*: Any Number
+    # 
+    # *returns*: The argument 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 argument date formatted using the date format configured for the project
+    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/mingle_macro_models/project_variable.rb

@@ -0,0 +1,24 @@
+module Mingle
+  # Copyright 2009 ThoughtWorks, Inc.  All rights reserved.
+  
+  # This is a lightweight representation of a ProjectVariable in Mingle
+  # A property defintion is a mnemonic name that represents a particular 
+  # value for one or more 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.display_value
+    end
+  end
+  
+end

data/lib/mingle_macro_models/property_definition.rb

@@ -0,0 +1,105 @@
+module Mingle
+  # Copyright 2009 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 = "Any card used in 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 short description of the property definition.
+    # This will be one of the above values
+    # - MANAGED_TEXT_TYPE
+    # - ANY_TEXT_TYPE
+    # - MANAGED_NUMBER_TYPE
+    # - ANY_NUMBER_TYPE
+    # - DATE_TYPE
+    # - FORMULA_TYPE
+    # - USER_TYPE
+    # - CARD_TYPE
+    # - AGGREGATE_TYPE
+    # - TREE_RELATIONSHIP_TYPE
+    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/mingle_macro_models/property_value.rb

@@ -0,0 +1,67 @@
+module Mingle
+  
+  # Copyright 2009 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/mingle_macro_models/user.rb

@@ -0,0 +1,29 @@
+#Copyright 2012 ThoughtWorks, Inc.  All rights reserved.
+# A lightweight model of a user in Mingle.
+module Mingle
+  class User
+    def initialize(full_user)
+      @full_user = full_user
+    end
+
+    # *returns*: The login of the user as configured in Mingle
+    def login
+      @full_user.login
+    end
+
+    # *returns*: The full name of the user as configured in Mingle
+    def name
+      @full_user.name
+    end
+
+    # *returns*: The version control user name of the user as configured in Mingle
+    def version_control_user_name
+      @full_user.version_control_user_name
+    end
+
+    # *returns*: The email address of the user as configured in Mingle
+    def email
+      @full_user.email
+    end
+  end
+end

metadata

@@ -0,0 +1,72 @@
+--- !ruby/object:Gem::Specification 
+name: mingle_macro_models
+version: !ruby/object:Gem::Version 
+  hash: 19
+  prerelease: 
+  segments: 
+  - 1
+  - 3
+  - 4
+  version: 1.3.4
+platform: ruby
+authors: 
+- ThoughtWorks Inc
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2012-04-10 00:00:00 Z
+dependencies: []
+
+description: Wrapper models used by custom Mingle macros.
+email: support@thoughtworks.com
+executables: []
+
+extensions: []
+
+extra_rdoc_files: []
+
+files: 
+- lib/mingle_macro_models/card_type.rb
+- lib/mingle_macro_models/card_type_property_definition.rb
+- lib/mingle_macro_models/project.rb
+- lib/mingle_macro_models/project_variable.rb
+- lib/mingle_macro_models/property_definition.rb
+- lib/mingle_macro_models/property_value.rb
+- lib/mingle_macro_models/user.rb
+- lib/mingle_macro_models.rb
+homepage: https://rubygems.org/gems/mingle_macro_models
+licenses: 
+- MIT
+post_install_message: 
+rdoc_options: []
+
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  none: false
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      hash: 3
+      segments: 
+      - 0
+      version: "0"
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  none: false
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      hash: 3
+      segments: 
+      - 0
+      version: "0"
+requirements: []
+
+rubyforge_project: 
+rubygems_version: 1.8.19
+signing_key: 
+specification_version: 3
+summary: Wrapper models used by custom Mingle macros.
+test_files: []
+