Module:SSC base/doc

Ceci est la page de documentation pour Module:SSC base

This is a base class to be inherited by special entity classes. It provides basic functionality like argument plausibility tests, semantic storage, display of an infobox, etc.

Access to the semantíc data (reading and writing) is provided by Extension:Semantic Scribunto.

Usage

To build an entity class, create an appropriate config module. Use Module:SSC base/config as a template. Then put the following code on a module page to build the entity class:

local config = mw.loadData( 'Module:<entity module>/config' )
local baseClass = require( 'Module:SSC base' )

local class = baseClass:new( config )

return class

"Abstract" methods

There are several methods in this class that should/can be implemented by your entity class.

setDefaults( data )

Can be used to insert some defaults into the datastream after arguments from the template call are processed but before they are stored semantically. Here is the husk:

function class:setDefaults( data )
	local data = data
	-- for example
	data.title = data.title or mw.title.getCurrentTitle().text
	return data
end

data is a table that holds your arguments after preprocessing. Insert your defaults but don't forget to return the data table at the end.

alterDataAfterStorage( data )

Manipulates the data table after semantic data is stored but before the infobox is displayed.

function class:alterDataAfterStorage( data )
	local data = data
	-- for example
	data.header1 = 'Base data'
	return data
end

Note: a field in your data table is only added to your infobox, if the class' configuration says so.

Public methods

renderPage()

This is usually called in a function, which is invoked on the entity's module page. It provides this functions:

filter known and existant argument data from template arguments
checks for existance of mandatory arguments
converts all list fields into a table
saves the semantic data
builds a nice infobox (utilizing Module:Infobox)
places the page in the appropriate category

local entity = require( 'Module:<entity module>/class' ):new()
return entity:renderPage()

retrieveClassData( filter )

This can be used to retrieve all data stored for entities of that class.

If you want a subset, use string filter like the selector in an ask query (e.g. '[[property::value]] [[property2::value2]]').

local entityClass = require( 'Module:<entity module>/class' )
local classData = entityClass:retrieveClassData()
-- now classData is a table of up to 500 rows, each containing data about an entity
-- each row is a table, indexed by fieldnames as defined in the parameters table in entity class' config

Module boilerplates

You need a base module. This bridges your template and your class module and "exposes" some functions.

Boilerplate for your Module:Entity
local p = {} function p.main( frame ) local entity = require( 'Module:Entity/class' ):new() return entity:renderPage() end return p

Then there is the class, which inherits its main functionality from Module:SSC base. Remember, that you should fill the two "abstract" methods setDefaults() and alterDataAfterStorage.

Boilerplate for your Module:Entity/class

local config = mw.loadData( 'Module:Entity/config' )
local class = require( 'Module:SSC base' )

local entity = class:new( config )

function entity:alterDataAfterStorage( data )
	local data = data

	if not data.nonEmtyField then
		data.profession = 'unknown'
	end
	
	if data['date of birth'] and mw.ustring.find( data['date of birth'], '/', 1, true ) then
		local date = mw.text.split( data['date of birth'], '/', true )
		data['date of birth'] = date[2] .. '.' .. date[1] .. '.' .. date[3]
	end
	
	return data
end

function entity:setDefaults( data )
	local data = data
	data.title = data.title or mw.title.getCurrentTitle().text
	return data
end

function entity:addSomeData()
	local cbData, query = comicBooks:retrieveClassData( '[[Has comic book writer::' .. mw.title.getCurrentTitle().text .. ']]' )
	cbData = cbData or {}
	return '\n=== Works ===\n' .. self:extractWorks( cbData ) .. '\n'
		.. '=== Collaborations ===\n' .. self:extractCollaborations( cbData ) .. '\n'
end

function entity:renderPage()
	return class.renderPage( self )
		.. self:addSomeData()
end

return person

Finally, each class needs a config file. Here is the structure to fill:

Boilerplate for your Module:Entity/config

return {
	-- **********************
	-- * mandatory settings *
	-- **********************
	
	-- this is your type of entity
	entityType = '',
	
	-- this is the category, the entities of the class will be put in
	category = '',
	
	-- lists all available pairs "template parameter" -> "semantic property"
	-- if you want to have a field in the template without storing it semantically, set it to true
	parameters = {
		-- example entries
		firstname			= 'has firstname',
		lastname			= 'has lastname',
		nostore				= true,
	},

	-- tell the class, which fields are mandatory
	-- for every argument in this list not present on your page's template call,
	-- an error will be displayed
	mandatory = { 'firstname', 'firstname', ... },
	
	-- these fields possibly contain more than one value
	listFields = { '' },
	
	-- separator used in list fields
	delimiter = ',',

	-- *********************
	-- * optional settings *
	-- *********************
	-- the headline of the entity's page
	headline = 'This is a page about an entity',

	-- INFOBOX CONFIG HERE
	-- here you can disable your infobox
	omitInfoBox = false,

	-- this is the name of the field, used as title in the infobox
	titleField = 'name',
	
	-- this defines, which fields are put into your infobox and in which order
	infoboxConfig = {
		-- for every row in your infobox, add a table here, containing at least the entry "field" which
		-- refers to the data field to display. if you omit the entry "label", the field will be displayed
		-- over both columns
		{ field = 'firstname', label = 'Firstname' },
		{ field = 'lastname', label = 'Lastname' },
		{ field = 'nostore', label = 'No Store' },
		-- why is this not defined as an array: lua does not maintain the order of items in an array but accesses them randomly
	},
	
	-- configure here, which fields should be linked (or form-linked)
	linkFields = {
		-- if a field is set to true, it will be linked
		-- if it is set to a string, #formlink will be used
		firstname	= true,
		formEntry	= 'FormForEntrys'
	},
}

Example

See Module:Person/class, method person:getPersonVitae() for an example.