Suggestion for improvement of CustomTime & Markers

[AlexDM0]

Hi guys,

Good work keeping visjs alive! I've started a new project which I want to use the vis-timeline for. I noticed you guys have added a lot of new things since the last time I've checked!

One of the things I've been trying to work with is the new marker feature. However, I found this a little clunky to use. I thought it might be nice to see if we can improve this!

There does not seem to be a clear separation between a marker and a custom time.

Maybe we could explore the use case of the custom time vs the marker. As far as I can see in the examples, they're pretty much interchangeable, except markers have more features than customTimes. I have long forgotten the original design goals of the custom time but if you have a few use cases that specifically require the custom time and not a marker I'd be happy to hear them!

Issues

A few things I found confusing:

• A marker requires a custom time bar to be created first, why can't I just addMarker(time, title, options={})?
• I MUST provide my own ID. It is used for styling, whereas other items use "className". I require the ID for all of the other methods. Maybe the add method can return a ID? It can be generated if the user does not provide one.
• I have to use setCustomTimeMarker, setCustomTimeTitle does not work without setCustomTimeMarker
• CustomTime is always editable (draggable). There are solutions to this but they are more hacky solutions than features. Many customTime related fields have editable. Maybe add it to the constructor?
• I have to use css to style my custom time bar, whereas items and groups have a style option.
• Changing the title in the example will not allow me to drag select the title. The mouse events should be swallowed by the title when editing.

I'd suggest:
Deprecate customTime and move forward with markers. A marker without title is similar to a customTime.

API Suggestion

This API can live side by side with the current version to keep backwards compatibility. We could then print deprecated logs when the "old" API is used, and remove them in a future breaking version update.

addMarker(time : number | Date, title?: string, options: MarkerOptions) : string

Create a marker at a specific time. Without title this is the same as a CustomTime (deprecated).

• Parameters

  • time(number | Date): Time of the marker. Timestamp or Date object.
  • title(string): [optional] provide a title for the marker
  • options(MarkerOptions): [optional] options to configure the marker

• MarkerOptions

{
  id?: string,                // [optional] custom ID, should not be used for css, only for reference
  draggable?: boolean = true, // [optional] drag the marker along the timeline, triggers event on change
  editable?: boolean = false, // [optional] make the title editable, triggers event on change
  style?: string,             // [optional] css string, just like items and groups    (consistency)
  className?: string,         // [optional] class name, just like items and groups (consistency)
   ...?
}

• Returns
  • id(string) The ID of this marker. Can be supplied in options if you want to use a custom ID. Is used to refer to this marker in the next methods.

setMarkerTitle(id: string, title: string)

Change the title of this marker.

• Parameters
  • id(string): ID of the marker to update.
  • title(string): New title for this marker

moveMarker(id: string, time: number | Date: string, animate? : boolean = false)

Change the position (time) of this marker.

• Parameters
  • id(string): ID of the marker to update.
  • time(number | Date): New time for this marker
  • animate(boolean): [optional] when true, animate the repositioning of the marker

updateMarker(id: string, options: MarkerOptions)

Change the options of the marker. Everything except the ID can be changed.

• Parameters
  • id(string): ID of the marker to update.
  • options(MarkerOptions): new options to configure the marker

removeMarker(id: string)

Delete the marker

• Parameters
  • id(string): ID of the marker to remove.

Result

It would make code like this:

timeline.addCustomTime(new Date(), 'customTime');
timeline.setCustomTimeMarker("This is editable", 'customTime', true);

into this

let markerId = timeline.addMarker(new Date(), "This is editable", {editable:true});
// or
timeline.addMarker(new Date(), "This is editable", {id: 'customTime', editable:true});

This is just a suggestion, I hope it can lead to a nice discussion!

[IncPlusPlus]

I ran into the same things you did and I like what you're proposing. I definitely think that custom times and markers share a lot of overlap and is pretty confusing. What I was hoping was to be able to use markers to denote start and end times of events so that a user could keep track of when an event starts and look at the overlap of that time while scrolling down through other groups of events. I suppose that could be an entirely separate feature though.