class Mingle::Project

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.

Constants

VERSION_ONE
VERSION_TWO

Attributes

card_types_loader[W]
project_variables_loader[W]
property_definitions_loader[W]
team_loader[W]

Public Class Methods

new(project, card_query_options) click to toggle source
# File lib/mingle_macro_models/project.rb, line 14
def initialize(project, card_query_options)
  @full_project = project
  @card_query_options = card_query_options
end

Public Instance Methods

can_be_cached?(mql) click to toggle source

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

returns: A boolean indicating whether the data pertaining to the MQL can be cached

# File lib/mingle_macro_models/project.rb, line 135
def can_be_cached?(mql)
  @full_project.with_active_project do
    CardQuery.parse(mql, @card_query_options).can_be_cached?
  end
end
card_types() click to toggle source

returns: A list CardTypes as configured for this project. There will always be at least one element in this list.

# File lib/mingle_macro_models/project.rb, line 31
def card_types
  @card_types_loader.load.collect(&:card_type)
end
execute_mql(mql, version = VERSION_TWO) click to toggle source

accepts: A valid MQL string. To see what constitutes valid MQL, look here

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.

# File lib/mingle_macro_models/project.rb, line 119
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
format_date_with_project_date_format(date) click to toggle source

accepts: Any Number

returns: The argument date formatted using the date format configured for the project

# File lib/mingle_macro_models/project.rb, line 156
def format_date_with_project_date_format(date)
  @full_project.format_date(date)
end
format_number_with_project_precision(number) click to toggle source

accepts: Any Number

returns: The argument number formatted to the precision configured for the project (default 2)

# File lib/mingle_macro_models/project.rb, line 149
def format_number_with_project_precision(number)
  @full_project.to_num(number)
end
identifier() click to toggle source

returns: The identifier of this project

# File lib/mingle_macro_models/project.rb, line 20
def identifier
  @full_project.identifier
end
name() click to toggle source

returns: The name of this project

# File lib/mingle_macro_models/project.rb, line 25
def name
  @full_project.name
end
property_definitions() click to toggle source

returns: An list of PropertyDefinitions as configured for this project, which may be empty

# File lib/mingle_macro_models/project.rb, line 36
def property_definitions
  @property_definitions_loader.load.collect(&:property_definition)
end
team() click to toggle source

returns: The full list of Users who are members of this project

# File lib/mingle_macro_models/project.rb, line 142
def team
  @team_loader.load
end
value_of_project_variable(project_variable_name) click to toggle source

accepts: The name of a project variable configured for this project

returns: The display value of the PropertyValue(s) that project_variable_name represents

# File lib/mingle_macro_models/project.rb, line 43
def value_of_project_variable(project_variable_name)
  @project_variables_loader.load.detect { |pv| pv.name == project_variable_name }.value
end

Private Instance Methods

add_alert(message) click to toggle source
# File lib/mingle_macro_models/project.rb, line 163
def add_alert(message)
  @card_query_options[:alert_receiver].alert(message) if @card_query_options[:alert_receiver]
end