angular-calendar-timeline

Angular 13+ timeline calendar

Demo

https://codesandbox.io/s/tender-cerf-zk0ewt

About

A timeline for angular 13+ that shows tasks or events on a timeline in different modes: days, weeks, and months.

This library is pretty small and DOESN'T use big dependencies like JQuery or Moment.js. Library also supports SSR.

Getting started

Install through npm:

npm install --save angular-timeline-calendar

Then import the timeline module into the module where you want to use the timeline.

Don't forget to call forChild() method:

import { NgModule } from '@angular/core';
import { TimelineModule } from 'angular-timeline-calendar';

@NgModule({
  imports: [
    TimelineModule.forChild(),
  ],
})
export class MyModule {
}

That's it, you can then use it in your component as:

import { ITimelineItem } from "angular-timeline-calendar";

@Component({
  template: `<timeline-calendar [items]="items"> </timeline-calendar>`
})
export class MyTimelineComponent implements AfterViewInit {
  items: ITimelineItem[] = [];
}

Customization

1. Localization

Change localization is very simple, just pass locale code to the 'locale' component input. Make sure that the current locale is registered by Angular:

import localeUk from "@angular/common/locales/uk";

registerLocaleData(localeUk);

@Component({
  template: `<timeline-calendar locale="uk"></timeline-calendar>`
})

2. Header

You can customize the scale view by providing a config for each view mode.
In case you need to change the format of the dates in the header or change start or end dates, you can provide a config for each view mode:

import { NgModule } from '@angular/core';
import { TimelineModule,
  IScaleFormatter, 
  IScaleGeneratorConfig,
  IItemsIterator } from 'angular-timeline-calendar';

const myCustomFormatter: IScaleFormatter = {
  formatColumn(column: IScaleColumn, columnWidth: number, locale: string): string {
    return column.date.toString();
  }
}

@NgModule({
  imports: [
    TimelineModule.forChild({
      // Customization dates range and their format in the header for day view mode.
      dayScaleConfig: {
        formatter: myCustomFormatter,
        getStartDate: (itemsIterator: IItemsIterator) => itemsIterator.getFirstItem(true).startDate,
        getEndDate: (itemsIterator: IItemsIterator) => new Date(),
      } as Partial<IScaleGeneratorConfig>,
      // Customization dates format in the header for week view mode.
      weekScaleConfig: {
          formatter: myCustomFormatter
      } as Partial<IScaleGeneratorConfig>
    }),
  ],
})
export class MyModule {
}

3. Zooms

You can simply set your own zooms if you want to add more. For changing the current zoom use TimelineComponent API. Here is an example:

import { AfterViewInit, ViewChild } from "@angular/core";
import { TimelineComponent,
  ITimelineZoom,
  DefaultZooms,
  TimelineViewMode } from "angular-timeline-calendar";

@Component({
  template: `<timeline-calendar #timeline [zooms]="zooms"></timeline-calendar>`
})
export class MyTimelineComponent implements AfterViewInit {
  @ViewChild('timeline') timeline: TimelineComponent;
  
  zooms: ITimelineZoom[] = [
    {columnWidth: 50, viewMode: TimelineViewMode.Month},
    {columnWidth: 55, viewMode: TimelineViewMode.Month},
    {columnWidth: 50, viewMode: TimelineViewMode.Days},
    DefaultZooms[0] // You can import and use default array;
  ];
  
  ngAfterViewInit(): void {
    // Change current zoom to any of passed to 'zooms' @Input.
    this.timeline.changeZoom(this.timeline.zooms[1]);

    // Change current zoom by one step next.
    this.timeline.zoomIn();

    // Change current zoom by one step back.
    this.timeline.zoomOut();
  }
}

This is not all API of component. Maybe later I will add some documentation. Currently, you can see comments inside TimelineComponent.

4. Templates

You easily can customize timeline items view, date marker, and left panel by passing custom TemplateRef:

<timeline-calendar 
  [itemContentTemplate]="customItemTemplate"
  [dateMarkerTemplate]="customDateMarkerTemplate"
></timeline-calendar>

<ng-template #customItemTemplate let-item let-locale="locale">
  {{item.name}} {{item.startDate}} {{item.endDate}} {{locale}}
</ng-template>

<ng-template #customDateMarkerTemplate let-leftPosition="leftPosition">
  dateMarkerTemplate
</ng-template>

5. View modes

The library allows you to add custom view modes, for example, years, hours, minutes, etc. All you have to do is extends StrategyManager class. Based on the current view type it returns different strategies with a common interface which needs for calculating operations between dates and generating scale.

Here is an example of how it should look, when you want to add some additional view modes:

import { NgModule } from '@angular/core';
import {
  TimelineModule,
  TimelineViewMode,
  IScaleFormatter,
  IStrategyManager,
  StrategyManager,
} from 'angular-timeline-calendar';

enum CustomViewMode {
  CustomView = 1,
  Day = TimelineViewMode.Day,
  Week = TimelineViewMode.Week,
  Month = TimelineViewMode.Month,
}

class CustomStrategyManager extends StrategyManager implements IStrategyManager<CustomViewMode> {
  getScaleGenerator(viewMode): IScaleGenerator {
    if (viewMode === CustomViewMode.Custom) {
      return {...};  // your custom logic here
    }

    return super.getScaleGenerator(viewMode);
  };

  getViewModeAdaptor(viewMode): IViewModeAdaptor {
    if (viewMode === CustomViewMode.Custom) {
      return {...} // custom adaptor;
    }

    return super.getViewModeAdaptor(viewMode);
  }
}

@NgModule({
  imports: [
    TimelineModule.forChild({
      strategyManager: StrategyManager,
    }),
  ],
  providers: [{
    provide: StrategyManager,
    useClass: CustomStrategyManager,
  }],
})
export class MyModule {
}

Angular versions

For Angular <= 13 use 0.4.3

For Angular >= 14 use 0.5.0

Have an issue? Leave it here: https://github.com/oOps1627/angular-calendar-timeline/issues

You can support me by donation:

• https://www.paypal.com/donate/?hosted_button_id=38ZN57VTQ9TQC
• https://buymeacoffee.com/andriy1627