Mashups in TargetProcess

Mashups allow you to quickly extend TargetProcess UI with any (almost) functionality you want. There are several places on each page (empty <div> elements) where you can add some new UI. Or you can hook up to page's DOM and modify existing UI.

Quick Start

Lets write a simple mashup that shows Bugs and Tasks count on the UserStory View page. Navigate to [tp_web_root]/JavaScript/Mashups folder and create BugsTasksCount folder. Then we add a mashup config file UserStoryInfo.cfg with the following content:

Placeholders:Project_Planning_UserStory_view

This config tells TargetProcess to execute our mashup script file only on User Story View page in placeholder in the bottom of the page. After that we should create a javascript file UserStoryInfo.js. With the power of REST API we can easily grab UserStory by ID and then get Tasks and Bugs count. Here is the code:

	tau.mashups.addMashup(
		function (config) {

			function userStoryInfo(placeholder) {
				this.placeholder = placeholder;
			}

			userStoryInfo.prototype = {
				placeholder: null,
				template: 'Tasks/Bugs : ${TasksCount}/${BugsCount}',

				render: function () {
					var url = new Tp.URL(window.location.href);
					var userStoryId = url.getArgumentValue("UserStoryID");
					$.getJSON(new Tp.WebServiceURL('/api/v1/Userstories/' + userStoryId + '/?include=[Name]&append=[Bugs-Count,Tasks-Count]').url, $.proxy(this._onUserStoryReceived, this));
				},

				_onUserStoryReceived: function (userStory) {
					var data = { TasksCount: userStory["Tasks-Count"], BugsCount: userStory["Bugs-Count"] };
					$.tmpl(this.template, data).appendTo(this.placeholder);
				}
			}

			new userStoryInfo($('#' + config.placeholderId)).render();
		}
	)

Navigate to TargetProcess and open User Story View page.

Overview

Mashup is a set of javascript files with a config. We have created a set of placeholders where UI can be extended, but in general you can use mashups anywhere and for any purpose you want. Here are some quick examples: add specific validation on a custom field, create custom report with help of REST API, hide some UI elements based on your custom rules, fetch data from external system and show it.

To create a mashup in TargetProcess, add new folder in [tp_web_root]\JavaScript\Mashups folder. You should put Mashup config and Javascript into this folder:

Mashup config is a file with a .cfg extension and the following format:

Placeholders:placeholder_1,placeholder_2

where placeholder_1 is some placeholder id.

So you enumerate areas where you want your mashup to be included.

Placeholders

All Javascript files will be included into the page. For example, if you have mashup config with the following content: Placeholders:placeholder1,placeholder2 and the page contains both placeholder1 and placeholder2, then your javascript files will be included twice.

TargetProcess has the following placeholders:

• footerPlaceholder. It is located just below the footer text.
• There is a unique placeholder for each page. It is located just below the page content. The id of the placeholder can be defined from the url. For example bug view page has the following relative url /Project/QA/Bug/View.aspx. The rule is: all slashes are replaced with underline and .aspx is removed. So in our example placeholder id will be Project_QA_Bug_View. Placeholder ids are case insensitive.

Here are some examples:

Page	Placeholder
Dashboard	Default
Requests List	Project_HelpDesk_Request_List
Kanban Board	Project_Planning_Kanban_KanbanBoard
Add User Story	Project_Planning_UserStory_Edit

Javascript Mashup File Format

We recommend to use the following syntax in javascript file:

tau.mashups.addMashup(
    function (config) { 
        // place your code here
    }
)

In this case we can guarantee some goodies:

1. Your code will be executed when all javascript frameworks are ready.
2. You have a config variable (see Mashup Configuration).
3. All your javascript code will be wrapped with a try/catch block and all errors will be visible in console only.
4. You always will have correct scope (no problems with duplicate function/variable names).

Mashup Configuration

When mashup function is called it is provided with a configuration object as it's last parameter.

tau.mashups.addMashup(
    function (config) { 
        // config = {
        //		'placeholderId': 'footerPlaceholder',
        //		'basePath': '/tpVdir/',
        //		'mashupPath': '/tpVdir/JavaScript/Mashups/MyMashup/'
        //}
    }
)

Configuration object contains the following fields:

1. 'placeholderId' is the element id where mashup shoud be rendered to
2. 'basePath' is the path to the root of the application
3. 'mashupPath' is the path to the root of the mashup

Modules and Dependencies

You can use mashup to define a module that will be used by other mashups. Here is the code to define a module:

tau.mashups.addModule("helloWorldModule", function() { 
        function helloWorldModule() {}
        
        helloWorldModule.prototype = {
        	sayHello : function() { alert('Hello world!'); }
        }
        
        return helloWorldModule;
    });

If the module is included into page then it is possible to use it in other mashup or module:

tau.mashups
	.addDependency("helloWorldModule")
	.addDependency("libs/jquery/jquery")
	.addMashup(function(helloWorldModule, jquery, config) { 
        //jquery is null but we need it to be here as a placeholder
        
        $('body').click(function() { new helloWorldModule().sayHello(); })
        
    });

You can use some predifined modules:

Module Name	Description
libs/jquery/jquery	jQuery
libs/jquery/jquery.ui	jQuery's visual controls
libs/jquery/jquery.tmpl	Render the specified HTML content as a template, using the specified data

Custom CSS

You can use your custom CSS. Create css file with the styes you need and save it to the Mashup folder. After that you can plug your styles in like this:

tau.mashups
	.addCSS("mycustom.css")
	.addDependency(...)
	.addMashup(...);

Remove Mashup

Just remove the folder with your mashup.

Examples and Contribution

You can find more examples of Mashups on GitHub. Feel free to Fork this repo and experiment.

Chapters

1. Quick Start
2. Overview
   • Placeholders
   • Javascript Mashup File
   • Mashup Configuration
   • Modules and Dependencies
   • Custom CSS
   • Remove Mashup
   • Examples and Contribution