Module Definition

Module Definition

A Module Definition describes business objects (and sometimes complex business processes) for your application.

Setting "driver"

string, default module_name

Which driver implements the main logic. If no one is given, then the module name is tried as the driver.

Regularly this will be “objects” or “files”.

Setting "collection"

string, default module_name

Which collection in the key value store is used. If no one is given, then the module name is tried as the collection.

Setting "needs_person"

string, default true

Normally all objects in the system do have a connection to the originally creating user. If this is not wanted or not needed simply set this to false.

Section "parent"

object, optional

Sets the parent object for a new created object in this module.

{
		"parent": {
			"ref": "devices",
			"ref_lookup": "serial_no",
			"self": true
		}
}

Section "default_object"

object, optional

Sets the default data for a new created object in this module.

Within the “default_object” setting all fields could be set to static values. Additionally using the prefix “?” field values out of a current form could be set into the “default_object”.

{
		"default_object": {
			"data": {
				"field1": "This is Field 1",
				"field2": "?field2"
			}
		}
}

Setting "default_mode"

string, enum ("front", “cards”, “list”), default “cards”

The default mode to view the index of this module in. This not only changes the called view template but also the way the retrieved data is given to the appropriate view.

Section "default_access"

object[], optional

Sets the default access for a new created object in this module.

{
		"default_access": [
			{
				"scope" : [
					"*"
				],
				"allow" : [
					{
						"user":"^user_id"
					}
				]
			}
		]
}

See concept “Authorization”.

Section "default_sharing"

string[], optional

Sets the default sharing for a new created object in this module.

{
		"default_sharing": ["site1", "^"]
}

See concept “Sharing”.

Setting "details_action"

string, optional

Normally clicking an object in the index of this module would navigate to details action. With this setting you could change that behavior e.g. having a click in the index directly go into edit action.

Setting "disable_add"

string, default false

Normally the system offers the add action where applicable (and permitted). With this setting this behavior could be disabled.

Setting "disable_edit"

string, default false

Normally the system offers the edit action where applicable (and permitted). With this setting this behavior could be disabled.

Setting "disable_map"

string, default false

Normally the system offers the map action where applicable (and permitted). With this setting this behavior could be disabled.

Setting "disable_tools"

string, default false

Normally the system offers the defined tools where applicable (and permitted). With this setting this behavior could be disabled.

Section "links"

map(string => object), optional

Link Definitions describe which object( collection)s this object( collection) is linked to and how. First the current request's "Action" and "Mode" are used to find the correct Link Definition.

Additionally the "args" section could be used to adapt the found Link Definition.

A Link Definition is an array of strings each describing a link to a different object( collection) and has the following syntax:

{
	"links": {
		"_": [
			"projects",
			"~~organizations;-description;country=CA^city:10"
		]
	}
}

Section "lookup"

string[], optional

A Lookup is used for so called translation tables (e.g. list boxes in forms) where a list of human readable strings in relation to their appropriate ID are given to the user for selection.

The collections “categories” and “entities” are formed as a tree while all others are linear lists.

{
	"lookup": [
		"projects",
		"customer<organizations.title"
	]
}

Section "args"

map(string => object), optional

The arguments are used to inject query string variables or form fields into Links and Queries. First the current request's "Action" and "Mode" are used to find the correct Arguments Definition.

A Arguments Definition is an array of strings each describing an argument and has the following syntax:

Of course all resulting relations between query string or form field relations and Links and Queries are always ment to be “equal” operator based.

{
	"args": [
		"index": [
			"serial_no!",
			".(timestamp)created_at"
		]
	]
}

Section "filter"

object, optional

The Filter Definition object defines special filter and sorting operations to be performed on every data query. This filter is applied directly onto the appropriate query, so working with the data fields require the prefix “data.”.

Using the special operator “||” as a prefix for a field name makes that condition into the “OR” path of that whole Filter Definition. Additionally the following special rules apply.

Remember, the Filter Definition is applied to all data queries within the appropriate Module Definition.

{
	"filter": [
		"^created": 1,
		"^user_id": "^",
		"data.city": "Vancouver",
		"||data.city": {"like": "vancouver"},
		"-": "data.description",
		":": 10
	]
}

Section "actions"

map(string => object), optional

Actions are used to implement additional methods within modules.

The following table shows the properties of an item of the data array in an Action Definition.

Remember that you must pay attention to the used template if injecting additional data having the template use the right names.

{
	"actions": [
		"locations": {
			"method": "index",
			"title": "Locations"
		}
	]
}

See "Action Definition".

Section "tools"

map(string => object), optional

The tools are used for the context based toolbar in a view of an action. First the current request's "Action" and "Mode" are used to find the correct tools.

...

{
	"tools": {
		"index": [
			"orders": {
				"title": "Orders",
				"module": "orders",
				"action": "index"
			}
		}
	]
}

Section "hooks"

map(string => string), optional

Hooks could be used to implement additional functionality into the system e.g. to do things in other backends or services. Hooks are implemented with PHP. First the current request's "Action" and "Mode" are used to find the correct hook.

A found hook always is given is a filename only which then is loaded out of the main config path with added file extension “.php”.

Each hook is run within a special closed function having the following PHP variables available:

...

{
	"hooks": [
		"index": "module_index_hook"
	]
}

...

// module_index_hook.php
// 
//	$context = [
//		'def' => $def,			// The current Module Definition
//		'driver' => $driver,	// The current driver
//		'module' => $module,	// The current Module Name
//		'method' => $method,	// The current Method Name
//		'params' => $params		// The current parameters
//	];
// 
	foreach ($page_items as $temp_i => $page_item) {
		$page_items[$temp_i]['added_column'] = 'This is from a hook.';
	}
//

Section "views"

map(string => object), optional

The views are used to select the appropriate sub template for the current request's "Action" and “Mode”.

Remember that the display of the views depends on the site template used. This system only connects queried or processed data with the appropriate template files.

{
	"views": {
		"_": "general_index",
		"details": "my_module_details"
	}
}

Section "forms"

map(string => object), optional

The arguments are used to inject query string variables or form fields into Links and Queries. First the current request's "Action" and "Mode" are used to find the correct Arguments Definition.

...

{
	"lookup": [
		"projects",
		"customer<organizations.title"
	]
}

Setting "pagination"

integer, optional

The amount of items per page if pagination should be used. No pagination will be used if this value is not given.

Setting "hide_action"

bool, default false

Setting this to true results in not having the current action shown in the bread crumbs.

Setting "rest_mode"

string, enum ("default", “virtual”, “post_process”, “non”), default “default”

With rest_mode the automatic provides REST API for the current module could be changed in its behavior.

Setting "alternative_navigation"

string, optional

Switch to alternate navigation for this action if the template offers one.

Setting "alternative_user_navigation"

string, optional

Switch to alternate navigation for this action if the template offers one and there is an authenticated user.