Module:Notify

This module is intended to facilitate access to the MediaWiki Notification system.

Users who are referenced in a signed edit receive a personal toolbar alert that they have been mentioned. The alert contains a link to the page where they have been mentioned. Because of limitations in the MediaWiki Notification system, references to more than 50 users in a single edit result in no notifications. Unregistered users (IP addresses) do not receive notifications other than from edits to their talk pages.

This module cannot be used directly from wikitext. Please use the associated templates instead. The functions provided here take no parameters, but access those passed to the parent template.

ping

This function creates up to 50 User: references with a single function call.

"Hidden" pings (i.e., pings where the user display names are blank, effectively hiding the User: links) are not supported on purpose.

Usage:

{{#invoke:Notify|ping}}

Template parameters:

unnamed

one or more user account names (up to 50)

label, label1, label2, ..., label50

(optional, default: same as the corresponding username) user's displayed name (label and label1 are synonyms.)

prefix

(optional, default: @) string to use before the first username

c

(optional, default: and) conjunction to use before the last username if more than one usernname

p

(optional, default: :) punctuation to use after the last username

---

--[[
This module provides functions to include references to User: pages more easily
to trigger the Notification system of MediaWiki using the Echo extension.

Including up to 50 User: references notifies those users on their personal
toolbars that they have been mentioned and provides a link to the page where
they have been mentioned.

Because of limitations in the Notification system, referencing more than 50
users at a time causes none of them to be notified.
]]

local p = {}

-- wrap a string to highlight an error message
local function _error( s )
	return '<span class="lua-error">' .. s .. '</span>'
end

--[[
ping

This function creates up to 50 User: references with a single function call.
It retrieves the list of users from the Template: transclusion.

Usage:
{{#invoke:Notify|ping}}
]]
function p.ping( frame )
	local args = frame:getParent().args
	local users = {}
	local display = {}
	local ret = ''
	local t, k, v

	local MAXN = 50
	local c = ( args['c'] or 'and' ) .. ' '
	local p = ( args['p'] or ':' ) .. ' '
	local prefix = args['prefix'] or '@'

	for k, v in pairs( args ) do
		if type( k ) == 'number' and k <= MAXN then
			-- unnamed parameters are names to ping
			t = nil
			if mw.ustring.match( v, '%S' ) then
				t = mw.title.new( v )
			end
			if t then
				users[k] = t.rootText
			else
				users[k] = '' -- blank invalid names for error reporting
			end
		elseif type( k ) == 'string' and mw.ustring.sub(k, 1, 5) == 'label' and
			mw.ustring.match( v, '%S' ) then
			-- label parameters are display names
			t = mw.ustring.sub(k, 6)
			if string.len( t ) == 0 then
				t = 1 -- "label" is a synonym for "label1"
			elseif mw.ustring.match( t, '%D' ) then
				t = nil -- ignore bad labels
			else
				t = tonumber( t )
			end
			if t and users[t] then
				-- need username defined before display name
				display[t] = v -- no validation of display names (for now)
			end
		end
	end

	t = table.maxn( users )
	if t > 0 then
		ret = prefix
		for k = 1, t do
			if k > 1 then
				if t > 2 or (t == 2 and c == ' ') then
					ret = ret .. ', '
				end
				if t == 2 and c ~= ' ' then
					ret = ret .. ' '
				end
				if k == t and c ~= ' ' then
					ret = ret .. c
				end
			end
			if users[k] and users[k] ~= '' then
				ret = ret .. '[[User:' .. users[k] .. '|' ..
					(display[k] or users[k]) .. ']]'
			else
				ret = ret .. _error( 'Error at user ' .. k )
			end
		end
		ret = ret .. p
	else
		ret = _error( 'No input provided' )
	end
	return ret
end

return p