imported>Oetterer: /* Dependencies */

2016-01-15T19:26:44Z

Dependencies

Neue Seite

{{documentation subpage}}
{{module rating|protected}}


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()|getCoreData()]] and its uid with [[#getUid()|getUid()]].

=== How-To ===
This is, what you have to do (see [[#Useful templates|Useful templates]] for content of the corresponding pages):
# create your base module ''Module:Name''
# create your class module ''Module:Name/class''. For this, copy lua sample code below this list and apply the following changes:
## change all occurences of ''className'' into your class name
## change the highlighted lines and replace 'Name' with the Name of your module
## implement the abstract methods:
### myAgumentProcessing(coreData)
### myDataAdjustments(data)
### myPlausibilityTest(args)
### myStashAdjustments(stash)
### static:mySfDynamicFieldAttribute(fieldname, attribute, value)
## for the usual output generation, implement (shells given in sample code)
### addInfobox()
### addPageBody()
# create and fill your configuration ''Module:Name/config''
# create your template ''Template:Name''
# create your form ''Form:Name''
# if applicable, create your category page ''Category:Name''
# fill in documentation:
## of your base module (place one invoke below the first comment and before the includeonly)
## 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|Useful templates]]
## of your class module's configuration (just copy content)
## of your template (one invoke below the first comment and before the includeonly)

=== Useful templates ===
{{Collapse top|title=base module:}}
{{code|lang=lua|line=1|code=
{{#invoke:Foundationclass/classDoc|base}}
}}
{{Collapse bottom}}
{{Collapse top|title=base module's documentation page:}}
{{pre2|1=
{{#invoke:Foundationclass/classDoc|baseDoc}}
}}
{{Collapse bottom}}
{{Collapse top|title=class module:}}
{{code|lang=lua|line=1|start=1|highlight=7,9|code=
{{#invoke:Foundationclass/classDoc|class}}
}}
{{Collapse bottom}}
{{Collapse top|title=class module's documentation page:}}
{{pre2|1=
{{#invoke:Foundationclass/classDoc|classDoc}}
}}
{{Collapse bottom}}
{{Collapse top|title=class configuration (sample file):}}
{{code|lang=lua|code=
{{Module:Foundationclass/config}}
}}
{{Collapse bottom}}
{{Collapse top|title=configuration documentation page:}}
{{pre2|1=
{{#invoke:Foundationclass/classDoc|configDoc}}
}}
{{Collapse bottom}}
{{Collapse top|title=template:}}
{{pre2|1=
{{#invoke:Foundationclass/classDoc|template}}
}}
{{Collapse bottom}}
{{Collapse top|title=template documentation page:}}
{{pre2|1=
{{#invoke:Foundationclass/classDoc|templateDoc}}
}}
{{Collapse bottom}}
{{Collapse top|title=form:}}
{{ombox|type=content|text='''Note:''' If you have a display error on your form in a way that your fieldset and your label (the blue box) does not include your form but instead is displayed above it, add a line break before and after the #invoke-statement, having it stand alone in line.}}
{{pre2|1=
{{#invoke:Foundationclass/classDoc|form}}
}}
{{Collapse bottom}}
{{Collapse top|title=category:}}
{{pre2|1=
{{#invoke:Foundationclass/classDoc|category}}
}}
{{Collapse bottom}}
{{Collapse top|title=gardening category:}}
{{pre2|1=
{{#invoke:Foundationclass/classDoc|gardeningCategory}}
}}
{{Collapse bottom}}

=== private, public, class or instance ===
{|
|+ Zugriffsmatrix
|-
! -
! public
! private
|-
! instance
| <syntaxhighlight lang="lua">
function MyClass:publicMethod()
MyClass.publicProperty
</syntaxhighlight>
| <syntaxhighlight lang="lua">
local _privateMethod = function (self, var)
_private[self]._privateProperty
</syntaxhighlight>
|-
! class
| <syntaxhighlight lang="lua">
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()
</syntaxhighlight>
| <syntaxhighlight lang="lua">
local _privateMethod = function (self, var)
local _privateProperty
</syntaxhighlight>
|}

==== private ====
===== property =====
you can declare a property private in one of two ways:
# anywhere, preferably before your constructor, declare a <code>local var</code> 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
# 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: {{code snippet|lang=lua|code=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:
{{code|lang=lua|code=
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:
{{code|lang=lua|code=
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: <code>class.static.myProperty = 'Hello World'</code>. 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: {{code snippet|lang=lua|code=function Class.static:staticMethod()}} when definig the method. On accessig this method, you should use the dot-notation: {{code snippet|lang=lua|code=function Class.staticMethod(self)}}

NOTE: Other than public methods, they can only be called by the class, but not by an instance:
{{code|lang=lua|code=
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 ==
{{MediaWiki:Classengine-content-documentation-methods}}

=== 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+)
{{small|
;self
:object, me
;return
:boolean, whether the object is plausible or not
}}

==== _debug(self, level, text) ====
Adds output to the internal debug log.
{{small|
;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 [[#private|list of errors]] and does some argument preparation.
{{small|
;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 ===
{{MediaWiki:Classengine-content-documentation-properties}}
=== 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 [https://www.mediawiki.org/wiki/Extension:Cargo Extension:Cargo] if you want to use it as a data store
* [[Module:SmwUtil]] and [https://www.mediawiki.org/wiki/Extension:Semantic_MediaWiki 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]]
* {{tl|code}}
* [https://www.mediawiki.org/wiki/Extension:TemplateData Extension:TemplateData]
and of course [https://www.mediawiki.org/wiki/Extension:Semantic_Forms Extension:Semantic Forms]

Also, have a look at the extended functionality of the [[:Category:Class engine|Class engine]].

=== Interface messages ===
To generate the [[#Useful_templates|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 ==
# have foundation class try to detect integer inputs (by td_type or cargo_type) and run a regexp in _plausibilityTest
# have foundationclass use mw message system for printouts instead of hardcoded text
# a template or page, that #autogenerates all categories, defined in [[Module:Foundationclass/globalconfig]]

{{#invoke:Foundationclass/classDoc|categorize}}<includeonly>{{#ifeq:{{SUBPAGENAME}}|sandbox||


[[Category:Lua metamodules]]
}}</includeonly>

Modul:Foundationclass/doc - Versionsgeschichte

imported>Oetterer: /* Dependencies */