mingle-macro-development-toolkit 1.2 → 1.3

data/History.txt

@@ -1,3 +1,8 @@
+== 1.3 September, 2009
+
+  * Multiple project support
+  * The execute_mql call is now versioned to support both old and new formats for results
+  
 == 1.2 April 16, 2009
   
   * Mingle 2.3 integration

data/LICENSE.txt

@@ -1,6 +1,6 @@
 The MIT License
 
-Copyright (c) 2008 ThoughtWorks, Inc.  All rights reserved.
+Copyright (c) 2009 ThoughtWorks, Inc.  All rights reserved.
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

data/README.rdoc

@@ -45,7 +45,7 @@ team over email at support@thoughtworks.com
 
 The MIT License
 
-Copyright (c) 2008 ThoughtWorks, Inc.  All rights reserved.
+Copyright (c) 2009 ThoughtWorks, Inc.  All rights reserved.
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

data/Rakefile

@@ -1,4 +1,4 @@
-#Copyright 2008 ThoughtWorks, Inc.  All rights reserved.
+#Copyright 2009 ThoughtWorks, Inc.  All rights reserved.
 
 begin
   require 'rubygems'
@@ -13,19 +13,21 @@ rescue LoadError
   exit 1
 end
 
-%w[rake rake/clean fileutils newgem rubigen].each { |f| require f }
+%w[rake rake/clean fileutils hoe newgem rubigen].each { |f| p "require #{f}"; require f }
 require File.dirname(__FILE__) + '/lib/macro_development_toolkit'
 
 # Generate all the Rake tasks
 # Run 'rake -T' to see list of generated tasks (from gem root directory)
-$hoe = Hoe.new('mingle-macro-development-toolkit', MacroDevelopmentToolkit::VERSION) do |p|
+$hoe = Hoe.spec('mingle-macro-development-toolkit') do |p|
+  p.version = MacroDevelopmentToolkit::VERSION
   p.developer('ThoughtWorks Inc', 'support@thoughtworks.com')
   p.post_install_message = 'getting_started.txt'
   p.rubyforge_name       = 'mingle-macros'
   p.extra_deps         = [
     ['activesupport','>= 2.0.2'],
   ]
-  p.rdoc_pattern = /README|(lib\/macro_development_toolkit\/mingle(?!_))/
+  p.summary = "This toolkit provides support for developing, testing and deploying custom Mingle macros."
+  p.extra_rdoc_files = ['README.rdoc']
   p.clean_globs |= %w[**/.DS_Store tmp *.log]
   path = (p.rubyforge_name == p.name) ? p.rubyforge_name : "\#{p.rubyforge_name}/\#{p.name}"
   p.remote_rdoc_dir = ''

data/bin/new_mingle_macro

@@ -1,5 +1,5 @@
 #!/usr/bin/env ruby
-#Copyright 2008 ThoughtWorks, Inc.  All rights reserved.
+#Copyright 2009 ThoughtWorks, Inc.  All rights reserved.
 
 require 'erb'
 begin

data/example/Rakefile

@@ -1,3 +1,6 @@
 %w[rubygems rake rake/clean rake/testtask fileutils macro_development_toolkit].each { |f| require f }
 
 Dir['tasks/**/*.rake'].each { |t| load t }
+
+desc "Runs all units and integration tests"
+task :test => ['test:units', 'test:integration']

data/example/integration_test.rb

@@ -1,15 +1,27 @@
 require File.dirname(__FILE__) + '/integration_test_helper.rb'
 
-# The Mingle API supports basic authentication and must be used in order to run integration tests. However it is disabled in the default configuration. To enable basic authentication, you need set the basic_authentication_enabled configuration option to true in the Mingle data directory/config/auth_config.yml file where Mingle data directory is the path to the mingle data directory on your installation e.g.basic_authentication_enabled: true.
+# The Mingle API supports basic authentication and must be used in order to run integration tests. 
+# However it is disabled in the default configuration. To enable basic authentication, 
+# you need set the basic_authentication_enabled configuration option to true in the 
+# <mingle_data_directory>/config/auth_config.yml file where <mingle_data_directory> is the path 
+# to the mingle data directory on your installation e.g.
+# basic_authentication_enabled: true.
 
 class <%= macro_class_name %>IntegrationTest < Test::Unit::TestCase
   
   PROJECT_RESOURCE = 'http://username:password@your.mingle.server:port/lightweight_projects/your_project_identifier.xml'
-
+  ANOTHER_PROJECT_RESOURCE = 'http://username:password@your.mingle.server:port/lightweight_projects/another_project_identifier.xml'
+  
   def test_macro_contents
     <%= macro_name %> = <%= macro_class_name %>.new(nil, project(PROJECT_RESOURCE), nil)
     result = <%= macro_name %>.execute
     assert result
   end
+  
+  def test_macro_contents_with_a_project_group
+    <%= macro_name %> = <%= macro_class_name %>.new(nil, [project(PROJECT_RESOURCE), project(ANOTHER_PROJECT_RESOURCE)], nil)
+    result = <%= macro_name %>.execute
+    assert result
+  end
 
 end

data/example/integration_test_helper.rb

@@ -1,19 +1,31 @@
+require 'delegate'
 require 'test/unit'
 require File.join(File.dirname(__FILE__), '..', '..', 'init.rb')
 require File.join(File.dirname(__FILE__), '..', '..', 'lib', '<%= macro_name %>')
 require File.join(File.dirname(__FILE__), 'rest_loader')
 
 class Test::Unit::TestCase
-
+  
   def project(name)
-    @project ||= RESTfulLoaders::ProjectLoader.new(name, nil, self).project
-  end  
-
+    @project ||= load_project_resource(name)
+  end
+  
+  def projects(*resources)
+    @projects ||= resources.map{ |resource| load_project_resource(resource) }
+  end
+  
   def errors
     @errors ||= []
-  end  
+  end
   
   def alert(message)
     errors << message
   end
-end  
+  
+  private
+  
+  def load_project_resource(resource)
+    RESTfulLoaders::ProjectLoader.new(resource, nil, self).project
+  end
+  
+end

data/example/unit_test.rb

@@ -9,5 +9,11 @@ class <%= macro_class_name %>Test < Test::Unit::TestCase
     result = <%= macro_name %>.execute
     assert result
   end
+  
+  def test_macro_contents_with_a_project_group
+    <%= macro_name %> = <%= macro_class_name %>.new(nil, [project(FIXTURE), project(FIXTURE)], nil)
+    result = <%= macro_name %>.execute
+    assert result
+  end
 
 end

data/example/unit_test_helper.rb

@@ -6,7 +6,17 @@ require File.join(File.dirname(__FILE__), 'fixture_loader')
 class Test::Unit::TestCase
   
   def project(name)
-    @project ||= FixtureLoaders::ProjectLoader.new(name).project
-  end  
+    @project ||= load_project_fixture(name)
+  end
+  
+  def projects(*names)
+    @projects ||= names.map { |name| load_project_fixture(name) }
+  end
+  
+  private
+  
+  def load_project_fixture(name)
+    FixtureLoaders::ProjectLoader.new(name).project
+  end
    
 end

data/getting_started.txt

@@ -49,11 +49,15 @@ class AverageMacro
   end
 end
 
-All data that is required to execute the macro is injected into the macro through the constructor. The parameters that are interpreted from the markup are passed in as a hash. The project that is passed in is a lightweight representation of the project in the Mingle model, and is documented at http://mingle-macros.rubyforge.org/rdoc
+All data that is required to execute the macro is injected into the macro through the constructor. The parameters that are interpreted from the markup are passed in as a hash. 
+
+The second parameter is special and could be either a single project or multiple projects, based on the parameter name used in the macro. In versions 1.3 and above of the gem, a comma separated list of project identifiers when supplied as the value of a macro parameter called project-group will be interpretted as multiple projects. This functionality can be used to build macros that report across multiple projects. The project or projects that are passed in are a lightweight representation of the project in the Mingle model which is documented at http://mingle-macros.rubyforge.org/rdoc
 
 The execute method uses the MQL execution facility that the project class provides, to execute the MQL string that is passed into through the parameters hash. It then formats the results to be a number, and provides that result of the execute command.
 
-For more help on what constitutes valid MQL, you can refer to our help documentation at http://studios.thoughtworks.com/mingle-agile-project-management/2.3/help/mql_reference.html
+For more help on what constitutes valid MQL, you can refer to our help documentation at http://studios.thoughtworks.com/mingle-agile-project-management/3.0/help/mql_reference.html
+
+To see an example of how to use the gem to report across multiple projects, refer to the cross_project_rollup macro which ships with versions of Mingle 3.0 and higher.
 
 Writing your own macro
 ----------------------
@@ -103,9 +107,13 @@ will be parsed as YAML and handling will be delegated to an instance of your mac
 
 {'parameter1' => 'value1', 'parameter2' => '<some_mql_snippet>'}
 
-and will be passed into the constructor of the class, along with an instance of a Mingle::Project, that represents the project that this macro is being rendered on.
+and will be passed into the constructor of the class. Additionally, by default, an instance of Mingle::Project that represents the project that this macro is being rendered on will also be provided. You can specify a different project to be passed in by setting a project parameter in your macro. Also you can specify a group of projects to be provided to your macro by setting a project-group parameter. In this case the projects will be an array of Mingle::Project. You will also need to implement a class method called supports_project_group? which returns true if you want your macro to be used with project-group, for example:
+
+def self.supports_project_group?
+  true
+end
 
-As an example of what you can do with this information is the following macro, which uses the Google Charting API to render a Google-o-meter style chart to represent work completed in a fuel gauge style meter.
+As an example of what you can do with this toolkit is the following macro, which uses the Google Charting API to render a Google-o-meter style chart to represent work completed in a fuel gauge style meter.
 
 class WorkGauge
   
@@ -168,6 +176,9 @@ of macros use Javascript (or JSONP) to offload work to the browser.
 
 You can find both simpler and more complex examples in the vendor/plugins/sample_macros directory.
 
+Tip: If you wish to use JQuery, you will have to add a call to JQuery.noConflict() to prevent conflicts with the Prototype library that ships with Mingle. You can refer to the JQuery documentation here (http://docs.jquery.com/Core/jQuery.noConflict) to see the correct order in which to load the libraries and other conditions to be followed in order to make this work properly. If you do not do this, you can still use JQuery without using the $ shorthand for the jQuery function.
+
+
 Unit testing your macro
 ------------------------
 
@@ -204,7 +215,7 @@ Integration testing your macro
 
 ########################################################NOTE###############################################################
 #                                                                                                                         #
-# IN ORDER TO RUN THE INTEGRATION TESTS, YOU WILL NEED TO TURN ON BASIC AUTHENTICATION FOR THE MINGLE 2.3 SERVER THAT YOU # 
+# IN ORDER TO RUN THE INTEGRATION TESTS, YOU WILL NEED TO TURN ON BASIC AUTHENTICATION FOR THE MINGLE 3.0 SERVER THAT YOU # 
 # ARE GOING TO BE TESTING AGAINST.                                                                                        #
 #                                                                                                                         #
 #########################################################NOTE##############################################################
@@ -235,7 +246,7 @@ end
 
 The skeleton project also has a sample integration test set up for you, which points to a bogus Mingle server, and uses bad credentials. Replace this resource URL with the URL for a deployed instance within your organization. The helper method project(...) which takes the resource URL, loads the data from the XML data obtained from the live instance of Mingle. 
 
-You can see examples of integration tests in the average macro that is packaged with Mingle in the vendor/plugins/average_macro directory. These tests run against a standard template that ships with Mingle2.3, and so you should be able to run them within your organization too, without a problem.
+You can see examples of integration tests in the average macro that is packaged with Mingle in the vendor/plugins/average_macro directory. These tests run against a standard template that ships with Mingle 3.0, and so you should be able to run them within your organization too, without a problem.
 
 To run your integration tests, run 
 
@@ -267,7 +278,7 @@ To deploy your macro to a locally deployed instance of Mingle, which is running
 
 % rake macro:deploy MINGLE_LOCATION=/path/to/mingle_root
 
-where /path/to/mingle_root is the location where Mingle2.3 is installed. 
+where /path/to/mingle_root is the location where Mingle 3.0 is installed. 
 
 * On Windows, this is the location that the installer installed Mingle at
 * On OSX, this will be within the app bundle, at <mingle_application_bundle>/Contents/Resources/app

data/lib/macro_development_toolkit.rb

@@ -1,10 +1,10 @@
-#Copyright 2008 ThoughtWorks, Inc.  All rights reserved.
+# Copyright 2009 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.2'
+  VERSION = '1.3'
 end
 
 require 'yaml'

data/lib/macro_development_toolkit/mingle/card_type.rb

@@ -1,9 +1,9 @@
 module Mingle
-  #Copyright 2008 ThoughtWorks, Inc.  All rights reserved.    
+  # 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.
+  # 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)

data/lib/macro_development_toolkit/mingle/card_type_property_definition.rb

@@ -1,12 +1,12 @@
 module Mingle
-  #Copyright 2008 ThoughtWorks, Inc.  All rights reserved.    
+  # Copyright 2009 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.
+  # 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  
+    end
     
     def position
       @card_type_property_definition.position.to_i

data/lib/macro_development_toolkit/mingle/project.rb

@@ -1,13 +1,16 @@
 module Mingle
-  #Copyright 2008 ThoughtWorks, Inc.  All rights reserved.
+  # Copyright 2009 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.
+  # 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
@@ -24,13 +27,12 @@ module Mingle
     end
     
     # *returns*: A list CardTypes as configured for this project.
-    # There will always be atleast one element in this array.
+    # There will always be atleast one element in this list.
     def card_types
       @card_types_loader.load
     end
     
-    # *returns*: An list of PropertyDefinitions as configured for this project. 
-    # This array may be empty
+    # *returns*: An list of PropertyDefinitions as configured for this project, which may be empty
     def property_definitions
       @property_definitions_loader.load
     end
@@ -43,13 +45,81 @@ module Mingle
     end
     
     # *accepts*: A valid MQL string. To see what constitutes valid MQL, 
-    # look here[http://studios.thoughtworks.com/mingle-agile-project-management/2.3/help/index.html]
+    # 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 spaces and special characters replaced 
-    # with underscores(_). 
-    def execute_mql(mql)
-      CardQuery.parse(mql, @card_query_options).values
+    # 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
@@ -59,11 +129,13 @@ module Mingle
     # cached.
     #
     # *accepts*: A valid MQL string. To see what constitutes valid MQL, 
-    # look here[http://studios.thoughtworks.com/mingle-agile-project-management/2.3/help/index.html]
+    # 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)
-      CardQuery.parse(mql, @card_query_options).can_be_cached?
+      @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
@@ -73,14 +145,14 @@ module Mingle
       
     # *accepts*: Any Number
     # 
-    # *returns*: The number formatted to the precision configured for the project (default 2)
+    # *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 number formatted to the precision configured for the project (default 2)
+    # *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

data/lib/macro_development_toolkit/mingle/project_variable.rb

@@ -1,8 +1,9 @@
 module Mingle
-  #Copyright 2008 ThoughtWorks, Inc.  All rights reserved.
+  # Copyright 2009 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
+  # 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)

data/lib/macro_development_toolkit/mingle/property_definition.rb

@@ -1,7 +1,7 @@
 module Mingle
-  #Copyright 2008 ThoughtWorks, Inc.  All rights reserved.
+  # Copyright 2009 ThoughtWorks, Inc.  All rights reserved.
 
-  #This is a lightweight representation of a ProjectDefinition in Mingle
+  # This is a lightweight representation of a ProjectDefinition in Mingle
   class PropertyDefinition
     
     MANAGED_TEXT_TYPE = "Managed text list"
@@ -13,7 +13,7 @@ module Mingle
     USER_TYPE = "Automatically generated from the team list"
     CARD_TYPE = "Card"
     AGGREGATE_TYPE = "Aggregate"
-    TREE_RELATIONSHIP_TYPE = "Used in card tree"
+    TREE_RELATIONSHIP_TYPE = "Any card used in tree"
         
     def initialize(full_property_definition)
       @full_property_definition = full_property_definition
@@ -34,7 +34,18 @@ module Mingle
       @card_types_property_definitions_loader.load.collect(&:card_type).sort_by(&:position)
     end
 
-    # *returns*: A 
+    # *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  

data/lib/macro_development_toolkit/mingle/property_value.rb

@@ -1,7 +1,6 @@
 module Mingle
   
-  #Copyright 2008 ThoughtWorks, Inc.  All rights reserved.
-  
+  # Copyright 2009 ThoughtWorks, Inc.  All rights reserved.
   class PropertyValue
     
     def initialize(property_value)

data/lib/macro_development_toolkit/mingle/user.rb

@@ -1,25 +1,29 @@
 module Mingle
+    # Copyright 2009 ThoughtWorks, Inc.  All rights reserved.
 
-   #Copyright 2008 ThoughtWorks, Inc.  All rights reserved.
-  
+    # A lightweight model of a user in 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

data/lib/macro_development_toolkit/mingle_model_loader.rb

@@ -1,7 +1,7 @@
-#Copyright 2008 ThoughtWorks, Inc.  All rights reserved.
+# Copyright 2009 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.
+# 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)
@@ -60,21 +60,25 @@ module MingleModelLoaders
 
   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)
+      @project.with_active_project do
+        @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  
   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
+      @project.with_active_project do
+        @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  
   end
@@ -86,12 +90,14 @@ module MingleModelLoaders
     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
+      @project.with_active_project do
+        @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  
 
   end  
@@ -103,12 +109,14 @@ module MingleModelLoaders
     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
+      @project.with_active_project do
+        @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  
 
   end
@@ -120,9 +128,11 @@ module MingleModelLoaders
     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
+      @project.with_active_project do
+        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  
   end  
 
@@ -133,10 +143,12 @@ module MingleModelLoaders
     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
+      @project.with_active_project do
+        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  
   end
 
@@ -147,23 +159,29 @@ module MingleModelLoaders
     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
+      @project.with_active_project do
+        @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  
   end
   
   class LoadTeamByProjectId < Base
     def load
-      @project.users.collect { |user| Mingle::User.new(user) }
+      @project.with_active_project do
+        @project.users.collect { |user| Mingle::User.new(user) }
+      end
     end  
   end
 
   class LoadProjectVariablesByProjectId < Base
     def load
-      @project.project_variables.collect { |plv| Mingle::ProjectVariable.new(plv) }
+      @project.with_active_project do
+        @project.project_variables.collect { |plv| Mingle::ProjectVariable.new(plv) }
+      end
     end  
   end
 end

data/test/fixtures/sample/project_variables.yml

@@ -1,6 +1,5 @@
 --- 
 - name: Current Release
   display_value: 'Release 3'
-  
 - name: Current Sprint
   display_value: 'Iteration 7'

data/test/integration/integration_test_helper.rb

@@ -1,5 +1,6 @@
 #Copyright 2008 ThoughtWorks, Inc.  All rights reserved.
 
+require 'delegate'
 require 'test/unit'
 require 'macro_development_toolkit'
 require File.dirname(__FILE__) + '/rest_loader'

data/test/integration/rest_loader.rb

@@ -1,4 +1,4 @@
-#Copyright 2008 ThoughtWorks, Inc.  All rights reserved.
+#Copyright 2009 ThoughtWorks, Inc.  All rights reserved.
 
 module RESTfulLoaders
   class RemoteError < StandardError
@@ -41,7 +41,7 @@ module RESTfulLoaders
       load_all_card_types_from_xml.collect do |card_type_xml| 
         card_types_property_definitions = OpenStruct.new(card_type_xml).card_types_property_definitions
         [card_types_property_definitions['card_type_property_definition']].flatten if card_types_property_definitions
-      end.compact.flatten
+      end.compact.flatten.compact
     end  
 
     def card_types_property_definitions_by_card_type_id_loader(card_type_id)
@@ -123,6 +123,8 @@ module RESTfulLoaders
 
     def initialize(project_name, macro_context=nil, alert_receiver=nil)
       super(project_name)
+      project_name =~ /(\/api\/([^\/]*))\//
+      @api_version_name = $1
       @macro_context = macro_context
       @alert_receiver = alert_receiver
     end
@@ -144,28 +146,32 @@ module RESTfulLoaders
       from_xml_data(
         Hash.from_xml(
           get(
-            build_request_url(:path => "/projects/#{project.identifier}/cards/execute_mql.xml", :query => "mql=#{mql}"))))
+            build_request_url(:path => url_for("execute_mql"), :query => "mql=#{mql}"))))
     end
     
     def can_be_cached?(mql, project)
       from_xml_data(
         Hash.from_xml(
           get(
-          build_request_url(:path => "/projects/#{project.identifier}/cards/can_be_cached.xml", :query => "mql=#{mql}"))))
+            build_request_url(:path => url_for("can_be_cached"), :query => "mql=#{mql}"))))
     end
     
     def format_number_with_project_precision(number, project)
       from_xml_data(
         Hash.from_xml(
           get(
-            build_request_url(:path => "/projects/#{project.identifier}/cards/format_number_to_project_precision.xml", :query => "number=#{number}"))))
+            build_request_url(:path => url_for("format_number_to_project_precision"), :query => "number=#{number}"))))
     end
     
     def format_date_with_project_date_format(date, project)  
       from_xml_data(
         Hash.from_xml(
           get(
-            build_request_url(:path => "/projects/#{project.identifier}/cards/format_string_to_date_format.xml", :query => "date=#{date}"))))
+            build_request_url(:path => url_for("format_string_to_date_format"), :query => "date=#{date}"))))
+    end
+    
+    def url_for(action)
+      "#{@api_version_name}/projects/#{project.identifier}/cards/#{action}.xml"
     end
     
     def build_request_url(params)
@@ -188,7 +194,6 @@ module RESTfulLoaders
         data
       end
     end
-      
   end
 
   class LoadCardTypesByProjectId < Base

data/test/integration/rest_loader_test.rb

@@ -1,10 +1,11 @@
-#Copyright 2008 ThoughtWorks, Inc.  All rights reserved.
+#Copyright 2009 ThoughtWorks, Inc.  All rights reserved.
 
 require File.dirname(__FILE__) + '/integration_test_helper.rb'
 
 class RestLoaderTest < Test::Unit::TestCase
   
-  TEST_PROJECT = 'http://bjanakir:p@localhost:8080/lightweight_projects/scrum_template_2_3.xml'
+  TEST_PROJECT = 'http://bjanakir:p@localhost:8080/api/v2/lightweight_projects/scrum_template_2_3.xml'
+  TEST_PROJECT_V1 = "http://bjanakir:p@localhost:8080/api/v1/lightweight_projects/scrum_template_2_3.xml"
   
   def test_should_load_direct_project_attributes_from_correct_fixture
     assert_not_nil project(TEST_PROJECT)
@@ -43,32 +44,42 @@ class RestLoaderTest < Test::Unit::TestCase
     assert_equal '#21 Release 1', project(TEST_PROJECT).value_of_project_variable('Current Release')
   end  
 
-  def test_should_execute_mql_to_return_an_array_of_hash_results_for_each_result_row
+  def test_should_execute_mql_to_return_an_array_of_hash_results_for_each_result_row_for_v2
     mql_results = project(TEST_PROJECT).execute_mql("SELECT SUM('Estimate - planning') WHERE 'Planning - Release' = (Current Release) AND 'Added On' IS NOT NULL")
+    assert_equal 1, mql_results.size
+    assert_equal Hash, mql_results.first.class
+    assert_equal 86, mql_results.first['sum_estimate___planning'].to_i
+  end  
 
+  def test_should_execute_mql_to_return_an_array_of_hash_results_for_each_result_row_for_v1
+    mql_results = project(TEST_PROJECT_V1).execute_mql("SELECT SUM('Estimate - planning') WHERE 'Planning - Release' = (Current Release) AND 'Added On' IS NOT NULL")
     assert_equal 1, mql_results.size
     assert_equal Hash, mql_results.first.class
     assert_equal 86, mql_results.first['Sum_Estimate___Planning'].to_i
   end  
 
-  def test_should_execute_number_format_remotely
+  def test_should_execute_number_format_remotely_for_v2
     proj = project(TEST_PROJECT)
     assert_equal "3.67", proj.format_number_with_project_precision("3.6711").to_s
     assert_equal "20.14", proj.format_number_with_project_precision("20.1398").to_s
   end  
 
-  def test_should_execute_date_format_remotely
+  def test_should_execute_number_format_remotely_for_v1
+    proj = project(TEST_PROJECT_V1)
+    assert_equal "3.67", proj.format_number_with_project_precision("3.6711").to_s
+    assert_equal "20.14", proj.format_number_with_project_precision("20.1398").to_s
+  end  
+
+  def test_should_execute_date_format_remotely_for_v2
     proj = project(TEST_PROJECT)
     assert_equal "22 May 2005", proj.format_date_with_project_date_format(Date.new(2005, 5, 22))
     assert_equal "06 Oct 2008", proj.format_date_with_project_date_format(Date.new(2008, 10, 6))
   end  
 
-  def test_should_execute_mql_to_return_an_array_of_hash_results_for_each_result_row
-    mql_results = project(TEST_PROJECT).execute_mql("SELECT SUM('Estimate - planning') WHERE 'Planning - Release' = (Current Release) AND 'Added On' IS NOT NULL")
-
-    assert_equal 1, mql_results.size
-    assert_equal Hash, mql_results.first.class
-    assert_equal 86, mql_results.first['Sum_Estimate___Planning'].to_i
+  def test_should_execute_date_format_remotely_for_v1
+    proj = project(TEST_PROJECT_V1)
+    assert_equal "22 May 2005", proj.format_date_with_project_date_format(Date.new(2005, 5, 22))
+    assert_equal "06 Oct 2008", proj.format_date_with_project_date_format(Date.new(2008, 10, 6))
   end  
 
   def test_should_errors_in_executing_mql_should_be_available_in_the_test

data/test/unit/fixture_loader.rb

@@ -1,4 +1,5 @@
 #Copyright 2008 ThoughtWorks, Inc.  All rights reserved.
+require 'erb'
 
 module FixtureLoaders
   class Base
@@ -9,7 +10,7 @@ module FixtureLoaders
     end
   
     def load_fixtures_for(name)
-      YAML::load(File.open("#{@expanded_fixture}/#{name}.yml"))
+      YAML::load(ERB.new(File.read("#{@expanded_fixture}/#{name}.yml")).result(binding))
     end
   
     def card_types_property_definitions_by_card_type_id_loader(card_type_id)

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification 
 name: mingle-macro-development-toolkit
 version: !ruby/object:Gem::Version 
-  version: "1.2"
+  version: "1.3"
 platform: ruby
 authors: 
 - ThoughtWorks Inc
@@ -9,7 +9,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2009-04-16 00:00:00 -07:00
+date: 2009-12-04 00:00:00 -08:00
 default_executable: 
 dependencies: 
 - !ruby/object:Gem::Dependency 
@@ -30,7 +30,7 @@ dependencies:
     requirements: 
     - - ">="
       - !ruby/object:Gem::Version 
-        version: 1.8.0
+        version: 2.3.3
     version: 
 description: ""
 email: 
@@ -41,9 +41,9 @@ extensions: []
 
 extra_rdoc_files: 
 - getting_started.txt
-- README.rdoc
 - LICENSE.txt
 - History.txt
+- README.rdoc
 files: 
 - getting_started.txt
 - README.rdoc
@@ -82,11 +82,13 @@ files:
 - example/integration_test.rb
 - example/integration_test_helper.rb
 has_rdoc: true
-homepage: "This toolkit provides support for developing, testing and deploying custom Mingle macros. "
+homepage: 
+licenses: []
+
 post_install_message: getting_started.txt
 rdoc_options: 
 - --main
-- README.rdoc
+- README.txt
 require_paths: 
 - lib
 required_ruby_version: !ruby/object:Gem::Requirement 
@@ -104,9 +106,9 @@ required_rubygems_version: !ruby/object:Gem::Requirement
 requirements: []
 
 rubyforge_project: mingle-macros
-rubygems_version: 1.3.0
+rubygems_version: 1.3.5
 signing_key: 
-specification_version: 2
-summary: ""
+specification_version: 3
+summary: This toolkit provides support for developing, testing and deploying custom Mingle macros.
 test_files: []