Difference between revisions of "Module:Year in various calendars/doc"

From blackwiki
Jump to navigation Jump to search
blackwiki>Mr. Stradivarius
(make code examples wrap nicely, tweak object initiation wording)
blackwiki>Mr. Stradivarius
(update after module rewrite)
Line 5: Line 5:
  
 
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:
 
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:
  
 
<div style="overflow: auto;"><source lang="lua">
 
<div style="overflow: auto;"><source lang="lua">
 
     local myCalendar = calendar:new()
 
     local myCalendar = calendar:new()
 
     myCalendar:setLink( 'My calendar article' ) -- The name of the calendar's Wikipedia article.
 
     myCalendar:setLink( 'My calendar article' ) -- The name of the calendar's Wikipedia article.
     myCalendar:setYearFunction(
+
     myCalendar:setYear( year + 10 ) -- Lua code linking the Gregorian calendar year to your calendar's year.
        function( year )
 
            -- Lua code linking the Gregorian calendar year to your calendar's year.
 
        end
 
    )
 
 
     box:addCalendar( myCalendar )
 
     box:addCalendar( myCalendar )
 
</source></div>
 
</source></div>
  
If you want to display just one year, then the Lua code should return one number value. If you want to display a year range, then the Lua code should return two number values. More complicated calendars can be displayed as text.
+
To display a year range:
 +
 
 +
<div style="overflow: auto;"><source lang="lua">
 +
    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 )
 +
</source></div>
 +
 
 +
More complicated calendars can be passed as a string to <code>calendar:setYear()</code>.
  
 
=== Technical details ===
 
=== Technical details ===
Line 41: Line 48:
 
* <code>footnotes</code> - sets text to be displayed in a footnotes section at the bottom of the sidebar.
 
* <code>footnotes</code> - sets text to be displayed in a footnotes section at the bottom of the sidebar.
 
* <code>navbar</code> - sets the page name to be used by the [[Template:Navbar|navbar]].
 
* <code>navbar</code> - sets the page name to be used by the [[Template:Navbar|navbar]].
 +
 +
Calendar box objects have the following properties:
 +
* <code>calendarBox.year</code> - the Gregorian year number. This is negative for BC years; for example, for the year 100 BC the value of calendarBox.year is <code>-99</code>. (BC years are calculated by "1 - n" rather than "0 - n", as there is no year zero.)
 +
* <code>calendarBox.yearText</code> - the Gregorian year text. This is a string value of the format "n" for AD years and "n BC" for BC years.
 +
* <code>calendarBox.caption</code> - the text of the box caption (the bold text that appears directly above the box). The default caption is the value of <code>calendarBox.yearText</code>.
 +
* <code>calendarBox.footnotes</code> - the text of the box footnotes.
 +
* <code>calendarBox.navbar</code> - the page name used by the navbar.
  
 
Calendar box objects have the following methods:
 
Calendar box objects have the following methods:
* <code>myCalendarBox:addCalendar( obj )</code> - adds a calendar object or a calendar group object to the calendar box.
+
* <code>calendarBox:setCaption( ''caption'' )</code> - sets the box caption (the bold text that appears directly above the box). The default caption is the value of <code>calendarBox.yearText</code>.
* <code>myCalendarBox:addCalendarGroup( obj )</code> - an alias for <code>myCalendarBox:addCalendar( obj )</code>.
+
* <code>calendarBox:addCalendar( ''obj'' )</code> - adds a calendar object or a calendar group object to the calendar box.
* <code>myCalendarBox:export()</code> - converts the calendar box object to wikicode. This method does most of the work - it detects whether the objects it processes are calendar objects or calendar group objects, and handles most of their formatting, as well as the formatting of the sidebar itself.
+
* <code>calendarBox:addCalendarGroup( ''obj'' )</code> - an alias for <code>myCalendarBox:addCalendar( obj )</code>.
 +
* <code>calendarBox:export()</code> - converts the calendar box object to wikicode. This calls <code>calendar:export()</code> and <code>calendarGroup:export()</code> to export calendar objects and calendar group objects.
  
 
==== calendar class ====
 
==== calendar class ====
Line 54: Line 69:
 
<nowiki>local myCalendar = calendar:new()</nowiki>
 
<nowiki>local myCalendar = calendar:new()</nowiki>
 
}}
 
}}
 +
 +
Calendar objects have the following properties:
 +
* <code>calendar.link</code> - the link name.
 +
* <code>calendar.year</code> - the year value. This is always a string value.
  
 
Calendar objects have the following methods:
 
Calendar objects have the following methods:
* <code>myCalendar:setLink( link, display, italics )</code> - sets the link name for the calendar object. <code>link</code> is the name of Wikipedia's article about the calendar, <code>display</code> is an optional display name for the article link, and if <code>italics</code> evaluates to <code>true</code> the link is displayed in italics.
+
* <code>calendar:setLink( ''link'', ''display'' )</code> - sets the link name for the calendar object. <code>''link''</code> is the name of Wikipedia's article about the calendar, and <code>''display''</code> is an optional display name for the article link.
* <code>myCalendar:setLinkFunction( function( year ) ''block'' end )</code> - sets a function that specifies the link name depending on the Gregorian year value. The output must be a string, or if the output evaluates to <code>nil</code> the calendar is not displayed.
+
* <code>calendar:setRawLink( ''wikitext'' )</code> - sets the calendar link as raw wikitext.
* <code>myCalendar:setYearFunction( function( year ) ''block'' end )</code> - sets a function to output the calendar year depending on the Gregorian year value. The function should output a number for a single year value, or two numbers for a year range. It can also output a string value for more complicated calendars. If the function evaluates to <code>nil</code> then the calendar box will display <code>''N/A''</code>.
+
* <code>calendar:getLink()</code> - gets the link value.
 +
* <code>calendar:setYear( ''year'' )</code> - sets the year value for the calendar. <code>''year''</code> can be a number or a string.
 +
* <code>calendar:setYearRange( ''startYear'', ''endYear'' ) - sets the year value for the calendar as a year range. Both <code>''startYear''</code> and <code>''endYear''</code> must be number values.
 +
* <code>calendar:export()</code> - exports the calendar to wikitext. If no link value was found, this returns <code>nil</code>. If a link was found but no year value was found, the calendar is output with a value of <code>''N/A''</code> for the year.
  
 
==== calendarGroup class ====
 
==== calendarGroup class ====
Line 65: Line 87:
  
 
{{pre|
 
{{pre|
<nowiki>local myCalendarGroup = calendarGroup:new{ heading = </nowiki>''heading''<nowiki>, calendars = { </nowiki>''calendar object 1'', ''calendar object 2'', ... <nowiki>} }</nowiki>
+
<nowiki>local myCalendarGroup = calendarGroup:new{ heading = </nowiki>''heading''<nowiki>} }</nowiki>
 
}}
 
}}
 
* <code>heading</code> - the wikitext heading for the calendar group (e.g. <code><nowiki>[[Hindu calendar]]s</nowiki></code>).
 
* <code>heading</code> - the wikitext heading for the calendar group (e.g. <code><nowiki>[[Hindu calendar]]s</nowiki></code>).
* <code>calendars</code> - an [[Lua (programming language)#As array|array]] containing calendar objects to be passed to a calendar box object.
 
  
Calendar group objects have only one method:
+
Calendar group objects have one property:
* <code>myCalendarBox:addCalendar( obj )</code> - adds a calendar object to the calendar group.
+
* <code>calendarGroup.heading</code> - the calendar group heading text.
 +
 
 +
Calendar group objects have the following methods:
 +
* <code>calendarGroup:addCalendar( ''obj'' )</code> - adds a calendar object to the calendar group.
 +
* <code>calendarGroup:export()</code> - converts a calendar group to wikitext. Calls <code>calendar:export()</code> to export individual calendar objects.
  
 
=== See also ===
 
=== See also ===
  
 
{{tl|Year in other calendars}}
 
{{tl|Year in other calendars}}

Revision as of 05:26, 31 August 2013

Script error: No such module "Year in other calendars". Template:Year in other calendars/doc

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 other 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( obj ).
  • 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 other calendars}}