Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
30 changes: 15 additions & 15 deletions wiki/Best-practices.md
Original file line number Diff line number Diff line change
@@ -1,68 +1,68 @@
##Creating the best user experience
## Creating the best user experience

We love our charts. We want them to be the best: the most beautiful, the most responsive and the most powerful charts in the whole HTML5 world. We are working hard to reach these goals.

We know all about our charts and about how to create the best user experience on them and we'd be glad to share our knowledge to you. This document describes several best practices for integrating the Charting Library into your website/application. The main point is to always think about your users and their experience.

###1. Understand what Charting Library IS and what it ISN’T
### 1. Understand what Charting Library IS and what it ISN’T

Charting Library is a charting component able to show prices, charts & technical analysis tools. Library does the chart magic, and nothing more. If you want some additional functionality (like chats, special symbols list, hottest deals, ads, etc) the best approach is to implement them outside of the chart. However, if you want to link your outside functionality with the library, you can use the library’s API to link them.


###2. Return exactly as many bars as the Library requests
### 2. Return exactly as many bars as the Library requests

Library will ask your backend for data and provide the required data range bounds with each request. Respect these bounds and return data filling this range as fully as possible. Do not return more bars. Do not return bars out of the requested range. If you want to extend the default data range requested by the Library, use our JS API (see calculateHistoryDepth).

###3. Return exactly as many marks as the Library requests
### 3. Return exactly as many marks as the Library requests

The same as for the bars above. Send only marks matching the requested range.


###4. Do not override calculateHistoryDepth() to get more than 2 screens of data
### 4. Do not override calculateHistoryDepth() to get more than 2 screens of data

Charting Library avoids loading content which the user didn’t ask for. Loading more bars into the chart means loading the CPU and memory with more operations that necessary. This means responsiveness of the whole solution decreases.

###5. Do not make your chart look as a mess
### 5. Do not make your chart look as a mess

Users like beautiful charts. As we do. Please remember to keep your chart looking good when customizing size or style. Avoid embedding custom controls that look alien to the entire chart's style.

###6. Avoid making very small charts
### 6. Avoid making very small charts

The smallest meaningful size that the Library supports is 600x600px. Avoid making charts smaller because it looks like a mess. Use the `mobile` preset, or hide some toolbars if you need charts smaller than mentioned above.

###7. Use the appropriate language
### 7. Use the appropriate language

The Charting Library is translated into a dozen of languages. Use the one that fits your users' needs.

###8. If you are experiencing issues
### 8. If you are experiencing issues

We are always eager to help you. But, unfortunately, we are really busy guys, so we don’t have much time. Please help us spend our time effectively and always update your Library's build to the latest `unstable` version to check if the issue still happens. Contact us if it does.

Also, check the data you are passing to the Charting Library and make sure it matches our requirements as described in the documentation. Pay special attention to SymbolInfo content because it's the most common place to make an error (according to our statistics).

You can watch the output of our demo data service and compare it to yours to ensure your backend behaves like it should.

###9. Read the docs
### 9. Read the docs
We spent a lot of time creating those docs for you to make your life easier. Please give it a try.

###10. Choose an appropriate data transport for your solution
### 10. Choose an appropriate data transport for your solution

Pay attention to differences between JS API and UDF, and choose the API that fits your needs best.
Do not use UDF if you need really fast data updates or data streaming.
Do not use UDF with data grouping (see `supports_group_request`) if your backend has more than a dozen symbols.

###11. Do not try to sniff our code and use undocumented features
### 11. Do not try to sniff our code and use undocumented features

All features not mentioned in our documentation are subjects for change without any warnings and backward compatibility. Also altering the source code is strictly prohibited by the legal agreement you signed.

###12. Do not use our demo datafeed on your production website
### 12. Do not use our demo datafeed on your production website

This datafeed is just a demo and is not intended for real usage. It may be unstable and can't bear significant load.

###13. Use the API for customization. Avoid editing CSS.
### 13. Use the API for customization. Avoid editing CSS.

We do not guarantee CSS selectors' backward compatibility.

###14. Set up your server to gzip files when sending to client
### 14. Set up your server to gzip files when sending to client

This is the common best practice for static HTML content. Gzipping the Library's HTML file will decrease your users' waiting time.
74 changes: 37 additions & 37 deletions wiki/Chart-Methods.md
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,7 @@ Here is a list of supported chart's methods.

**Since 1.5 version.** You can call these methods using chart object returned to you by widget's methods [[chart(index)|Widget-Methods#chart-chartindex]] or [[activeChart()|Widget-Methods#chart-activechart]].

#Methods
# Methods

* Subscribing To Chart Events
* [[onDataLoaded()|Chart-Methods#ondataloaded]]
Expand Down Expand Up @@ -41,52 +41,52 @@ Here is a list of supported chart's methods.
* [[getVisibleRange()|Chart-Methods#getvisiblerange]]
* [[priceFormatter()|Chart-Methods#priceformatter]]

#Subscribing To Chart Events
# Subscribing To Chart Events

####onDataLoaded()
#### onDataLoaded()

You can subscribe using [[Subscription]] object returned by this function to be notified when new history bars are loaded and unsubscribe from the event.

####onSymbolChanged()
#### onSymbolChanged()

You can subscribe using [[Subscription]] object returned by this function to be notified when the symbol is changed and unsubscribe from the event.

####dataReady(callback)
#### dataReady(callback)
1. `callback`: function(interval)

The Charting Library will call the callback provided immediately if bars are already loaded or when the bars are received.
The function returns `true` if bars are already loaded and `false` otherwise.

####crossHairMoved(callback)
#### crossHairMoved(callback)
**Since 1.5 version.**

1. `callback`: function({time, price})

The Charting Library will call the callback every time the crosshair position is changed.

#Chart Actions
# Chart Actions

####setVisibleRange(range, callback)
#### setVisibleRange(range, callback)
1. `range`: object, `{from to}`
1. `from`, `to`: unix timestamps, UTC
2. `callback`: `function()`. The Library will call it after it's done with the viewport setup.

Forces the chart to adjust its parameters (scroll, scale) to make the selected time period fit the view port.
Neither `from`, nor `to` must not be in future. This method was introduced in version `1.2`.

####setSymbol(symbol, callback)
#### setSymbol(symbol, callback)
1. `symbol`: string
2. `callback`: function()

Makes the chart to change its symbol. Callback is called after new symbol's data arrived.

####setResolution(resolution, callback)
#### setResolution(resolution, callback)
1. `resolution`: string
2. `callback`: function()

Makes the chart to change its resolution. Callback is called after new data arrived.

####executeAction(action)
#### executeAction(action)
**_deprecated, use executeActionById instead_**

1. `action`: string
Expand All @@ -100,7 +100,7 @@ widget.chart().executeAction("Hide All Drawing Tools"); // this will toggle all
// < ... >
```

####executeActionById(actionId)
#### executeActionById(actionId)
_**since version 1.3**_

1. `actionId`: string
Expand Down Expand Up @@ -154,26 +154,26 @@ widget.chart().executeActionById("drawingToolbarAction"); // hides or shows the
// < ... >
```

####refreshMarks()
#### refreshMarks()

Calling this method makes the Library to request visible marks once again.

####clearMarks()
#### clearMarks()

Calling this method makes the Library to remove all visible marks.

####setChartType(type)
#### setChartType(type)
1. `type`: `TradingView.BARS` | `TradingView.CANDLES` | `TradingView.AREA` | `TradingView.LINE` | `TradingView.HEIKEN_ASHI` | `TradingView.HOLLOW_CANDLES`

Sets the main series style.

####closePopupsAndDialogs()
#### closePopupsAndDialogs()

Calling this method closes a context menu or a dialog if it is shown.

#Studies And Shapes
# Studies And Shapes

####createStudy(name, forceOverlay, lock, inputs, callback, overrides)
#### createStudy(name, forceOverlay, lock, inputs, callback, overrides)
1. `name`: string, a name of an indicator as you can see it in `Indicators` widget
2. `forceOverlay`: forces the Charting Library to place the created study on main pane
3. `lock`: boolean, shows whether a user will be able to remove/change/hide your study or not
Expand Down Expand Up @@ -201,7 +201,7 @@ Creates the study on a main symbol. Examples:
```


####createShape(point, options, callback)
#### createShape(point, options, callback)
1. `point`: object `{time, [price], [channel]}`
1. `time`: unix time. The only mandatory argument.
2. `price`: If you specify `price`, then your icon will be placed on its level. If you do not, then the icon sticks to bar at respective time.
Expand All @@ -221,7 +221,7 @@ Creates the study on a main symbol. Examples:

This call creates a shape at specified point on main series.

####createMultipointShape(points, options, callback)
#### createMultipointShape(points, options, callback)
1. `points`: an array of objects `[{time, [price], [channel]},...]`
1. `time`: unix time. The only mandatory argument.
2. `price`: If you specify `price`, then your icon will be placed on its level. If you do not, then the icon sticks to bar at respective time.
Expand All @@ -243,28 +243,28 @@ Look [[Shapes and Overrides|Shapes and Overrides]] for more information.

This call creates a shape with specified points on main series.

####removeEntity(entityId)
#### removeEntity(entityId)
1. `entityId`: object. Value which was passed to your callback after the entity (shape of study) was created.

Removes the specified entity.

####createVerticalLine(point, options)
#### createVerticalLine(point, options)
1. `point`: object `{time}`
2. `options`: obejct `{lock}`

This function is a synonym for `createShape` with shape = 'vertical_line'. It is treated as **obsolete**.

####removeAllShapes()
#### removeAllShapes()
Removes all shapes (drawings) from the chart.

####removeAllStudies()
#### removeAllStudies()
Removed all studies from the chart.


#Study Templates
# Study Templates


####createStudyTemplate(options, callback)
#### createStudyTemplate(options, callback)
1. `options`: object `{saveInterval}`
1. `saveInterval`: boolean
2. `callback`: function(data)
Expand All @@ -273,16 +273,16 @@ Removed all studies from the chart.

Saves the study template to JS object. Charting Library will call your callback and pass the state object as argument. This call is a part of low-level [[save/load API|Saving-and-Loading-Charts]].

####applyStudyTemplate(template)
#### applyStudyTemplate(template)
1. `template`: object

Loads the study template from state object. This call is a part of low-level [[save/load API|Saving-and-Loading-Charts]].


#Trading Primitives
# Trading Primitives


####createOrderLine(options)
#### createOrderLine(options)
Creates a new order on the chart and returns an API-object which you can use to control the order properties and behavior. It's strongly recommended to read [[this article|Trading-Primitives]] before using this call.

Arguments (since 1.4):
Expand Down Expand Up @@ -352,7 +352,7 @@ widget.chart().createOrderLine()
.setQuantity("2");
```

####createPositionLine(options)
#### createPositionLine(options)
Creates a new position on the chart and returns an API-object which you can use to control the position properties and behavior. It's strongly recommended to read [[this article|Trading-Primitives]] before using this call.

Arguments (since 1.4):
Expand Down Expand Up @@ -429,7 +429,7 @@ widget.chart().createPositionLine()
.setLineStyle(0)
.setLineLength(25);
```
####createExecutionShape(options)
#### createExecutionShape(options)
Creates a new execution on the chart and returns an API-object which you can use to control the execution properties. It's strongly recommended to read [[this article|Trading-Primitives]] before using this call.

Arguments (since 1.4):
Expand Down Expand Up @@ -477,25 +477,25 @@ widget.chart().createExecutionShape()
.setPrice(15.5);
```

#Getters
# Getters

####symbol()
#### symbol()

Returns chart's symbol.

####resolution()
#### resolution()

Returns chart's resolution.

####getVisibleRange()
#### getVisibleRange()

Returns object `{from, to}`. `from` and `to` are Unit timestamps **in the timezone of chart**.

####priceFormatter()
#### priceFormatter()

Returns object with `format` function that you can use to format prices. Introduced in 1.5.

#See Also
# See Also
* [[Widget Methods]]
* [[Charts Customization 101]]
* [[Widget Constructor]]
Expand Down
6 changes: 3 additions & 3 deletions wiki/Charts-Customization-101.md
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
Customization is rather a vague concept so there are a few articles about it.

#Customization done through data stream.
# Customization done through data stream.
They are most about data-related stuff. Those customizations are done through datafeed configuration response. The example of configuration response:

```javascript
Expand All @@ -24,7 +24,7 @@ They are most about data-related stuff. Those customizations are done through da

One may find more detailed description of this parameters on [[JS API page|JS-Api#onreadycallback]].

#Customizations done on client-side.
# Customizations done on client-side.
These ones allow you to affect most of UI/UX. These customizations are done through chart widget constructor arguments. The example of widget constructor call:

```javascript
Expand Down Expand Up @@ -67,6 +67,6 @@ var widget = new TradingView.widget({

See the details in [[Widget Constructor Arguments article|Widget-Constructor]].

#See Also
# See Also
* [[Widget's Constructor Arguments|Widget-Constructor]]
* [[Widget's Methods|Widget-Methods]]
2 changes: 1 addition & 1 deletion wiki/Creating-Custom-Studies.md
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
We use our [Pine scripting language](https://www.tradingview.com/study-script-reference/) to create indicators for Charting Library. If you want to create a custom indicator you have to write it in Pine using TradingView site. Then contact us and we'll compile your Pine code to a code for Charting Library. Then use widget constructor's `indicators_file_name` parameter to show the library where to find your studies.


### How to show your data as an indicator
## # How to show your data as an indicator

Here is an instruction for the case if you have some data which you want to show on the chart like an indicator and which cannot be computed from series data directly.

Expand Down
2 changes: 1 addition & 1 deletion wiki/Drawings-Overrides.md
Original file line number Diff line number Diff line change
Expand Up @@ -960,7 +960,7 @@ linetoolvisibilities: {
}
```

###Constants
### Constants

These constants are used in the drawings defaults. You cannot use their names directly. Use the values instead.

Expand Down
Loading