Module:Year in various calendars

Module documentation[view] [edit] [history] [purge]

This module produces the sidebar opposite displaying a given Gregorian year in various different calendars.

Syntax

Simple

{{#invoke:Year in various calendars|main}}

All parameters

{{#invoke:Year in various calendars|main |year=(n) |footnotes=(footnotes) |gregcal=(article name)}}

Parameters

year

Number specifying the year to be displayed. This can be negative and also can be in the format "n BC" to display BC dates or "AD n" as an alternative to a positive number. If not specified, the current year is used.

footnotes

Any footnotes to be placed at the bottom of the sidebar.

gregcal

Name of an article to be displayed for Gregorian and Julian years (e.g. "2000 BC"). Do not include square brackets.

Microformat

The HTML mark-up produced by this template includes an hCalendar microformat that makes event/date details readily parsable by computer programs. This aids tasks such as the cataloguing of articles and maintenance of databases. For more information about the use of microformats on Wikipedia, please visit the Microformat WikiProject.

Classes used

The HTML classes of this microformat include:

• attendee
• description
• dtend
• dtstart
• location
• summary
• url
• vevent

Please do not rename or remove these classes
nor collapse nested elements which use them.

Adding new calendars

The module is set up to allow for easy addition of new calendars. Just scroll down to the "Build the box" section of the module code, and add your calendar as follows:

To display one year:

    local myCalendar = calendar:new()
    myCalendar:setLink( 'My calendar article' ) -- The name of the calendar's Wikipedia article.
    myCalendar:setYear( year + 10 ) -- Lua code linking the Gregorian calendar year to your calendar's year.
    box:addCalendar( myCalendar )

To display a year range:

    local myCalendar = calendar:new()
    myCalendar:setLink( 'My calendar article' ) -- The name of the calendar's Wikipedia article.
    myCalendar:setYearRange( year + 10, year + 11 ) -- Lua code outputting the start year and the end year of the year range.
    box:addCalendar( myCalendar )

More complicated calendars can be passed as a string to calendar:setYear().

Technical details

The module defines three classes which do the work of setting up the sidebar and displaying the data provided by the calendar functions. These are the calendarBox class, which defines the sidebar; the calendar class, which holds the data for one calendar; and the calendarGroup object, which defines a group of calendar objects with a heading.

To load these classes from another module, use the following:

local yearInOtherCalendars = require( 'Module:Year in various calendars' )
local calendarBox = yearInOtherCalendars.calendarBox
local calendarGroup = yearInOtherCalendars.calendarGroup
local calendar = yearInOtherCalendars.calendar

calendarBox class

A calendarBox object is initiated with:

local myCalendarBox = calendarBox:new{ year = yyyy, footnotes = footnotes, navbar = page name }

• year - sets the Gregorian year to base calendar calculations on. If not specified, the current year is used.
• footnotes - sets text to be displayed in a footnotes section at the bottom of the sidebar.
• navbar - sets the page name to be used by the navbar.

Calendar box objects have the following properties:

• calendarBox.year - the Gregorian year number. This is negative for BC years; for example, for the year 100 BC the value of calendarBox.year is -99. (BC years are calculated by "1 - n" rather than "0 - n", as there is no year zero.)
• calendarBox.yearText - the Gregorian year text. This is a string value of the format "n" for AD years and "n BC" for BC years.
• calendarBox.caption - the text of the box caption (the bold text that appears directly above the box). The default caption is the value of calendarBox.yearText.
• calendarBox.footnotes - the text of the box footnotes.
• calendarBox.navbar - the page name used by the navbar.

Calendar box objects have the following methods:

• calendarBox:setCaption( caption ) - sets the box caption (the bold text that appears directly above the box). The default caption is the value of calendarBox.yearText.
• calendarBox:addCalendar( obj ) - adds a calendar object or a calendar group object to the calendar box.
• calendarBox:addCalendarGroup( obj ) - an alias for myCalendarBox:addCalendar().
• calendarBox:export() - converts the calendar box object to wikicode. This calls calendar:export() and calendarGroup:export() to export calendar objects and calendar group objects.

calendar class

A calendar object is initiated with:

local myCalendar = calendar:new()

Calendar objects have the following properties:

• calendar.link - the link name.
• calendar.year - the year value. This is always a string value.

Calendar objects have the following methods:

• calendar:setLink( link, display ) - sets the link name for the calendar object. link is the name of Wikipedia's article about the calendar, and display is an optional display name for the article link.
• calendar:setRawLink( wikitext ) - sets the calendar link as raw wikitext.
• calendar:getLink() - gets the link value.
• calendar:setYear( year ) - sets the year value for the calendar. year can be a number or a string.
• calendar:setYearRange( startYear, endYear ) - sets the year value for the calendar as a year range. Both startYear and endYear must be number values.
• calendar:export() - exports the calendar to wikitext. If no link value was found, this returns nil. If a link was found but no year value was found, the calendar is output with a value of N/A for the year.

calendarGroup class

A calendarGroup object is initiated with:

local myCalendarGroup = calendarGroup:new{ heading = heading }

• heading - the wikitext heading for the calendar group (e.g. [[Hindu calendar]]s).

Calendar group objects have one property:

• calendarGroup.heading - the calendar group heading text.

Calendar group objects have the following methods:

• calendarGroup:addCalendar( obj ) - adds a calendar object to the calendar group.
• calendarGroup:export() - converts a calendar group to wikitext. Calls calendar:export() to export individual calendar objects.

See also

{{Year in various calendars}}

The above documentation is transcluded from Module:Year in various calendars/doc. (edit | history)
Editors can experiment in this module's sandbox (edit | diff) and testcases (create) pages.
Subpages of this module.

local htmlBuilder = require( 'Module:HtmlBuilder' )

--------------------------------------------------------------------
-- Calendar box class definition
--------------------------------------------------------------------

local calendarBox = {}
calendarBox.__index = calendarBox

function calendarBox:new( init )
    init = type( init ) == 'table' and init or {}
    local title = mw.title.getCurrentTitle()
    local obj = {}
    
    -- Set the year. Use the specified year if it is valid, otherwise use the current year.
    local initYear = tonumber( init.year )
    if initYear and math.floor( initYear ) == initYear and initYear ~= math.huge then
        self.year = initYear
    else
        self.year = tonumber( mw.language.getContentLanguage():formatDate( 'Y' ) )
    end
    
    self.caption = init[ 1 ] == 'BC' and title.text or self.year

    return setmetatable( obj, {
        __index = self
    })
end    

function calendarBox:addCalendar( obj )
    if not ( type( obj ) == 'table' ) then
        error( 'invalid calendar object "' .. obj .. '" passed to addCalendar' )
    end
    self.calendars = self.calendars or {}
    table.insert( self.calendars, obj )
end

calendarBox.addCalendarGroup = calendarBox.addCalendar

function calendarBox:export()
    local root = htmlBuilder.create( 'table' )
    root
        .addClass( 'infobox' )
        .addClass( 'vevent' )
        .css( 'width', '22em' )
        .tag( 'caption' )
            .css( 'font-size', '125%' )
            .tag( 'span' )
                .addClass( 'summary' )
                .addClass( 'dtstart' )
                .wikitext( self.caption )

    --local row = root.tag( 'tr' )
    for i, calendar in ipairs( self.calendars ) do
        root
            .tag( 'tr' )
                .tag( 'td' )
                    .wikitext( calendar.link )
                    .done()
                .tag( 'td' )
                    .wikitext( calendar.calculateYear( self.year ) )
                    .allDone()
    end

    return tostring( root )
end

--------------------------------------------------------------------
-- Calendar group class definition
--------------------------------------------------------------------

--  Calendar groups are used to group different calendars together. 
--  Previously, the template did this by including a table row with
--  no year value. By using objects we can do the same thing more
--  semantically.

local calendarGroup = {}
calendarGroup.__index = calendarGroup
calendarGroup.type = 'calendarGroup'

function calendarGroup:new( init )
    init = type( init ) == 'table' and init or {}
    local obj = {}
    obj.heading = init.heading
    obj.calendars = init.calendars
    return setmetatable( obj, {
        __index = self
    })
end

--------------------------------------------------------------------
-- Calendar class definition
--------------------------------------------------------------------

local calendar = {}
calendar.__index = calendar
calendar.type = 'calendar'

function calendar:new()
    local obj = {}
    return setmetatable( obj, {
        __index = self
    })
end

function calendar:setLink( link, display, italics )
    if not type( link ) == 'string' then
        return nil
    end
    display = type( display ) == 'string' and display 
    local ret
    if display then
        ret = mw.ustring.format( '[[%s|%s]]', link, display )
    else
        ret = mw.ustring.format( '[[%s]]', link )
    end
    if italics then
        ret = mw.ustring.format( "''%s''", ret )
    end
    self.link = ret
end

function calendar:setYearFunction( func )
    self.calculateYear = func
end

--------------------------------------------------------------------
-- Build the box
--------------------------------------------------------------------

local function _main( args )
    local box = calendarBox:new( args )

    -- Gregorian calendar

    local gregorian = calendar:new()
    gregorian:setLink( 'Gregorian calendar' )
    gregorian:setYearFunction(
        function( year )
            return year
        end
    )
    box:addCalendar( gregorian )
            
    -- Ab urbe condita
    
    local abUrbe = calendar:new()
    abUrbe:setLink( 'Ab urbe condita' )
    abUrbe:setYearFunction(
        function( year )
            return year + 753
        end
    )
    box:addCalendar( abUrbe )
    
    return box:export()
end

--------------------------------------------------------------------
-- Output the box and the class definitions
--------------------------------------------------------------------

local p = {}

function p.main( frame )
    -- If called via #invoke, use the args passed into the invoking
    -- template, or the args passed to #invoke if any exist. Otherwise
    -- assume args are being passed directly in from the debug console
    -- or from another Lua module.
    local origArgs
    if frame == mw.getCurrentFrame() then
        origArgs = frame:getParent().args
        for k, v in pairs( frame.args ) do
            origArgs = frame.args
            break
        end
    else
        origArgs = frame
    end
    -- Trim whitespace and remove blank arguments.
    local args = {}
    for k, v in pairs( origArgs ) do
        if type( v ) == 'string' then
            v = mw.text.trim( v )
        end
        if v ~= '' then
            args[k] = v
        end
    end
    return _main( args )
end

p.calendarBox = calendarBox
p.calendarGroup = calendarGroup
p.calendar = calendar

return p