Latest revision as of 12:30, 7 March 2016

While the mvc.lua code provides a generic framework for any lua "mvc"-based application, "acf" is the component that makes the mvc.lua framework into a web configuration Application. Some ideas and rationales for application-wide settings are discussed here.

Use of cfe

A cfe (Configuration Framework Entity) is a way to pass data between a model, controller and view in a common way. There are many ways to do this (e.g. closures, AKClass); use of cfe is an arbitrary decision just to keep development moving forward.

A cfe is a table with some fields guaranteed to exist. It is also a way to abstract user-modifiable data from view-centric HTML input types. ACF isn't necessarily web-only. With a different controller and views, it could be cli (or gui?!). The acf-cli application is an example of this.

Fields in all cfes

cfe's are constructed from a function in mvc.lua that returns an anonymous table with the following fields

Field	Default	Description
value	""	The value of the cfe (e.g. the IP address, hostname, password, etc.)
type	"text"	The type of entity (see below)
label	""	User-readable label for the value

The reason for having these fields pre-defined is to allow models, controllers and views to use the indexes without having to first check if they exist. For example the entity will always have a value and type.

cfe's can have other fields. Some common fields that may, or may not, be present:

Field	Description
errtxt	Text explaining why validation failed
option	A list of options for this value
descr	User-readable description for the value
seq	Numeric sequence suggesting display order for cfe's in a group or form
default	Default value (can be displayed to user)
readonly	If present, indicates that the information is to be displayed, but not editable, typically used in forms

To set fields or overwrite field defaults, specify a table in the argument list to the cfe constructor:

mycfe = cfe({label="User", value="asdf", errtxt="Invalid User"})

is equivalent to

mycfe = {label="User", value="asdf", type="text", errtxt="Invalid User"}

cfe types

The type field of a cfe can be one of the following:

type	Description	Modifiers
text	a text field, typically one line of text
longtext	a multi-line text field, like a textarea
select	a select list	value is the currently selected item option is an array of select options
multi	a multi-select list	value is an array of selected items option is an array of select options
list	a list	value is an array of strings
boolean	true or false
raw	raw binary data
form	a set of cfe's that make up a form	value is a table of cfe's that make up a form (the table should be name-indexed) option is the command name to save changes (button name for HTML) descr or errtxt may contain the result of a save attempt
group	a set of cfe's that make up an anonymous group	value is a table of grouped cfe's (can be used to pass several items to a view) (the table should be name-indexed)
structure	a Lua table with no further type info
password	a password which should not be readable by a user
hidden	a hidden field typically containing information used by ACF and not visible to a user

The Model defines the object set

The model is responsible for writing and reading from the running system. The model typically does not need to know which part of a specific acf module it is running under. It is not mandatory that the model be lua "oop" as the rest of the system is. (the model may not have any need to know "self")

Since the model can choose how much or how little of the system to expose, the basic data set should be defined in the model.

@@ Line 1: / Line 1: @@
-While the mvc.lua code provides a generic framework for any lua "mvc"-based appliction, "acf" is the component that makes the mvc.lua framework into a configuration Application.  Some ideas and rationales for application-wide settings are discussed here.
+While the mvc.lua code provides a generic framework for any lua "mvc"-based application, "acf" is the component that makes the mvc.lua framework into a web configuration Application. Some ideas and rationales for application-wide settings are discussed here.
 = Use of ''cfe'' =
-A ''cfe'' ('''C'''onfiguration '''F'''ramework '''E'''ntity) is a way to pass data between a model,controller and view in a common way.  There are many ways to do this (e.g. closures, AKClass); use of cfe is an arbitrary decision just to keep development moving forward.
+A ''cfe'' ('''C'''onfiguration '''F'''ramework '''E'''ntity) is a way to pass data between a model, controller and view in a common way. There are many ways to do this (e.g. closures, AKClass); use of cfe is an arbitrary decision just to keep development moving forward.
-A cfe is a table with some fields guaranteed to exist.  It is also a way to abstract user-modifiable data from view-centric html input types.  ACF isn't necessarily web-only.  With a different controller and views, it could be cli (or gui?!)
+A cfe is a table with some fields guaranteed to exist. It is also a way to abstract user-modifiable data from view-centric HTML input types. ACF isn't necessarily web-only. With a different controller and views, it could be cli (or gui?!). The acf-cli application is an example of this.
 == Fields in all cfes  ==
-cfe's are constructed from a function in <tt>acf-controller.lua</tt> that returns an anonymous table with the following fields
+cfe's are constructed from a function in <tt>mvc.lua</tt> that returns an anonymous table with the following fields
 {| border=1
   ! Field !! Default !! Description
   |-
-  |value || empty ||The value of the cfe (e.g. the ip address, hostname, password, etc.)
+  |value || "" || The value of the cfe (e.g. the IP address, hostname, password, etc.)
   |-
-  |type || text || The type of entity (see below)
+  |type || "text" || The type of entity (see below)
   |-
-  |option ||empty ||common modifiers for this type of cfe
+  |label || ""  || User-readable label for the value
- |-
- |errtxt || empty ||text explaining why validation failed
 |}
-The reason for having these fields pre-defined is to allow models,controllers and views to use the indexes without having to first check if they exist.  For example the entity will always have a value and type.
+The reason for having these fields pre-defined is to allow models, controllers and views to use the indexes without having to first check if they exist. For example the entity will always have a value and type.
-cfe's can have other fields, or can have their defaults overwritten by specifying a table in the argument list to the cfe constructor:
+cfe's can have other fields.  Some common fields that may, or may not, be present:
-:mycfe = cfe({label="Foo", type="boolean", value=true})
+{| border=1
+ ! Field !! Description
+ |-
+ |errtxt || Text explaining why validation failed
+ |-
+ |option || A list of options for this value
+ |-
+ |descr || User-readable description for the value
+ |-
+ |seq || Numeric sequence suggesting display order for cfe's in a group or form
+ |-
+ |default || Default value (can be displayed to user)
+ |-
+ |readonly || If present, indicates that the information is to be displayed, but not editable, typically used in forms
+|}
+To set fields or overwrite field defaults, specify a table in the argument list to the cfe constructor:
+:mycfe = cfe({label="User", value="asdf", errtxt="Invalid User"})
 is equivalent to
-:mycfe = {value=true, type="boolean", option="", errtxt="", label="Foo"}
+:mycfe = {label="User", value="asdf", type="text", errtxt="Invalid User"}
 == cfe types ==
@@ Line 35: / Line 51: @@
 The ''type'' field of a cfe can be one of the following:
-{|
+{| border=1
- |-
   ! type !! Description !! Modifiers
   |-
@@ Line 43: / Line 58: @@
   | longtext || a multi-line text field, like a textarea  ||
   |-
-  | select || a select list || ''value'' is the currently selected item <br>''option'' is a table of select options
+  | select || a select list || ''value'' is the currently selected item <br>''option'' is an array of select options
   |-
-  | boolean || a checkbox ||
+  | multi || a multi-select list || ''value'' is an array of selected items <br>''option'' is an array of select options
   |-
-  | action || a submit button or link to an action || ''option'' is a table with keys of "prefix", "controller", "action", etc
+  | list || a list || ''value'' is an array of strings
   |-
-  | message || a text message || typically used for something the view should not allow the user to change.
+  | boolean || true or false ||
   |-
   | raw || raw binary data ||
   |-
-  | closure || a function ||
+  | form || a set of cfe's that make up a form || ''value'' is a table of cfe's that make up a form (the table should be name-indexed)<br>''option'' is the command name to save changes (button name for HTML)<br>''descr'' or ''errtxt'' may contain the result of a save attempt
   |-
-  | form || a set of cfe's that make up a form || ''value'' is a table of cfes<br>''option'' is a table with keys of "prefix", "controller", "action", etc.
+  |  group || a set of cfe's that make up an anonymous group || ''value'' is a table of grouped cfe's (can be used to pass several items to a view) (the table should be name-indexed)
   |-
-  |  group || a set of cfe's that make up an anonymous group || ''value'' is a table of grouped cfes (can be used when several cfe's share the same name)
+  |  structure || a Lua table with no further type info ||
+ |-
+ |  password || a password which should not be readable by a user ||
+ |-
+ |  hidden || a hidden field typically containing information used by ACF and not visible to a user ||
   |}
-= Use of CRUD =
-CRUD stands for Create Read Update Delete.  Where possible, ACF models/controllers should follow this pattern.  To help reuse of code, the functions in models and controllers should have one of Cread Read Update or Delete in their names (create_interface_by_name, update_hostname, delete_package, read_timezone, etc.)
-= Use of cmd =
-The use of a standard "do this" cfe in all acf controllers may also allow more reuse.  It is suggested to use "cmd" as the ''name'' of this cfe, with the value being the command to perform.
 = The Model defines the object set =
-The model is responsible for writing and reading from the running system.  The model also does not need to know which part of a specific acf module it is running under.  It is not mandatory that the model be lua "oop" as the rest of the system is.  (the model may not have any need to know "self")
+The model is responsible for writing and reading from the running system. The model typically does not need to know which part of a specific acf module it is running under. It is not mandatory that the model be lua "oop" as the rest of the system is. (the model may not have any need to know "self")
+Since the model can choose how much or how little of the system to expose, the basic data set should be defined in the model.
-Since the model can choose how much or how little of the system to expose, the basic data set should be defined in the model (perhaps as a constructor function)
+[[Category:ACF]]