<ellipse-data-cricket> ⌲ Upgrading

<ellipse-data-cricket> is a fully featured replacement for Ellipse Data's <ellipse-data> element.

As of August 2023, it is expected that all current users of <ellipse-data> will migrate to <ellipse-data-cricket> as the former tag will soon be deprecated, and new features and upgrades will only be applied to the latter.

The significant differences of <ellipse-data-cricket> compared to <ellipse-data> are:

It is an HTML custom element, which means modern browsers treat it out of the box like a built-in HTML element.
It does not require any additional JavaScript code outside of the element tag to be run to manage it.
It's CSS is now protected (as custom elements enforce 'Shadow DOM'), so customizations are now limited to those which are provided by the public custom styling API. Trying to override styling by targeting other internal CSS selectors will have no effect.
It's attribute names (and relevant attribute values) have been modified to use kebab-case rather than underscore_case when separating multiple words in the name or value.
Boolean attributes are no longer applied by adding the attribute value as a string (eg. lh_batters_to_rh=true or lh_batters_to_rh=false). Instead, if boolean attributes are applied to the widget with any or no value, then the widget will assume that the feature it to be turned on. (i.e. lh_batters_to_rh=true is equivalent to lh-batters-to-rh, and lh_batters_to_rh=false is equivalent to no attribute being applied.)
Some attributes have been deprecated and/or replaced by other similar attributes.
Attributes are now fully reactive, meaning that if they are changed while the widget is running the widget will react suitably. The previous <ellipse-data> would have needed the tag to be recreated to take the new settings, meaning that any internal state (eg. user applied filters) would have been lost. The new tag is more suitable and easy to integrate into modern reactive framework teamplates (eg. React, Angular, Vue).
Drops support for legacy browsers (IE10/IE11 browsers), due to modern (es2019) technologies used. The new <ellipse-data-cricket> tag is supported by all modern browsers.

Upgrading from <ellipse-data> to <ellipse-data-cricket>

Replace Script

Remove the old widget script file:
```
<script src="https://cricvizwidgets.com/widgets.js"></script>
```
Add the the new widget script file (ensuring type="module"), which provisions the <ellipse-data-cricket> tag:
```
<script type="module" src="https://widgets.cricviz.com/lib/ellipse-data-cricket.js"></script>
```
Note that it is fine to put the new script within the head of your page, as it's type="module" it will only be executed when the page body is loaded.

Upgrade Tag Instances

For each tag you are using, you should inspect and change where appropriate:

Change attribute names which have multiple words from using underscore_case into the new kebab-case :

<ellipse-data>	<ellipse-data-cricket>
lh_batters_to_rh	lh-batters-to-rh
bowling_type	bowling-type
grid_metric	grid-metric
comp_type	comp-type
date_start	date-start
date_end	date-end
show_range	show-range
team_colour	team-color
pitchmap_height_ratio	pitchmap-height-ratio

Change attribute values which have multiple words from using underscore_case into the new kebab-case :

<ellipse-data>	<ellipse-data-cricket>
type:"beehive_batter"	type:"beehive-batter"
type:"beehive_bowler"	type:"beehive-bowler"
type:"beehive_competition_batter"	type:"beehive-competition-batter"
type:"beehive_competition_bowler"	type:"beehive-competition-bowler"
type:"pitchmap_batter"	type:"pitchmap-batter"
type:"pitchmap_bowler"	type:"pitchmap-bowler"
type:"pitchmap_competition_batter"	type:"pitchmap-competition-batter"
type:"pitchmap_competition_bowler"	type:"pitchmap-competition-bowler"
type:"wagonwheel_batter"	type:"wagonwheel-batter"
type:"wagonwheel_bowler"	type:"wagonwheel-bowler"
type:"wagonwheel_competition_batter"	type:"wagonwheel-competition-batter"
type:"wagonwheel_competition_bowler"	type:"wagonwheel-competition-bowler"
include:"axis_horizontal"	include:"axis-horizontal"
include:"axis_vertical"	include:"axis-vertical"
include:"grid_labels"	include:"grid-labels"
include:"range_markers"	include:"range-markers"
include:"two_runs"	include:"two-runs"

Note any spelling changes in the new attributes names or values, as some have been modified (eg. to use US English spellings) :

<ellipse-data> <ellipse-data-cricket>

live live-update

team_colour team-color
Set the customer-id as attribute into <ellipse-data-cricket>. This should be the same as the API_KEY value which you applied via $ed.start(...) in the old element. Note that you won't need the $ed management in the new version (see below).

Update Custom Styles

As mentioned above, and in the Getting Started section, custom styling is implemented differently in the new <ellipse-data-cricket> element. Steps:
1. Remove any styles=true attribute you are setting on the widget, as it is no longer a valid/needed widget option. (Also: Try the new version of the Widget Maker Tool to ensure you are applying the correct attribute names.)
2. Remove any custom CSS styles you were applying to the old <ellipse-data> element. You will need to rework them for the <ellipse-data-cricket> element using the new custom styling mechanism.
  NOTE: CricViz team should be able to supply you with the set of CSS custom properties and their values which will port your styling of <ellipse-data> across to <ellipse-data-cricket>.
Rework 'Widget Management'

As stated above, the new <ellipse-data-cricket> element no longer requires the any extra JavaScript management code to be run outside the widget.

The old <ellipse-data> element used the $ed variable provided by it's script to trigger the loading sequence of the widget, and then remove the widget later:
```
$ed(document).ready(() => {
  $ed.start({
    id: 'API_KEY'
  });
});

... and then somewhere later ...

$ed.removeWidget('ed-6')
```
The new implemention does not have any variable within the script, but instead uses custom element features to handle the lifecyle of the widget internally within <ellipse-data-cricket>, in much the same way as a standard HTML element might.

Optimising the data loading of the widget is important, and now this can be achieved by the following:
- Since the <ellipse-data-cricket> element is a custom HTML element if the ellipse-data-cricket.js script is not loaded, then the browser will simply not render anything for the widget (i.e. 0 height, 0 width, no error).
- If you apply the new disabled value-less boolean attribute to the widget (see attributes), then it will mean:
  - The widget will not handle any UI events (eg. mouse/key).
  - The widget will not send any network data requests.
- If the widget is entirely offscreen it will not make any subsequent live-update requests.
- If the widget has been offscreen or disabled, and becomes partially onscreen and not disabled, then it may make a new request to refresh it's data (and will also resume live-update if it is applied as an attribute.)
- The widget may also trigger data requests in reaction to certain attributes applied to it changing (eg. match id) change, as a different data feed will be required.