Modul:SFfield/class/doc

This is a Class Module. It implements a class in Lua using Module:Middleclass. This class provides methods for defining and creating Semantic Forms field-tags.

Usage

local classSFfield = require('Module:SFfield/class')
local field = classSFfield:new('name')
classSFfield:setDefaultSize(80)
field:set('input type', 'tokens')
field:set('list')
field:set('mandatory', true)
field:set('property', 'goes by name')
local output = field:render()

This class provides meththods for creating field tags to use in Semantic Forms. It is fast, easy to use and does some minor plausibility checks:

• it only allows existing attributes to be set
• it only allows existing "input type"s to be set

Concerniny "existing": The module knows all input types from Semantic Forms and Semantic Forms Inputs. All valid entries are defined in Configuration Data

Besides some debugging, the class does not print any error reports or development output. See Module:Debug/class for more information on how to access debug output.

There is are some static properties to default certain values when not set individually:

• size for "tokens", "combobox", "text", ... fields
• autogrow for "textarea" and "textarea with autocomplete"
• cols for "textarea" and "textarea with autocomplete"
• editor for "textarea" and "textarea with autocomplete"
• rows for "textarea" and "textarea with autocomplete"

They are initialized in the class but can be overwritten by static methods.

Besides simple field-tags there is also a method with which you can have your tags enclosed in the typical tr-th-td structure to easily create a form table. You can also add a tooltip. If mandatory was set, it also prints a small asterix next to the label.

local node = field:createTr('Name', 'This field holds the full name, the person is known for.')

Constructor

new(fieldname)

Creates a new Object for class Name.

fieldname

string, mandatory

holds the name of the field; in SF-terms: this transforms to the parameter name of the referenced template

return

object, of class SFfield

Methods

Public methods

__tostring()

Returns a string representation of the field by calling render().

return

string, representation of itself

createTr(label, tooltip)

Uncloses the rendered field in a tr-th-td structure that can directly be used in an html formtable. When mandatory is set in the field, it adds an asterix after the label. A tooltip can also be provided.

label

string, mandatory

what var is for

tooltip

string, optional

explanatory text that helps the user fill this field

return

object of class mw.html, one table row (tr) containing an th with the labal (and tooltip) and a tr with the rendered field.

get(attribute)

Returns the value for the attribute.

attribute

string, mandatory

the name of the attribute, you wish to get

return

vaiable, the value for the attribute

render()

Renders the object and creates a semantic forms field already htmlentities-encoded (so it can be used directly in the form)

return

string, rendered and encoded field-tag

set(attribute, value)

Sets an attribute for the field. Checks attribute for validity before setting it. In case of attribute input type checks value for validity, too. When setting simple attributes like list or mandatory, omitting value is interpreted as adding the attribute. If you at anytime wish to remove such an attribute, you have to set value to false.

attribute

string, mandatory

the name of the attribute, you wish to set

value

(string

static methods

SFfield:getShowOnSelectIdPrefix()

Returns the static property used as prefix in the html-id attribute that serves as identifier for the show on select mechanism. When using the method createTr, you probably have no need for this.

return

string, prefix for the value of the id attribute

SFfield:setDefaultSize(val)

Sets the default size for text-like fields (tokens, combobox, text, ...). The default only applies, if this attribute is not set individually in a textarea field.

val

integer, mandatory

default size in characters for input fields

return

boolean, whether setting was successful or not

SFfield:setDefaultTextAreaAutogrow(val)

Sets the default autogrow-behaviour of textarea-type fields. The default only applies, if this attribute is not set individually in a textarea field.

val

boolean, mandatory

disables or enables default value for autogrow in textarea fields.

return

boolean, whether setting was successful or not

SFfield:setDefaultTextAreaCols(val)

Sets the default for number of columns for textarea-type fields. The default only applies, if this attribute is not set individually in a textarea field.

val

integer, mandatory

default for number of columns for the textarea fields.

return

boolean, whether setting was successful or not

SFfield:setDefaultTextAreaEditor(val)

Sets the default editor of textarea-type fields. The default only applies, if this attribute is not set individually in a textarea field.

val

string

SFfield:setDefaultTextAreaRows(val)

Sets the default for number of rows for textarea-type fields. The default only applies, if this attribute is not set individually in a textarea field.

val

integer, mandatory

default for number of rows for the textarea fields.

return

boolean, whether setting was successful or not

SFfield:setShowOnSelectIdPrefix(val)

Sets the default prefix for the html id-attribute used in the show on select complex.

val

string, mandatory

the static property will be set to this value

return

boolean, whether setting was successful or not

private methods

_processAttributes(self)

Converts the private property attributes (which holds all attributes for this field) from an array {attribute = value, ...} table to a sequence {'attriubte=value', ..} table. Also:

• adds the attribute 'input type' if missing to a default, depending on setting of attribute 'list'
• sets defaults (if applicable) for
  • size
  • autogrow
  • cols
  • editor
  • rows
• does the 'show on select' table-conversion if necessary

self

object, me

var

type(string

Properties

static

_CFG

table, holds configuration data found in Module:Name/config

WARNING: This is a read only table and besides functions pairs() and ipairs() nothing else will work on it, especially not the functions of the table library!

• global, table, global behaviour settings
• validAttributes, table, a sequence of all valid attributes
• validInputTypes, table, a sequence of all valid values for attribute "input type"

_TT

table, instance of Module:TableTools

_defaultListInputType

string, default value for attribute "input type" if unset. applies if "list" is set

_defaultSingleInputType

string, default value for attribute "input type" if unset. applies if "list" is not set

_defaultSize

integer, default size for most input types if not set

_defaultTextAreaAttributes

table, holds some default attribte values for textarea fields if unset

_mandatoryMarker

string, createTr uses this marker to depict mandatory fields

_showOnSelectIdPrefix

string, prefix string for html id-attributes for the show on select complex (e.g.: '")

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.

attributes

table, holds "my" attributes

dbg

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

name

string, name of this field

Configuration Data

This class holds it control data in Module:SFfield/class/config.