LitRelativeDateTime

What is LitRelativeDateTime?

LitRelativeDateTime is a Flutter package to generate relative dates to show differences in time. Theses dates are formatted in a localized and human-readable format.

Screenshots

English Locale	German Locale

How it works

The RelativeDateTime takes two DateTime objects and calculates the difference in time of both dates. This relative time difference is then used for localizing and formatting the expression in human-readable format.

How to use

First the delegates and supported locales should be declared on your MaterialApp to enable localization for your app:

localizationsDelegates: [
  GlobalMaterialLocalizations.delegate,
  GlobalWidgetsLocalizations.delegate,
  GlobalCupertinoLocalizations.delegate,
],
// Set the supported locales according to the localizations you have
// implmented on your application.
supportedLocales: [
  const Locale('en'), // English, no country code
  const Locale('de'), // German, no country code
  const Locale('ru'), // Russian, no country code
],

To display localized and formatted dates relative to another date in human-readable format, first a RelativeDateTime object should be created:

    RelativeDateTime _relativeDateTime =
        RelativeDateTime(dateTime: DateTime.now(), other: _otherDateTime);

Next the RelativeDateFormat object can be initialized. It will enable formatting the previously created RelativeDateTime:

RelativeDateFormat _relativeDateFormatter = RelativeDateFormat(
    Localizations.localeOf(context),
);

If you want to provide your own Localizations, you can do so by passing the optional localizations argument, which contains a list of RelativeDateLocalization objects:

RelativeDateLocalization(
  languageCode: 'en',
  timeUnitsSingular: [
    'second',
    'minute',
    'hour',
    'day',
    'week',
    'month',
    'year',
  ],
  timeUnitsPlural: [
    'seconds',
    'minutes',
    'hours',
    'days',
    'weeks',
    'months',
    'years',
  ],
  prepositionPast: 'ago',
  prepositionFuture: 'in',
  atTheMoment: 'now',
  formatOrderPast: [
    FormatComponent.value,
    FormatComponent.unit,
    FormatComponent.preposition
  ],
  formatOrderFuture: [
    FormatComponent.preposition,
    FormatComponent.value,
    FormatComponent.unit,
  ],
);

Now the RelativeDateFormat's format() method can be called, which takes the RelativeDateTime as an argument in order to format the RelativeDateTime to display the string on e.g. a Text widget:

Text(relativeDateFormatter.format(relativeDateTime))

There is an AnimatedBuilder implementation (AnimatedRelativeDateTimeBuilder) available to display RelativeDateTime values relative to the current timestamp. The animation renders every second to allow updating the builder every past second.

AnimatedRelativeDateTimeBuilder(
    date: _lastPressed!,
    builder: (relDateTime, formatted) {
      return Text(
        formatted,
      );
    },
  );

The Example app can provide further details on implementing relative dates.

Getting Started with Flutter

For help getting started with Flutter, view our online documentation, which offers tutorials, samples, guidance on mobile development, and a full API reference.

Example

The example folder contains an example app demonstrating how LitRelativeDateTime could implemented.

License

The source code of this repository is distributed under the BSD 3-Clause license as specified in the LICENSE file.

Libraries

controller/relative_date_format
controller/relative_date_time_controller
controller/time_difference_controller
controllers: A list of controller classes used to achive certain features.
data: A list of data objects containing read-only data.
data/meta
data/time_constants
lit_relative_date_time: A Flutter package to generate relative dates to show differences in time in localized and human-readable format.
localization/all
localization/de
localization/default
localization/en
localization/ru
localizations: A list of localization data used to localize the formatted strings.
model/lit_time_unit
model/relative_date_localization
model/relative_date_time
model/time_difference
models: A list of model classes used to store and mutate data across this package.
widget/animated_relative_date_time_builder
widget/relative_date_time_builder
widgets: A list of Flutter widget classes used to implement Builders or UI elements used across this package.