Module:TimeAgo
Note to editors: Please don't categorize this template by editing it directly. Instead, place the category in its documentation page, in its "includeonly" section.
The Time ago template calculates the amount of time which has passed since a provided timestamp. The result is a string similar to one of the examples below. This template should not be used with "subst" unless you don't want the stamp to change as the user refreshes the page.
Note that due to Wikipedia's caching mechanisms, you may need to purge a page using this template to update the dynamic value. See the section Purge below.
The result is rounded down. "Month" is defined as 31 days.
Usage
[edit]{{Time ago|timestamp}}
The timestamp can be almost any solid, readable format but to avoid ambiguity mistakes, one of the styles below is preferred.
magnitude
parameter can be set to explicitly use certain unit. Allowed values are:seconds
,minutes
,hours
,days
,weeks
,months
andyears
.min_magnitude
parameter can be set to use the specified unit or bigger units. Allowed values are:seconds
,minutes
,hours
,days
,months
andyears
.ago
parameter can be set to override the default usage of the text "ago
". If the parameter is blank but not missing (i.e.{{time ago|2008|ago=}}
), then the text "ago" is suppressed altogether. For future dates, setting "ago" as blank but not missing will suppress the text "time" (i.e. "2 years" instead of "2 years' time").
Spelling out numbers
[edit]Numbers from 1 to 100 can be spelled out in their equivalent English word by using the spellout
parameter. If spellout
is set to "yes", "y", "true" or "1", all numbers from 1 to 100 will be spelled out. If spellout
is set to "auto", only numbers from 1 to 9 will be spelled out, as per the recommendations at MOS:NUMERAL.
It is also possible to set a custom maximum value for spelling out by using the spelloutmax
parameter. For example, setting |spellout=yes
and |spelloutmax=24
will result in all numbers less than or equal to 24 being spelled out, and all numbers greater than 24 appearing as numerals.
Purge link
[edit]Add the parameter |purge=yes
to add a purge link.
Examples
[edit]- {{#invoke:TimeAgo|main| -83 minutes}} → 83 minutes ago
- {{#invoke:TimeAgo|main| -334 minutes}} → 5 hours ago
- {{#invoke:TimeAgo|main| +334 minutes}} → 5 hours' time
- {{#invoke:TimeAgo|main|{{REVISIONTIMESTAMP}}}} → 8 years ago
- {{#invoke:TimeAgo|main| Jan 21, 2001 3:45 PM}} → 23 years ago
- {{#invoke:TimeAgo|main| 3:45 pm, 21 Jan 2001}} → Error: first parameter cannot be parsed as a date or time.
- {{#invoke:TimeAgo|main| Nov 6 2008}} → 15 years ago
- {{#invoke:TimeAgo|main| Nov 6 2008|3=magnitude=weeks}} → 824 weeks ago
- {{#invoke:TimeAgo|main| Nov 6 2008|3=min_magnitude=days}} → 15 years ago
- {{#invoke:TimeAgo|main| Nov 6 2008|3=min_magnitude=years}} → 15 years ago
- {{#invoke:TimeAgo|main| Nov 6 2008|3=ago=in the past}} → 15 years in the past
- {{#invoke:TimeAgo|main| Nov 6 2008|3=purge=yes}} → 15 years ago (purge)
- {{#invoke:TimeAgo|main| 2008-11-06}} → 15 years ago
{{Time ago| June 1, 2009|spellout=yes}}
→ fifteen years ago{{Time ago| June 1, 1999|spellout=yes}}
→ twenty-five years ago{{Time ago| June 1, 2009|spellout=auto}}
→ 15 years ago{{Time ago| June 1, 1999|spellout=auto}}
→ 25 years ago{{Time ago| June 1, 1989|spellout=yes|spelloutmax=15}}
→ 35 years ago{{Time ago| June 1, 1989|spellout=yes|spelloutmax=25}}
→ 35 years ago
TemplateData
[edit]This template calculates the amount of time which has passed since a provided timestamp.
Parameter | Description | Type | Status | |
---|---|---|---|---|
Timestamp | 1 | Base timestamp for calculation of passed time. Example format: Nov 6 2008, see template documentation for other supported formats. | String | required |
magnitude | magnitude | Explicitly sets a specific unit to display return value. Allowed values are: seconds, minutes, hours, days, weeks, months and years. | String | optional |
min_magnitude | min_magnitude | Sets a minimum unit to display return value. Allowed values are: seconds, minutes, hours, days, months and years. | String | optional |
ago | ago | Override the default usage of the text 'ago'. If it is blank but not missing then 'ago' will be removed completely; for future dates, this will remove the text 'time' as well. | String | optional |
notext | notext | if set to yes will not show any text, only the nubmer | String | optional |
Purge link | purge | Add the parameter purge=yes to add a WP:PURGE link. | String | optional |
Spell out numbers | spellout | If set to "yes", "y", "true" or "1", numbers from 1 to 100 are spelled out as English words. If set to "auto", numbers from 1 to 9 are spelled out. | Line | optional |
Spell out max | spelloutmax | The maximum number to be spelled out as an English word. | Number | optional |
-- Replacement for [[Template:Time ago]]
local numberSpell = require('Module:NumberSpell')._main
local yesno = require('Module:Yesno')
local p = {}
-- Table to convert entered text values to numeric values.
timeText = {
['seconds'] = 1,
['minutes'] = 60,
['hours'] = 3600,
['days'] = 86400,
['weeks'] = 604800,
['months'] = 2678400,
['years'] = 31557600
}
-- Table containing tables of possible units to use in output.
timeUnits = {
[1] = { 'second', 'seconds', "second's", "seconds'" },
[60] = { 'minute', 'minutes', "minutes'", "minutes'" },
[3600] = { 'hour', 'hours', "hour's", "hours'" },
[86400] = { 'day', 'days', "day's", "days'" },
[604800] = { 'week', 'weeks', "week's", "weeks'" },
[2678400] = { 'month', 'months', "month's", "months'" },
[31557600] = { 'year', 'years', "year's", "years'" }
}
function p._main( args )
-- Initialize variables
local lang = mw.language.getContentLanguage()
local auto_magnitude_num
local min_magnitude_num
local result
local result_unit
local magnitude = args.magnitude
local min_magnitude = args.min_magnitude
local purge = args.purge
local spell_out = args.spellout
local spell_out_max = args.spelloutmax
-- Add a purge link if something (usually "yes") is entered into the purge parameter
if purge then
purge = ' <span class="plainlinks">([' .. mw.title.getCurrentTitle():fullUrl('action=purge') .. ' purge])</span>'
else
purge = ''
end
-- Check that the entered timestamp is valid. If it isn't, then give an error message.
local noError, inputTime = pcall( lang.formatDate, lang, 'U', args[1], true )
if not noError then
return '<strong class="error">Error: first parameter cannot be parsed as a date or time.</strong>'
end
-- Store the difference between the current time and the inputted time, as well as its absolute value.
local timeDiff = lang:formatDate( 'U', nil, true ) - inputTime
local absTimeDiff = math.abs( timeDiff )
if magnitude then
auto_magnitude_num = 0
min_magnitude_num = timeText[magnitude]
else
-- Calculate the appropriate unit of time if it was not specified as an argument.
local autoMagnitudeData = {
{ denom = 63115200, amn = 31557600 },
{ denom = 5356800, amn = 2678400 },
{ denom = 172800, amn = 86400 },
{ denom = 7200, amn = 3600 },
{ denom = 120, amn = 60 }
}
for i, t in ipairs( autoMagnitudeData ) do
if absTimeDiff / t.denom >= 1 then
auto_magnitude_num = t.amn
break
end
end
auto_magnitude_num = auto_magnitude_num or 1
if min_magnitude then
min_magnitude_num = timeText[min_magnitude]
else
min_magnitude_num = -1
end
end
if not min_magnitude_num then
-- Default to seconds if an invalid magnitude is entered.
min_magnitude_num = 1
end
local magnitude_num = math.max( min_magnitude_num, auto_magnitude_num )
local result_num = math.floor ( absTimeDiff / magnitude_num )
local punctuation_key, suffix
if timeDiff >= 0 then -- Past
if result_num == 1 then
punctuation_key = 1
else
punctuation_key = 2
end
if args.ago == '' then
suffix = ''
else
suffix = ' ' .. (args.ago or 'ago')
end
else -- Future
if args.ago == '' then
suffix = ''
if result_num == 1 then
punctuation_key = 1
else
punctuation_key = 2
end
else
suffix = ' time'
if result_num == 1 then
punctuation_key = 3
else
punctuation_key = 4
end
end
end
result_unit = timeUnits[ magnitude_num ][ punctuation_key ]
-- Convert numerals to words if appropriate.
spell_out_max = tonumber( spell_out_max ) -- Would cause script errors if not a number.
local result_num_text
if ( spell_out == 'auto' and 1 <= result_num and result_num <= 9 and result_num <= ( spell_out_max or 9 ) )
or ( yesno( spell_out ) and 1 <= result_num and result_num <= 100 and result_num <= ( spell_out_max or 100 ) )
then
result_num_text = numberSpell( result_num )
else
result_num_text = tostring( result_num )
end
if args.notext == 'yes' then
result = result_num_text
else
result = result_num_text .. ' ' .. result_unit .. suffix -- Spaces for suffix have been added in earlier.
end
return result .. purge
end
function p.main( frame )
local args = require( 'Module:Arguments' ).getArgs( frame, {
valueFunc = function( k, v )
if v then
v = v:match( '^%s*(.-)%s*$' ) -- Trim whitespace.
if k == 'ago' or v ~= '' then
return v
end
end
return nil
end,
wrappers = 'Template:Time ago'
})
return p._main( args )
end
return p