mingle-macro-development-toolkit 1.3.3 → 2.0.0

data/lib/mingle_macro_development_toolkit/loaders/restful_loaders/card_type_loader.rb

@@ -0,0 +1,19 @@
+#Copyright 2012 ThoughtWorks, Inc.  All rights reserved.
+module RESTfulLoaders
+  class CardTypeLoader
+    def initialize(project, ct)
+      @project = project
+      @ct = ct
+    end
+
+    def card_type
+      @card_type ||= load
+    end
+
+    def load
+      card_type = Mingle::CardType.new(OpenStruct.new(@ct))
+      card_type.card_types_property_definitions_loader = CardTypesPropertyDefinitionsLoader.new(@project, 'card_type_id' => @ct['id'])
+      card_type
+    end
+  end
+end

data/lib/mingle_macro_development_toolkit/loaders/restful_loaders/card_types_loader.rb

@@ -0,0 +1,14 @@
+#Copyright 2012 ThoughtWorks, Inc.  All rights reserved.
+module RESTfulLoaders
+  class CardTypesLoader
+    include LoaderHelper
+
+    def initialize(project)
+      @project = project
+    end
+
+    def load
+      extract('card_types', @project).collect { |ct| CardTypeLoader.new(@project, ct) }.sort_by { |loader| loader.card_type.position }
+    end
+  end
+end

data/lib/mingle_macro_development_toolkit/loaders/restful_loaders/card_types_property_definitions_loader.rb

@@ -0,0 +1,32 @@
+#Copyright 2012 ThoughtWorks, Inc.  All rights reserved.
+module RESTfulLoaders
+  class CardTypesPropertyDefinitionsLoader
+    include LoaderHelper
+
+    def initialize(project, params)
+      @project = project
+      @params = params
+    end
+
+    def load
+      mappings = extract('card_types', @project).collect do |card_type|
+        mapping = card_type['card_types_property_definitions'].values
+      end.flatten
+
+      pds = extract('property_definitions', @project)
+      cts = extract('card_types', @project)
+      mappings.collect do |mapping|
+        if (match?(mapping))
+          pd = pds.find { |pd| pd['id'] && pd['id'] == mapping['property_definition_id'] }
+          ct = cts.find { |ct| ct['id'] == mapping['card_type_id'] }
+          OpenStruct.new(:card_type => CardTypeLoader.new(@project, ct).load, :property_definition => PropertyDefinitionLoader.new(@project, pd).load)
+        end
+      end.compact
+    end
+
+    private
+      def match?(mapping)
+        @params.all? { |key, value| value == mapping[key] }
+      end
+  end
+end

data/lib/mingle_macro_development_toolkit/loaders/restful_loaders/project_loader.rb

@@ -0,0 +1,26 @@
+#Copyright 2012 ThoughtWorks, Inc.  All rights reserved.
+module RESTfulLoaders
+  class ProjectLoader
+    include LoaderHelper
+
+    def initialize(resource, error_handler)
+      @resource = resource
+      @error_handler = error_handler
+    end
+
+    def project
+      @project ||= load
+    end
+
+    private
+      def load
+        proj = OpenStruct.new(get(@resource)).project
+        project = MqlExecutor.new(@resource, @error_handler, Mingle::Project.new(OpenStruct.new(proj), nil))
+        project.card_types_loader = CardTypesLoader.new(proj)
+        project.property_definitions_loader = PropertyDefinitionsLoader.new(proj)
+        project.team_loader = TeamLoader.new(proj)
+        project.project_variables_loader = ProjectVariablesLoader.new(proj)
+        project
+      end
+  end
+end

data/lib/mingle_macro_development_toolkit/loaders/restful_loaders/project_variables_loader.rb

@@ -0,0 +1,14 @@
+#Copyright 2012 ThoughtWorks, Inc.  All rights reserved.
+module RESTfulLoaders
+  class ProjectVariablesLoader
+    include LoaderHelper
+
+    def initialize(project)
+      @project = project
+    end
+
+    def load
+      extract('project_variables', @project).collect {|pv| Mingle::ProjectVariable.new(OpenStruct.new(pv))}
+    end
+  end
+end

data/lib/mingle_macro_development_toolkit/loaders/restful_loaders/property_definition_loader.rb

@@ -0,0 +1,20 @@
+#Copyright 2012 ThoughtWorks, Inc.  All rights reserved.
+module RESTfulLoaders
+  class PropertyDefinitionLoader
+    def initialize(project, pd)
+      @project = project
+      @pd = pd
+    end
+
+    def property_definition
+      @property_definition ||= load
+    end
+
+    def load
+      @property_definition = Mingle::PropertyDefinition.new(OpenStruct.new(@pd))
+      @property_definition.card_types_property_definitions_loader = CardTypesPropertyDefinitionsLoader.new(@project, 'property_definition_id' => @pd['id'])
+      @property_definition.values_loader = PropertyValuesLoader.new(@pd)
+      @property_definition
+    end
+  end
+end

data/lib/mingle_macro_development_toolkit/loaders/restful_loaders/property_definitions_loader.rb

@@ -0,0 +1,14 @@
+#Copyright 2012 ThoughtWorks, Inc.  All rights reserved.
+module RESTfulLoaders
+  class PropertyDefinitionsLoader
+    include LoaderHelper
+
+    def initialize(project)
+      @project = project
+    end
+
+    def load
+      extract('property_definitions', @project).collect { |pd| PropertyDefinitionLoader.new(@project, pd) }
+    end
+  end
+end

data/lib/mingle_macro_development_toolkit/loaders/restful_loaders/property_values_loader.rb

@@ -0,0 +1,14 @@
+#Copyright 2012 ThoughtWorks, Inc.  All rights reserved.
+module RESTfulLoaders
+  class PropertyValuesLoader
+    include LoaderHelper
+
+    def initialize(property_definition)
+      @property_definition = property_definition
+    end
+
+    def load
+      extract('values', @property_definition).collect {|value| Mingle::PropertyValue.new(OpenStruct.new(value))}
+    end
+  end
+end

data/lib/mingle_macro_development_toolkit/loaders/restful_loaders/team_loader.rb

@@ -0,0 +1,14 @@
+#Copyright 2012 ThoughtWorks, Inc.  All rights reserved.
+module RESTfulLoaders
+  class TeamLoader
+    include LoaderHelper
+
+    def initialize(project)
+      @project = project
+    end
+
+    def load
+      (extract('users', @project) || []).collect{ |user| Mingle::User(OpenStruct.new(user))}
+    end
+  end
+end

data/templates/Rakefile

@@ -0,0 +1,23 @@
+namespace :test do
+  Rake::TestTask.new(:units) do |t|
+    t.libs << "test/unit"
+    t.pattern = 'test/unit/*_test.rb'
+    t.verbose = true
+  end
+
+  Rake::TestTask.new(:integration) do |t|
+    t.libs << "test/integration"
+    t.pattern = 'test/integration/*_test.rb'
+    t.verbose = true
+  end
+end
+
+namespace :macro do |ns|
+  task :deploy, :mingle_location do |task|
+    macro_folder = File.expand_path(File.join(File.dirname(__FILE__), '..'))
+    mingle_location = task[:mingle_location] || ENV["MINGLE_LOCATION"]
+    mingle_plugins_folder = File.join(mingle_location, 'vendor', 'plugins')
+    FileUtils.cp_r(macro_folder, mingle_plugins_folder)
+    puts "#{macro_folder} successfully copied over to #{mingle_plugins_folder}. Restart the Mingle server to start using the macro."
+  end
+end

data/{getting_started.txt → templates/getting_started.txt}

@@ -1,73 +1,73 @@
 A background on macros in Mingle
 ---------------------------------
-
+ 
 Macros are a special kind of markup in the Mingle wiki. A macro is identified by the following markup generic syntax
-
+ 
 {{ 
   macro_name
     parameter1: value1
     parameter2: value2
     ...
 }}
-
+ 
 The markup has to be valid YAML syntax. Specifically, this means that the markup is sensitive to spacing and indentation. For more help around YAML and what constitutes valid YAML markup, you can refer to http://yaml.org/spec/current.html
-
+ 
 Specific examples of this include the pre-written macros, such as the value, average & table macros and the macros for all the charts.
-
+ 
 When Mingle encounters a macro while rendering the markup, it delegates handling of the macro to a custom class behind the scenes that is registered to handle it. e.g., if Mingle encountered the following markup,
-
+ 
 {{
   average
     query: SELECT 'Pre-release Estimate' WHERE Release = (current release)
 }}
-
+ 
 it would parse the content between the opening and closing double braces, and identify the following.
-
+ 
 Macro Name: average
 Macro Parameters: {query => "SELECT 'Pre-release Estimate' WHERE Release = (current release)"}
-
+ 
 It then scans a registry of known macros, for a class that is configured to handle a macro with name average. This is the AverageMacro class. You can find this class under the vendor/plugins/average_macro directory of your installation of Mingle.
-
+ 
 class AverageMacro
-  
+   
   def initialize(parameters, project, current_user)
     @parameters = parameters
     @project = project
     raise "Parameter <b>query</b> is required" unless query
   end
-  
+   
   def execute
     first_values = @project.execute_mql(query).collect { |record| record.values.first }
     data = first_values.reject(&:blank?).collect(&:to_f) 
     data.empty? ? 'no values found' : @project.format_number_with_project_precision(data.sum.to_f/data.size.to_f)
   end
-  
+   
   private
-  
+   
   def query
     @parameters['query']
   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 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/3.1/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
 ----------------------
-
+ 
 To write your own macro, you can start with the generated skeleton for the macro. To generate your own macro skeleton, use the new_mingle_macro script that installed with your gem.
-
+ 
 % new_mingle_macro your_new_macro
-
+ 
 This should generate a folder structure as follows
-
+ 
 your_new_macro
       |
       |----lib
@@ -90,67 +90,67 @@ your_new_macro
              |---- integration
                     |
                     your_new_macro_integration_test.rb, ...
-
-
+ 
+ 
 The lib directory contains the actual macro, and the test folders give you the option to run the tests either against local YAML based fixtures, or using REST to test against a deployed mingle instance.
-
+ 
 When this macro is deployed to Mingle, all wiki markup of the form
-
+ 
 {{
   your_new_macro
     parameter1: value1
     parameter2: <some_mql_statement>
     ...
 }}
-
+ 
 will be parsed as YAML and handling will be delegated to an instance of your macro class, YourNewMacro. The parameters will be parsed into a Ruby hash, of the following structure:
-
+ 
 {'parameter1' => 'value1', 'parameter2' => '<some_mql_snippet>'}
-
+ 
 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 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
-  
+   
   def initialize(parameters, project, current_user)
     @parameters = parameters
     @project = project
     @current_user = current_user
   end
-    
+     
   def execute
     completed_work = @project.execute_mql(@parameters['completed_work']).first.values.sum
     total_work = @project.execute_mql(@parameters['total_work']).first.values.sum
     completion_percentage = (completed_work.to_f / total_work.to_f) * 100
-
+ 
     %Q{ <img src='http://chart.apis.google.com/chart?cht=gom&chs=350&chd=t:#{completion_percentage}&chds=0,100' /> }
   end
-  
+   
 end
-
+ 
 The execute method can return any valid HTML or Javascript content. The ability to emit Javascript content, specifically, can only be used on Mingle version 2.3 and above.
-
+ 
 The following example demonstrates how to use the Javascript emission functionality to embed a Google Maps map. 
-
+ 
 Note: For this example to work, you will have to supply your own Google Maps API key as a part of the script tag that loads the Google API.
-
+ 
 class GoogleMap
-
+ 
   def initialize(parameters, project, current_user)
     @latitude = parameters['latitude'] || 39.55
     @longitude = parameters['longitude'] || 116.25
     @zoom_level = parameters['zoom_level'] || 8
   end
-
+ 
   def execute
     <<-HTML
     h2. Google Maps JavaScript API Example: Simple Map
-    
+     
     <div id="map_canvas" style="width: 600px; height: 400px"></div>
     <script src="http://maps.google.com/maps?file=api" type="text/javascript"></script>
     <script type="text/javascript">
@@ -164,99 +164,99 @@ class GoogleMap
     </script>
     HTML
   end
-
+ 
   def can_be_cached?
     false  # if appropriate, switch to true once you move your macro to production
   end
-    
+     
 end
-
+ 
 Long running or integration macros which run on server will result in long page render times. We recommend these sort
 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
 ------------------------
-
+ 
 The macro development toolkit comes with a built in unit testing framework, that borrows the familiar idea of YAML based fixtures. The one small difference we have made to it is that each project that you are providing fixtures for gets its own subfolder within the fixtures directory. We hope that this makes it easier to identify relationships between the objects set up in the YAML files.
-
+ 
 If you are using the skeleton project set up by the new_mingle_macro script, the fixtures directory provides you with a sample project fixture. The data in that should give you a sense of the relationships between the various objects.
-
+ 
 The skeleton project also has a sample unit test set up for you, which uses the sample fixture data. Note the helper method project(...) which takes the name of a sample project to load information from. This method loads a web of objects from the directory named the same as the argument, in the fixtures folder.
-
+ 
 class YourNewMacroTest < Test::Unit::TestCase
-  
+   
   FIXTURE = 'sample'
-  
+   
   def test_macro_contents
     macro = YourNewMacro.new(nil, project(FIXTURE), nil)
     result = macro.execute
     assert result
   end
-
+ 
 end
-
+ 
 Once loaded, you can test things like parameter checking and validations using this style of test. While you cannot execute MQL in this style of test, you can use your favorite mocking library to test how results get handled.
-
+ 
 You can see examples of unit tests in the average macro that is packaged with Mingle in the vendor/plugins/average_macro directory.
-
+ 
 To run your unit tests, run 
-
+ 
 % rake test:units 
-
+ 
 from the root of your custom macro
-
+ 
 Integration testing your macro
 -------------------------------
-
+ 
 ########################################################NOTE###############################################################
 #                                                                                                                         #
 # IN ORDER TO RUN THE INTEGRATION TESTS, YOU WILL NEED TO TURN ON BASIC AUTHENTICATION FOR THE MINGLE 3.1 SERVER THAT YOU # 
 # ARE GOING TO BE TESTING AGAINST.                                                                                        #
 #                                                                                                                         #
 #########################################################NOTE##############################################################
-
+ 
 The integration tests look very similar to the unit tests, the primary difference being that they actually communicate with a deployed Mingle instance over REST. The helper methods populate a web of objects representing a project, that look and behave in a manner identical to how they will in production.
-
+ 
 The one significant difference about these style of tests is that you can actually execute MQL remotely on the Mingle instance instead of mocking out the MQL execution. This will give you a good idea of what results and errors you may expect to see in production, without having to deploy the macro every time.
-
+ 
 There are tradeoffs, of course. Some of these are as follows
-
+ 
 * Should you decide to add these tests to a Continuous Integration build, like Cruise, you will hit the production Mingle sever with every test run. Not hot.
-
+ 
 * Given that each test makes a call to a production server, there is no guarantee (unless you set it up in such a way) - that multiple calls to fetch the same resource will give the same result.
-
+ 
 * Also, while not slow, these tests are definitely much slower than the unit tests. So while it is certainly possible to write only integration tests, we would encourage as a judicious mix of both styles.
-
+ 
 class YourNewMacroIntegrationTest < Test::Unit::TestCase
-  
+   
   PROJECT_RESOURCE = 'http://yourname:password@your.mingle.server:port/lightweight_project/project_identifier.xml'
-
+ 
   def test_macro_contents
     macro = YourNewMacro.new(nil, project(PROJECT_RESOURCE), nil)
     result = macro.execute
     assert result
   end
-
+ 
 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 Mingle 3.1, and so you should be able to run them within your organization too, without a problem.
-
+ 
 To run your integration tests, run 
-
+ 
 % rake test:integration 
-
+ 
 from the root of your custom macro
-
+ 
 Deploying your macro
 ---------------------
-
+ 
 ####################################################### CAUTION ###########################################################
 #                                                                                                                         #
 # BEFORE YOU DEPLOY ANYTHING TO YOUR MINGLE INSTANCE, PLEASE MAKE SURE THAT IT IS COMPLETELY SAFE. THIS IS ESPECIALLY     # 
@@ -272,31 +272,31 @@ Deploying your macro
 #     *    OTHER DATABASE ACTIVITY, SUCH AS TRANSACTION COMMITS, SHOULD BE MONITORED AND AVOIDED                          #
 #                                                                                                                         #
 ######################################################## CAUTION ##########################################################
-
-
+ 
+ 
 To deploy your macro to a locally deployed instance of Mingle, which is running at mingle_root
-
+ 
 % rake macro:deploy MINGLE_LOCATION=/path/to/mingle_root
-
+ 
 where /path/to/mingle_root is the location where Mingle 3.1 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
 * On *NIX, this is the expanded archive
-
+ 
 The entire macro folder and its contents will be copied over into the vendor/plugins directory of that Mingle installation. Once deployed, the server will need to be restarted in order for the macro to become available for use.
-
+ 
 Alternatively, you could also copy the folder by hand into the same location.
-
+ 
 ########################################################NOTE################################################################
 #                                                                                                                          #
 #                                          LEGAL NOTICES AND INFORMATION                                                   #
 #                                                                                                                          #
 #########################################################NOTE###############################################################
-
+ 
 This Getting Started file and the mingle-macro-development-toolkit-1.3.1.gem are owned exclusively by ThoughtWorks, Inc., 
 and ThoughtWorks reserves all rights therein.
-
+ 
 We believe that it is a sound practice from legal, business and software development perspectives to always provide copyright 
 information and license information with any software that you make available to others.  We have provided this information 
 for the Mingle Macro Development Toolkit in the LICENSE.txt file distributed with the Toolkit.  We encourage you to use that