Modul:Foundationclass/doc

This is a Template for Class Modules. It implements a class in Lua using Module:Middleclass and provides serveral static and public methods, commonly used in the typical form>page>store process.

Usage

This is in a way an abstract class. It provides some static and public methods for resuse, and also maintains a store of private properties. If can be used to fast and easily create a typical class module that can handle:

• creating an appropriate form
• supplying your respective template with functionalities for
  • object initialization via template parameters, arguments, and datastore (self initialization)
  • general data assesment (basic plausibility tests)
  • data storage (supported are cargo and semantic media wiki)
  • error and warnings management
  • output and rendering
• creating a template documentation

You can and should adjust the module in this methods:

• individual attribute adjustment for the semantic forms fields
• individual plausibility testing
• individual data initialization
• individual data store adjustments before stashing

You can access the objects core data store with getCoreData() and its uid with getUid().

How-To

This is, what you have to do (see Useful templates for content of the corresponding pages):

1. create your base module Module:Name
2. create your class module Module:Name/class. For this, copy lua sample code below this list and apply the following changes:
   1. change all occurences of className into your class name
   2. change the highlighted lines and replace 'Name' with the Name of your module
   3. implement the abstract methods:
      1. myAgumentProcessing(coreData)
      2. myDataAdjustments(data)
      3. myPlausibilityTest(args)
      4. myStashAdjustments(stash)
      5. static:mySfDynamicFieldAttribute(fieldname, attribute, value)
   4. for the usual output generation, implement (shells given in sample code)
      1. addInfobox()
      2. addPageBody()
3. create and fill your configuration Module:Name/config
4. create your template Template:Name
5. create your form Form:Name
6. if applicable, create your category page Category:Name
7. fill in documentation:
   1. of your base module (place one invoke below the first comment and before the includeonly)
   2. of your class module (new docu for your own public, static and private methods (which you can probably copy from other classes) and one invoke to show the inheritance. Sample code provided in Useful templates
   3. of your class module's configuration (just copy content)
   4. of your template (one invoke below the first comment and before the includeonly)

private, public, class or instance

Zugriffsmatrix

-	public	private
instance	function MyClass:publicMethod() MyClass.publicProperty	local _privateMethod = function (self, var) _private[self]._privateProperty
class	function MyClass.static:staticMethod() MyClass.static.staticProperty -- accessing MyClass.staticProperty -- being "outside": MyClass:staticMethod() -- being inside a static method self:staticMethod() -- being inside a public method self.class:staticMethod()	local _privateMethod = function (self, var) local _privateProperty

private

property

you can declare a property private in one of two ways:

1. anywhere, preferably before your constructor, declare a local var to have a private propery, this is not recommended, but it allows you to declare a private property, that can be used by your static methods. thus being somewhat private static
2. for your instances, you can use the table _private[self] as a private store. it is available after your construrctor has been called (since this is an instance attribute)

method

a private method is declared thus: local _privateMethod = function(self, var). If you want to use the method in an public/static/other private method before it is declared (aka: the calling method is on a lower line number than your private method's declaration), decare it ahead and define it later:

local _privateImportantMethod
..
privateImportantMethod = function(self, var)

private class and instance methods are basically the same.

public

property

can be dclared via class.property. DONT DO THIS. It is bad style!

method

Declare them class:publicMethod(var). They are, after all, public

NOTE: public methods can be called by an instance, but also as static method:

function Class:public()
	return 'public: ' .. tostring(self)
end

local me = Class:new()
me.public()	-- returns "public: Instance of class Class"
Class:public()	-- returns "public: class Class"

static

property

Declare a static property like this: class.static.myProperty = 'Hello World'. This produces a public property, that can be accessed by the class, childclasses or instances via *.myProperty (replace * with class, object, childclass, ...)

method

Much the same as static properties, but you should use the colon operator: function Class.static:staticMethod() when definig the method. On accessig this method, you should use the dot-notation: function Class.staticMethod(self)

NOTE: Other than public methods, they can only be called by the class, but not by an instance:

function Class.static:static()
	return 'static: ' .. tostring(self)
end

local me = Class:new()
me.static()	-- returns "error:  attempt to call method 'static' (a nil value)"
Class:static()	-- returns "static: class Class"
Class.static(self)	-- this is not called via colon (:) operator as to preserve the childClass's scope when inheriting from this class

Methods

Constructor

new(uid, superhandler)

Creates a new Object for the class.

uid

variable, suggested

used to identify the object. defaults to mw.title.getCurrentTitle().prefixedText

superhandler

object of childclass of Foundationclass, optional

supply the superhandler, if you instanciate an object within another object. the instanciated object will pass errors and warnings to the superhandler and forgo adding an object category

return

object, of the class

Abstract Methods

 

myArgumentProcessing(coreData)

Performs the individual argument processing in initFromArgs(args) right before inititializing it.

coreData

table, mandatory

the core data of the object. the one to process individually before initialization

return

table, the new core data array to be used

myDataAdjustments(data)

Performs a transformation form data (coming from the datastore) into data used for argument processing. This is called by initFromData(data) (for smw: after property to parameter conversion) and is directly passed to initFromArgs(args) and subsequently plausibility test.

data

table, mandatory

a data table coming directly from the data store

return

table, the new data table suiteable for argument processing

myPlausibilityTest(args)

Performs the individual plausibility tests in initFromArgs(args) before entering the initialization part. NOTE: The return value will be ignored. If this finds errors, it must add them to the list of errors via addError(errortext).

args

table, mandatory

arguments passed to the template to be checked

return

boolean, whether the object is plausible or not.

myStashAdjustments(stash, storeType)

Can adjusts the stash in storeData() right before storing it.

stash

table, mandatory

the array of data to be saved (in the form fieldname: value)

storeType

string, mandatory

type of storage method used with the current call (either 'cargo' or 'swm'). In case you use both stores and your stash adjustment differs with each of this methods

return

table, the new stash

FoundationClass:mySfDynamicFieldAttribute(fieldname, attribute, value)

For some semantic form fields there are attribute values, that are not static, thus can not be provided at forehand in the configuration file. This method does the trick to adapt them at runtime shortly before the field is rendered. Essentially: the method checks, if it has a special rule for the pair fieldname:attribute and if so, calculates the new value. if not, the old value is returned. Note, that you can completely disable a form field with this when you return false on attribute "disable".

fieldname

string, mandatory

the form field's name, needed to match current paring to an existing special treatment rule

attribute

string, mandatory

the form field's attribute, needed to match current paring to an existing special treatment rule

value

variable, mandatory

the value, that is already provided in the configuration file. this will be adapted by the method, if there is a special rule for the pair fieldname:attribute.

return

string, the value to be used forthwith (which can be the old one or a freshly calculated)

Public methods

 

addCategory(category)

Prepares to add the page to category category. Note: until you actually call render() or renderCategories(), this will not be implemented

category

string, mandatory

the name of the category, to add the page to

return

boolean, true

addError(errortext)

adds errortext as new error to the list of errors, rendered at a later time.

errortext

string, mandatory

text added to list of errors

return

boolean, whether adding was successful or not

addInfobox()

If no errors and data is present, adds an infobox to the object's output. NOTE: This is a shell method and should be overwritten!

return

boolean, whether adding was successful or not

addOutput(content)

Adds something to the page's output. Something can be of type string, int, or table (that needs to have __tostring() implemented)

content

string, int, or table; mandatory

content element that is added to page's output

return

boolean, whether adding was successful or not

addPageBody()

Adds a page body (all content besides the infobox) to the object's output: Errors and Warnings, sample configuration, statistics, ... Of course, only if there is data. NOTE: This is a shell method and should be overwritten!

return

boolean, whether adding was successful or not

addWarning(warning)

adds warning as new warning to the list of warnings, to be rendered at a later time (with renderWarnings()).

warning

string, mandatory

text added to list of warnings

return

boolean, whether adding was successful or not

getCoreData()

Returns the table of coreData

return

table, the value for _private[self].coreData, emtpy if not initialized

getUid()

Returns the object's uid, nil if not set

return

variable, the value for _private[self].uid

goodToGo()

Is this a proper object (with data and no errors)

return

boolean, whether we are proper initialized

initFromArgs(args)

Initializes the object with a data table, containing arguments (template parameter). Does plausibility tests and mangling of input and either fills list of errors or adds input to the object's data. {{{1}}}

initFromData(data)

Initializes the object with a data table, coming from the datastore. Depending on datastore, that means that the table keys might be different than when using arguments form the template. Does plausibility tests and mangling of input and either fills list of errors or adds input to the object's data. {{{1}}}

initMyself(uid)

Initializes the object with data from the data store. The method queries for the object's uid in the container defined by Foundationclass.globalConfig.uidFieldName (can be set to an infividual name in Module:Foundationclass/globalconfig) in either the class's table (in case of datastore cargo) or for objects that have Foundationclass.globalConfig.smwClassProperty set to class.name (in case of datastore smw). The uid was either passed to the method (priority) or submitted to the constructor. Does NOT do plausibility tests and mangling of input but assumes the data comes directly from the data store and thus can be trusted (i.e. passes _plausibilityTest())

uid

string, optional

the data, the object can use to identify itself. This field can be omitted, in which case the uid that was submitted to the constructor will be used.

return

boolean, whether initialization was successful or not

render()

Renders the object's output

return

string, the textual representation of the object (which can vary, depending on what add*-methods you called before)

renderCategories()

Renders the object's categories (if any), thus adding them to the output stream and in turn sorting the page in it, if and only if render() is called on the object's page (when self:getUid == Foundationclass/doc).

return

object of type mw.html, the wikitext necessary to add the page to the categories

renderErrors()

Renders the object's errors (if any)

return

object of type mw.html, the representation of the list of errors

renderWarnings()

Renders the object's warnings (if any)

return

object of type mw.html, the representation of the list of warnings

setSortkey(sortkey)

Sets a default sortkey for this page using the magic word DEFAULTSORT. Only applies, if no superhandler is given.

sortkey

string, mandatory

new sortkey for this page

return

void

setUid(value)

Sets my uid to the given value. normally this should be set by constructor

value

string/integer, mandatory

new valued for my uid

return

boolean, true/false

storeData()

If this was initialized with outside data and there are no errors, stores the arguments in an appropriate data store (smw or cargo). In case of cargo, also calls the necessary #cargo_declare parser function if in the template namespace.

return

boolean, whether store was successful or not

Static methods

 

FoundationClass:categorize()

Placed on one to class's pages (usually not on the class object pages), this calculates the necessary (meta-) category, to put the page in, using pagetitle, subpagetitle, namespace, and so on. Your project's categories (defined in Module:Foundationclass/globalconfig) are used.

return

string, to be put on page, so that it will be categorized

FoundationClass:categoryPage()

Procudes the output for our corresponding category page. Including the message box and the display of the data structure.

return

object of type mw.html, the representation of the category page's content

FoundationClass:cargoGenerateTableStructure()

Produces a cargo table declaration array (fieldname => declaration of field) that can be used in method storeData() for cargo_declare.

return

table, data structure for cargo table

FoundationClass:explainDataStore()

Produces a textual explanation of the used datastructure (table definition for cargo or property list and types for smw) that can be printed on various dodumentation pages

return

string, a textual explanation

FoundationClass:formRedlink(target, form, linktext, queryString)

Takes a pagename (target) and a formname (form) and then generates a link to that page if the page exists. Otherwise it links to the form to create the page. Linktext is target per default, if you do not provide linktext

target

string, mandatory

the pagename (including namespace) to link to

form

string, mandatory

the name of the form (w/o the form namespace!!) to fallback to, if page does not exist

linktext

string, optional

text you want to display instead of target

queryString

string, optional

the query string provided to the form, e.g. 'Template[page]=' .. mw.title.getCurrentTitle().prefixedText

return

string, the requested link

FoundationClass:gardeningCategoryPage()

Procudes the output for the class' gardening category page (if any). Includung the message boxes.

return

object of type mw.html, the representation of the gardening category page's content

FoundationClass:mwLink(object)

Takes object and links it (adding square brackets). If object is a table, it iterates over it with lua's mw.text.listToText()

object

mixed

object to return as linked string(s)

return

string, with all elements of object mw-linked

FoundationClass:sfGenerateForm()

Generates all output necessary for a form, that can be used to create or maintain an object of this class. Note: this output is to be put inside the <includeonly>-tag on the Form page.

return

object of class mw.html, the representation of the form

FoundationClass:sfGenerateFormEntry()

Generates the "teaser" text shown on the form page when accessing it to create a form (before you type in the name in the input field)

return

object of class mw.html, the representation of the form teaser

FoundationClass:sfGenerateFormInfoTag()

Generates a form's info-tag, together with create and edit title and - if applicable - the query string (in case we have createLinkType formlink).

return

string, a semantic form info tag

FoundationClass:sfGenerateFormLink()

Generates a form input field or a form link that links to the class's form (essentially calls the parser function #forminput or #formlink respectively).

return

string, the input field, that lints to the form

FoundationClass:sfGenerateFormTable(fieldlist)

Generates a table that can be used in a form inside the {{{for template}}} tag. The table contains all fields, that are named in the table parameter fieldlist (which defaults to _CFG.form.fieldOrder) and that are present in _CFG.parameter.. All fields with attribute hidden are placed after the closing /table-tag

fieldlist

table, optional

contains a list of fieldnames, to be processed and added to the return node.

return

object of class mw.html, the representation of the formtable

FoundationClass:sfInitField(fieldname)

Creates a field object of Class SFfield and initializes it per myConfiguration.parameters[fieldname] if entry is present

fieldname

string, mandatory

contains the name of the field to initialize

return

object of Class SFfield, the initialized field object. nil if fieldname is not present in parameter-array

FoundationClass:smwGetProperty2ParameterTranslationTable()

Returns a translation table property-name => parametername, if data store smw is used.

return

table, for every property used in the class the corresponding parameter name

FoundationClass:templateDocumentation()

Generates almost all the output, necessary to have a good documentation page for the corresponding template. Only missing the {{documentation subpage}} call at the top and the includeonly part at the bottom.

return

object of class mw.html, the representation of the template documentation

FoundationClass:usesDataStore(store)

Returs true, if class uses store as datastore. Available stores are 'cargo' and 'smw'

store

string, mandatory

store type to check against

return

bool, whether store store is used as data store

private methods

These private Methods can not be used by child classes!

_amIPlausible(self)

Returs true or false, whether the object is plausible or not (i.e. has no errors or 1+)

self

object, me

return

boolean, whether the object is plausible or not

_debug(self, level, text)

Adds output to the internal debug log.

self

object, me

level

int; mandatory

debug level for the message

text

string; mandatory

debug message text

return

void

_plausibilityTest(self, args)

Checks, if input provided via template is plausible enough, to represent the object (to be stored and displayed). Also fills the list of errors and does some argument preparation.

self

object, me

args

table, mandatory

arguments passed to the template to be checked

return

boolean, whether the object is plausible or not

Properties

static

FoundationClass.globalConfig

table, holds some global configuration (data, that applies to all classes the same way). See Module:Foundationclass/globalconfig for details.

FoundationClass.myCargoUtil

table, instance of Module:CargoUtil

FoundationClass.mySwmUtil

table, instance of Module:SmwUtil

FoundationClass.myTableTools

table, instance of Module:TableTools

FoundationClass.myYesno

table, instance of Module:Yesno

private

Note: all private properties are stored in table _private[self]. _private is a static array that is indexed by self, so the table _private[self] holds all properties for instance self.

categories

table, holds the objects categories

coreData

table, holds the objects data ofter initializing

dbg

object, my instance of Module:Debug/class for debugging purposes

errors

table, a list of errors that occurred

fullpagename

string, name of currentpage including namespace

initialized

boolean, is this object properly initialized

loadedDataFromDataStore

boolean, did this object get its data from the data store

output

object of type mw.html, holds all output to be rendered()

pagename

string, name of current page (or current page's super page) w/o namespace

uid

string, uinique identifier ('NIL' if unset)

warnings

table, a list of warnings that came up

Configuration Data

This class holds gets its control data from the child class. Also, there is some global configuration data in Module:Foundationclass/globalconfig, that applies to all classes.

Dependencies

If you want to use Module:Foundationclass, you also need the following items (and their doc pages!):

• Module:Middleclass
• Module:Foundationclass/config
• Module:Foundationclass/classDoc
• Module:Foundationclass/globalconfig
• Module:CargoUtil and Extension:Cargo if you want to use it as a data store
• Module:SmwUtil and Extension:Semantic MediaWiki if you want to use it as a data store

also

• Module:Arguments
• Module:Collapse
• Module:Debug/class
• Module:Error
• Module:Infobox
• Module:Lua banner
• Module:Message box
• Module:SFfield
• Module:SFfield
• Module:TableTools
• Module:Yesno
• {{code}}
• Extension:TemplateData

and of course Extension:Semantic Forms

Also, have a look at the extended functionality of the Class engine.

Interface messages

To generate the Useful_templates, Foundationclass makes use of the following interface messages:

• MediaWiki:Classengine-content-documentation-methods
• MediaWiki:Classengine-content-documentation-properties
• MediaWiki:Classengine-template-module-page
• MediaWiki:Classengine-template-module-documentation-page
• MediaWiki:Classengine-template-module-class-page
• MediaWiki:Classengine-template-module-class-documentation-page
• MediaWiki:Classengine-template-module-config-documentation-page
• MediaWiki:Classengine-template-template-page
• MediaWiki:Classengine-template-template-documentation-page
• MediaWiki:Classengine-template-form-page
• MediaWiki:Classengine-template-category-page
• MediaWiki:Classengine-template-gardeningcategory-page
• MediaWiki:Classengine-template-property-page

Next in dev queue

1. have foundation class try to detect integer inputs (by td_type or cargo_type) and run a regexp in _plausibilityTest
2. have foundationclass use mw message system for printouts instead of hardcoded text
3. a template or page, that #autogenerates all categories, defined in Module:Foundationclass/globalconfig