Relative Time Plus

[TheFes]

Relative Time Plus

A jinja macro to display the difference between two datetimes in a readable format

Why this macro

I hear you thinking, there is already a relative_time filter/function in Home Assistant. And of course this is true, but it only returns the text in English, and always only returns the biggest time fraction. So this macro supports multiple languages and has some additional options.

How to install

You need to have Home Assistant 2023.4 or higher installed to use custom templates.
As of version 1.0 Home Assistant 2023.11 is required because it uses tests introduced in that version.

This custom template is compatible with HACS, which means that you can easily download and manage updates for it. Custom templates are currently only available in HACS when you enable experimental features. Make sure to enable it in the HACS settings, which you can access from Settings > Devices & Services > HACS When experimental features are enabled you click the button below to add it to your HACS installation

For a manual install you can copy the contents of relative_time_plus.jinja to a jinja file in your custom_templates folder.
Run the homeassistant.reload_custom_templates service call to load the file.

Languages

Current supported languages:

• Danish - C4-Dimitri
• Dutch - TheFes
• English - TheFes
• French - Pulpyyyy
• German - fastlane086
• Italian - SiriosDev
• Polish - darylosu
• Portuguese - FragMenthor

How to use

The only required field is the datetime you want to show as relative time. It can be eiter in the past or future, and you can use a datetime object, a timestamp (integer or float) or anything which can be converted to a datetime object using as_datetime.
Other optional fields are:

name	type	default	example	description
parts	integer	1	3	The number of time fractions which should be used
not_use	list or string	['millisecond']	['yr', 'minute']	Provide the time periods you don’t want to use in the output, by default only milliseconds are excluded. You can provide a list or a comma separated string, so 'yr, month' and ['yr', 'monhth'] will both work. Possible values are year, month, week, day, hour, minute, second, millisecond or the abbreviated versions yr, mth, wk, day, hr, min, sec, ms.
always_show	list or string	[]	['yr', 'mth', 'day']	Provide the time periods you always want to show, even when they are zero. With the example the output could be "0 years, 0 months and 19 days"
time	boolean	true	false	Set to false to ignore time and only compare on date
abbr	boolean	false	true	Set to true to use the abbreviated phrases
language	string	"en"	"nl"	The country code (eg dk for Denmark) for the language to be used for the output
compare_date	datetime or timestamp	now()	12345	The datetime to compare the other datetime to

Example usage:
Using a sensor state:

{% from 'relative_time_plus.jinja' import relative_time_plus %}
{{ relative_time_plus(states('sensor.uptime'), parts=3, not_use=['week', 'millisecond'], time=true, abbr=true, language='nl') }}

This will output something like
10 dg, 2 u en 7 min

Using a last_changed datetime of an entity:

{% from 'relative_time_plus.jinja' import relative_time_plus %}
{{ relative_time_plus(states.light.office.last_changed, 2) }}

This will output something like
3 hours and 1 minute

Using the always_show parameter (remove the compare_date parameter to use the current date):

{% set current_date = '2023-12-25' %}
{{ relative_time_plus('2018-12-25', compare_date=current_date, not_use='wk', always_show=['yr', 'mth', 'day'], parts=3) }}

This will output
5 years, 0 months and 0 days

Using a date string:

{% from 'relative_time_plus.jinja' import relative_time_plus %}
{{ relative_time_plus('2023-01-01', parts=2, time=false, not_use=['wk']) }}

This will output something like (assuming the current date is 9th of April 2023)
3 months and 8 days

My language is not suported

You can either issue a PR with the language phrases, or create an issue with all the required phrases (so singular, plural and abbreviated per time section, a combine word and an error text) in an issue.

[TheFes]

Update

v1.1.0

NEW FEATURES

• Added option to include milliseconds. By default this is set to false

OTHER

• Some further code improvements and cleanup

[TheFes]

Update

v1.2.0

IMPROVEMENTS

• The parameter not_use has been added to replace the month, week and millisecond parameters. If you use them in existing templates, it will still work, but not_use is more versatile, as you can exclude all time periods using it. Using not_use you can provide the time periods you don’t want to use in the output, by default only milliseconds are excluded. Possible values are year, month, week, day, hour, minute, second, millisecond or the abbreviated versions yr, mth, wk, day, hr, min, sec, ms. You can provide a list or a comma separated string, so 'yr, month' and ['yr', 'month'] will both work.
• I will probably remove the month, week and millisecond in the future, so if you don’t use the defaults, make sure to update to not_use

What’s Changed

• Add not_use parameter by @TheFes in Add not_use parameter by TheFes · Pull Request #31 · TheFes/relative-time-plus · GitHub
• Remove double sentence by @TheFes in Remove double sentence by TheFes · Pull Request #32 · TheFes/relative-time-plus · GitHub

Full Changelog: Comparing v1.1.1...v1.2.0 · TheFes/relative-time-plus · GitHub

[TheFes]

UPDATE

v1.3.0

IMPROVEMENTS

• Add always_show parameter, which can be used to show time periods when they are 0, so for example 0 years, 0 months and 12 days

BUG FIXES

• Fix calculation for years and months in specific cases

What’s Changed

• Add badges by @TheFes in Add badges by TheFes · Pull Request #33 · TheFes/relative-time-plus · GitHub
• Add always show parameter by @TheFes in Add always show parameter by TheFes · Pull Request #34 · TheFes/relative-time-plus · GitHub

Full Changelog: Comparing v1.2.0...v1.3.0 · TheFes/relative-time-plus · GitHub

[TheFes]

Seems I forgot to poste some updates here.

UPDATE (22 Mar 2024)

WARNING: THIS RELEASE CONTAINS BREAKING CHANGES

@Pipo31416 Suggested a round paramter in #39. I thought this was a great suggestion, but decided to implement it differently, causing an almost complete rewrite of the macro. So that’s why I named this release 2.0.0

BREAKING CHANGES

• The parameters month, week and millisecond are removed. They can be set by adding these time parts to the not_use parameter
• The parameter verbose is removed. It was doing the exact opposite of the parameter name, and was already replaced by the abbr parameter some time ago

IMPROVEMENTS

• a new parameter round_mode has been added. By default this is set to "floor" meaning it will round the last shown time part down. Other options are "ceil" (always round up) and "common" which will round up if the remaining timedelta is 0.5 or more of the last shown time part. (eg 30 minutes or more if the last shown time part is hour).
• you can use "all" for the show_all parameter to show all time parts. The time parts set in the not_use parameter will be leading, so eg always_show='all', not_show='day' will show all time parts (even when they are 0) expect for the days.

BUG FIXES

• the time parts set in always_show would not always be shown

What’s Changed

• Add round_mode parameter by @TheFes in Add `round_mode` parameter by TheFes · Pull Request #40 · TheFes/relative-time-plus · GitHub

Full Changelog: https://github.com/TheFes/relative-time-plus/compare/v1.3.2...v1.4.0

Other updates after 2.0

• Czech added
• Norwegian (bokmål) (nb) and Norwegegion (nynorsk) (nn) added
• Russian added
• Ukranian added
• Some bugfixes
• Fixed translations for ms in German

[parautenbach (Pieter Rautenbach)]

@TheFes

Other options are "floor" (always round up)

ceil(ing)?

[TheFes]

Ah, right, it’s ceil, adjusted now!

Thanks

[XabiX]

Hello Experts,

I am trying to replace such section of code, within a decluttering template

      secondary: >-
        {% set sec = as_timestamp(now()) -
        as_timestamp(states.[[entity]].last_changed ) %} {%set hr = (sec /
        3600)| int %} {%set min = sec / 60 - hr * 60 %} {% if hr > 1 %}
          {{"%d" % (hr)}} heures
        {% elif hr > 0 and min > 2 %}
          {{"%d" % (hr)}} h et {{"%2d" % (min)}} mins
        {% elif hr > 0 and min > 1 %}
          {{"%d" % (hr)}} h et {{"%2d" % (min)}} min
        {% elif min > 2 %} 
          {{min | int}} mins
        {% elif min > 1 %}
          {{min | int}} min
        {% elif sec > 0 %}
          {{sec | int}} s
        {% endif %}

with

      secondary: >-
        {% from 'relative_time_plus.jinja' import relative_time_plus %} {{
        relative_time_plus(states.'[[entity]]'.last_changed, parts=3,
        not_use=['week', 'millisecond'], time=true, abbr=false, language='fr')
        }}

But not sure why it’s not working. Thus my question, is relative_time_plus supposed to work also within a decluttering template? from my testing the line looks good:

Merci

[TheFes]

not familiar with decluttering card, but I notice you have single quotes around [[entity]] in the version using relative_time_plus, which you don’t have in your first version

[XabiX]

dam, that was it!

Sorry my bad. The good news is then I can confirm that relative time plus works also under decluttering

[Braakie (Raymond)]

Hey TheFes
I am using your custom template via HACS, but it displays the days in years for me.
It should be 54 days, not 54 years

{% from 'relative_time_plus.jinja' import relative_time_plus %}
{{ relative_time_plus(states('sensor.tp_link_router_uptime'), parts=3, not_use=['week', 'millisecond'], time=true, abbr=true, language='nl') }}

[TheFes]

Can you give the state of that sensor?

[Braakie (Raymond)]

The state say this:

unit_of_measurement: d
device_class: duration
friendly_name: TP-Link Router Uptime

[TheFes]

This state indicates 106 days, the template isn’t built to use such input, so it will treat the numeric value as a Unix timestamp, meaning 106 seconds after midnight UTC 1st of January 1970, which is almost 55 years ago.

You can use this

{% from 'relative_time_plus.jinja' import relative_time_plus %}
{{ relative_time_plus(now() - timedelta(days=states('sensor.tp_link_router_uptime')|float), parts=3, not_use=['week', 'millisecond'], time=true, abbr=true, language='nl') }}

[Braakie (Raymond)]

Ok thanks, this looks somewhat realistic
3 mnd, 15 dg en 15 u

[TheFes]

that could match 106.6 days

[Braakie (Raymond)]

Yes that’s right, thanks for your help, I’ll get there