Skip to content

Commit

Permalink
chore: update readme
Browse files Browse the repository at this point in the history
  • Loading branch information
ihym committed Jun 20, 2023
1 parent f0ed891 commit 830d89c
Show file tree
Hide file tree
Showing 2 changed files with 58 additions and 61 deletions.
116 changes: 55 additions & 61 deletions README.md
Original file line number Diff line number Diff line change
@@ -1,16 +1,15 @@
# ngx-timeago [![Build Status](https://travis-ci.org/ihym/ngx-timeago.svg?branch=master)](https://travis-ci.org/ihym/ngx-timeago) [![npm version](https://badge.fury.io/js/ngx-timeago.svg)](https://badge.fury.io/js/ngx-timeago) [![npm](https://img.shields.io/npm/dm/ngx-timeago.svg?maxAge=2592000)](https://www.npmjs.com/package/ngx-timeago) [![License: MIT](https://img.shields.io/badge/License-MIT-brightgreen.svg)](https://opensource.org/licenses/MIT)
# ngx-timeago [![npm version](https://badge.fury.io/js/ngx-timeago.svg)](https://badge.fury.io/js/ngx-timeago) [![npm](https://img.shields.io/npm/dm/ngx-timeago.svg?maxAge=2592000)](https://www.npmjs.com/package/ngx-timeago) [![License: MIT](https://img.shields.io/badge/License-MIT-brightgreen.svg)](https://opensource.org/licenses/MIT)

Live updating timestamps in Angular 6+.

[https://ihym.github.io/ngx-timeago/](https://ihym.github.io/ngx-timeago/)

Get the complete changelog here: https://github.com/ihym/ngx-timeago/releases

* [Installation](#installation)
* [Usage](#usage)
* [API](#api)
* [Contribute](#contribute)

- [Installation](#installation)
- [Usage](#usage)
- [API](#api)
- [Contribute](#contribute)

## Installation

Expand All @@ -22,34 +21,31 @@ npm install ngx-timeago --save

Choose the version corresponding to your Angular version:

| Angular | ngx-timeago |
| ----------------- | ------------------ |
| 16 | 3.x+ |
| 10,11,12,13,14,15 | 2.x+ |
| 6,7,8,9 | 1.x+ |
| Angular | ngx-timeago |
| ----------------- | ----------- |
| 16 | 3.x+ |
| 10,11,12,13,14,15 | 2.x+ |
| 6,7,8,9 | 1.x+ |

## Usage

#### 1. Import the `TimeagoModule`:

Once installed you need to import the main module into your application module by calling TimeagoModule.forRoot().
Once installed you need to import the main module into your application module by calling TimeagoModule.forRoot().

Make sure you only call this method in the root module of your application, most of the time called `AppModule`.
This method allows you to configure the `TimeagoModule` by specifying a formatter, clock and/or an intl service. You should end up with code similar to this:

```ts
import { BrowserModule } from '@angular/platform-browser';
import { NgModule } from '@angular/core';
import { TimeagoModule } from 'ngx-timeago';
import { BrowserModule } from "@angular/platform-browser";
import { NgModule } from "@angular/core";
import { TimeagoModule } from "ngx-timeago";

@NgModule({
imports: [
BrowserModule,
TimeagoModule.forRoot()
],
bootstrap: [AppComponent]
imports: [BrowserModule, TimeagoModule.forRoot()],
bootstrap: [AppComponent],
})
export class AppModule { }
export class AppModule {}
```

##### SharedModule
Expand All @@ -59,12 +55,9 @@ you can export the `TimeagoModule` to make sure you don't have to import it in e

```ts
@NgModule({
exports: [
CommonModule,
TimeagoModule
]
exports: [CommonModule, TimeagoModule],
})
export class SharedModule { }
export class SharedModule {}
```

##### Lazy loaded modules
Expand All @@ -77,13 +70,13 @@ Since lazy loaded modules use a different injector from the rest of your applica
@NgModule({
imports: [
TimeagoModule.forChild({
formatter: {provide: TimeagoFormatter, useClass: CustomFormatter},
clock: {provide: TimeagoClock, useClass: CustomClock},
intl: {provide: TimeagoIntl, useClass: CustomIntl},
})
]
formatter: { provide: TimeagoFormatter, useClass: CustomFormatter },
clock: { provide: TimeagoClock, useClass: CustomClock },
intl: { provide: TimeagoIntl, useClass: CustomIntl },
}),
],
})
export class LazyLoadedModule { }
export class LazyLoadedModule {}
```

##### I18n
Expand All @@ -92,13 +85,13 @@ By default, there is no intl service available, as the default formatter doesn't
You should provide one, if you end up with a formatter that needs it (either TimeagoCustomFormatter which is provided by the lib or your own). The purpose of the intl service is to contain all the necessary i18n strings used by your formatter.

```ts
import { NgModule } from '@angular/core';
import { BrowserModule } from '@angular/platform-browser';
import { Timeago, TimeagoIntl, TimeagoFormatter, TimeagoCustomFormatter } from 'ngx-timeago';
import { AppComponent } from './app';
import { NgModule } from "@angular/core";
import { BrowserModule } from "@angular/platform-browser";
import { Timeago, TimeagoIntl, TimeagoFormatter, TimeagoCustomFormatter } from "ngx-timeago";
import { AppComponent } from "./app";

export class MyIntl extends TimeagoIntl {
// do extra stuff here...
// do extra stuff here...
}

@NgModule({
Expand All @@ -107,27 +100,25 @@ export class MyIntl extends TimeagoIntl {
TimeagoModule.forRoot({
intl: { provide: TimeagoIntl, useClass: MyIntl },
formatter: { provide: TimeagoFormatter, useClass: TimeagoCustomFormatter },
})
}),
],
bootstrap: [AppComponent]
bootstrap: [AppComponent],
})
export class AppModule { }
export class AppModule {}
```

There is support for a large number of languages out of the box. This support is based on the string objects taken from `jquery-timeago`.

To use any of the languages provided, you will have to import the language strings and feed them to the intl service.

```ts
import { Component } from '@angular/core';
import { TimeagoIntl } from 'ngx-timeago';
import {strings as englishStrings} from 'ngx-timeago/language-strings/en';
import { Component } from "@angular/core";
import { TimeagoIntl } from "ngx-timeago";
import { strings as englishStrings } from "ngx-timeago/language-strings/en";

@Component({
selector: 'app',
template: `
<div timeago [date]="1553683912689"></div>
`
selector: "app",
template: ` <div timeago [date]="1553683912689"></div> `,
})
export class AppComponent {
constructor(intl: TimeagoIntl) {
Expand All @@ -139,16 +130,18 @@ export class AppComponent {

You can also customize the language strings or provide your own.


#### 2. Use the pipe or the directive:

This is how you do it with the **pipe**:

```html
<div>{{1553683912689 | timeago:live}}</div>
```

And in your component define live (`true` by default).

This is how you use the **directive**:

```html
<div timeago [date]="1553683912689" [live]="live"></div>
```
Expand All @@ -168,21 +161,21 @@ Once you've defined your formatter, you can provide it in your configuration.
imports: [
BrowserModule,
TimeagoModule.forRoot({
formatter: {provide: TimeagoFormatter, useClass: CustomFormatter}
})
formatter: { provide: TimeagoFormatter, useClass: CustomFormatter },
}),
],
bootstrap: [AppComponent]
bootstrap: [AppComponent],
})
export class AppModule { }
export class AppModule {}
```

#### Write your own clock

The only required method to build your own clock, is `tick` that must return an `Observable<any>`. Whenever this observable emits, the timestamp will be updated, using your formatter (and intl, if available).

```ts
import { TimeagoClock } from 'ngx-timeago';
import { Observable, interval } from 'rxjs';
import { TimeagoClock } from "ngx-timeago";
import { Observable, interval } from "rxjs";

// ticks every 2s
export class MyClock extends TimeagoClock {
Expand All @@ -199,17 +192,17 @@ Setup the clock in your module import by adding it to the `forRoot` (or `forChil
imports: [
BrowserModule,
TimeagoModule.forRoot({
clock: {provide: TimeagoClock, useClass: MyClock},
})
clock: { provide: TimeagoClock, useClass: MyClock },
}),
],
providers: [
],
bootstrap: [AppComponent]
providers: [],
bootstrap: [AppComponent],
})
export class AppModule { }
export class AppModule {}
```

## Contribute

`ngx-timeago` is packaged with [ng-packagr](https://github.com/dherges/ng-packagr) and then imported into an Angular CLI app.
To run the demo, do the following steps:

Expand All @@ -219,5 +212,6 @@ $ npm run build:lib
$ npm start
```

***
---

MIT © [Vasilis Diakomanolis](https://github.com/ihym)
3 changes: 3 additions & 0 deletions angular.json
Original file line number Diff line number Diff line change
Expand Up @@ -105,5 +105,8 @@
}
}
}
},
"cli": {
"analytics": false
}
}

0 comments on commit 830d89c

Please sign in to comment.