Class: Subscriptions

STX.QuoteFeed. Subscriptions


new Subscriptions()

A QuoteFeed that maintains a list of subscribed symbols and provides callbacks for when to subscribe or unsubscribe as instruments are added or removed from the chart. These could be additional symbols needed for a study, series added programatically or even comparisons added by the user via the UI.

A subscription is uniquely defined by a params object accepted by STX.QuoteFeed#fetch: { symbolObject: period: interval: }

Example
//Copy and paste STX.QuoteFeed.CopyAndPasteMe. Change "CopyAndPasteMe" to the name
//of your quote service. Then implement the fetch() method based on the included comments
	
STX.QuoteFeed.CopyAndPasteMe=function(){};
	
STX.QuoteFeed.CopyAndPasteMe.stxInheritsFrom(STX.QuoteFeed.Subscriptions);
	
STX.QuoteFeed.CopyAndPasteMe.prototype.fetchFromSource=function(params, cb){
	
	// This is an outline for how to implement fetch in your custom feed. Cut and paste
	// this code and then implement. Leave any portion blank that you cannot support.
	// 
	// Most quote feeds will support startDate and endDate. This will be enough to implement
	// charts. It is also possible to implement charts with quote feeds that support other
	// request parameters but you may need to do some manipulation within this code to
	// accomplish this.
	// 
	// See STX.QuoteFeed.Demo or STX.QuoteFeed.EndOfDay below for actual implementations.
	
	if(params.startDate && params.endDate){
		// If you receive both a startDate and endDate then the chart is asking for a
		// specific data range. This usually happens when a comparison symbol has been
		// added to the chart. You'll want the comparison symbol to show up on all the same
		// bars on the screen.
		// 
		// You should return data for the entire range, otherwise you could get a gap of data on the screen.
	} else if(params.startDate){
		// This means the chart is asking for a refresh of most recent data.
		// (This is streaming by "polling". For actual push based streaming see STXChart#streamTrade and STXChart.appendMasterData.
		// 
		// The chart will call this every X seconds based on what you have specified in behavior.refreshInterval
		// when you initially attached the quote feed to stxx (attachQuoteFeed).
		// 
		// If you don't support polling then just do nothing and return.
		// Otherwise fetch your data, probably using Ajax, and call the cb method with your data.
		// 
		// Please note that you may need to return more than 1 bar of data. If the chart has moved
		// forward then the requested startDate will be the previous bar (to finalized the bar) and
		// you should return that bar as well as the current (new) bar. To simplify, always return
		// all of the bars starting with startDate and ending with the most recent bar.
	}else if(params.endDate){
		// If you only receive an endDate, it means the user has scrolled past the end of
		// the chart. The chart needs older data, if it's available.
		// If you don't support pagination just return and do nothing.
		// 
		// Note: If your server requires a startDate then you'll need to calculate one here. A simple method
		// would be to take the endDate and then, using JavaScript Date math, create a date that is far enough
		// in the past based on params.period, params.interval and params.ticks. @todo, provide a convenience method
		// 
		// Otherwise fetch your data, probably using Ajax, and call the call with cb method with your data.
	}else{
		// The chart needs an initial load.
		// 
		// params.tick provides an suggested number of bars to retrieve to fill up the chart
		// and provide some bars off the left edge of the screen. It's good to provide more initial
		// data than just the size of the chart because many users will immediately zoom out. If you
		// have extra data off the left edge of the chart, then the zoom will be instantaneous. There
		// is very little downside to sending extra data.
		// 
		// You do not need to retrieve exactly params.tick number of bars. This is a suggestion.
		// You can return as many as you want. Fetching 1,000 bars is another good approach. This will
		// cover the immediate zooming and panning needs of 95% of users.
		//
		// Note: If your server requires startDate and endDate then use Date.now() for the endDate
		// and calculate a startDate using JavaScript Date math. params.period, params.interval and params.ticks
		// provide all the variables necessary to do the math. @todo, provide a convenience method
		// 
		// Fetch your data, probably using Ajax, and call the cb method with yourdata. This
		// is where you'll need to reformat your data into the format required by the chart.
		// 
		//  Put your code here to format the response according to the specs and return it in the callback.
		//
		//	Example code:
		//	
		// STX.postAjax(url, null, function(status, response){
		//	if(status!=200){
		//		cb({error:status});	// something went wrong, use the callback function to return your error
		//		return;
		//	}
		//	
		//	var quotes=formatQuotes(response);
		//	var newQuotes=[];
		//	for(var i=0;i<quotes.length;i++){
		//		newQuotes[i]={};
		//		newQuotes[i].Date=quotes[i][0]; // Or set newQuotes[i].DT if you have a JS Date
		//		newQuotes[i].Open=quotes[i][1];
		//		newQuotes[i].High=quotes[i][2];
		//		newQuotes[i].Low=quotes[i][3];
		//		newQuotes[i].Close=quotes[i][4];
		//		newQuotes[i].Volume=quotes[i][5];
		//		newQuotes[i].Adj_Close=quotes[i][6];
		//	}
		//  cb({quotes:newQuotes, moreAvailable:false}); // set moreAvailable to true or false if your server supports fetching older data, and you know that older data is available.
		// });
		// 
	}
};
	
STX.QuoteFeed.CopyAndPasteMe.prototype.subscribe=function(params){
	// This will get called each time the chart encounters a new symbol. This
	// could happen from a user changing symbol, a user adding a comparison symbol,
	// a new study that requires a new symbol.
	// 
	// You can use this along with unsubscribe() to keep track for the purpose
	// of maintaining legends, lists of securities, or to open or close streaming
	// connections.
	// 
	// If using a push streamer, subscribe to this security and then have the push
	// streamer push updates using STXChart#streamTrade if you have
	// a "last trade" stream or STXChart@appendMasterData if you have an "OHLC" stream.
	// 
	// Use params.interval, params.period, params.symbolObject to inform your streamer
	// what it needs to send
};
	
STX.QuoteFeed.CopyAndPasteMe.prototype.unsubscribe=function(params){
	// When a chart no longer needs to keep track of a symbol it will call
	// unsubscribe(). You can use this to tell your streamer it no longer
	// needs to send updates.
};

Methods


fetchFromSource()

The charting engine will call this method whenever it needs data from your feed. Override this with your implementation to fetch data from your server.
Uses same parameters and format as STX.QuoteFeed#fetch.


subscribe(params)

This callback will be called when a new instrument is added to the chart. Put your code here to subscribe to your feed.

Parameters:
Name Type Description
params object

Describes the symbol and periodicity for the new instrument.

Properties
Name Type Argument Description
symbol string

The new symbol to subscribe. See STX.QuoteFeed for details.

symbolObject string <optional>

The new symbol to subscribe in object format. See STX.QuoteFeed for details.

period number

The timeframe each returned object represents. See STX.QuoteFeed for details.

interval string

The type of data your feed will need to provide. See STX.QuoteFeed for details.


unsubscribe(params)

This callback will be called when an existing instrument is removed from the chart. Put your code here to UN-subscribe from your feed.

Parameters:
Name Type Description
params object

Describes the symbol and periodicity for the currently subscribed instrument.

Properties
Name Type Argument Description
symbol string

The symbol to remove. See STX.QuoteFeed for details.

symbolObject string <optional>

The symbol to remove in object format. See STX.QuoteFeed for details.

period number

The timeframe each current object represents. See STX.QuoteFeed for details.

interval string

The type of data your feed is currently providing. See STX.QuoteFeed for details.