webmcp
changeset 12:f3d3203cd2e4 v1.0.7
Documentation for partial loading added
NOTE: Previous changeset d76a8857ba62 also modified behaviour of ui.script: Scripts containing "]]>" are now rejected to avoid ambiguities
NOTE: Previous changeset d76a8857ba62 also modified behaviour of ui.script: Scripts containing "]]>" are now rejected to avoid ambiguities
author | jbe |
---|---|
date | Fri Feb 19 16:43:29 2010 +0100 (2010-02-19) |
parents | d76a8857ba62 |
children | 39652c779afe |
files | framework/env/ui/_partial_load_js.lua framework/env/ui/add_partial_param_names.lua framework/env/ui/enable_partial_loading.lua framework/env/ui/form.lua framework/env/ui/is_partial_loading_enabled.lua framework/env/ui/link.lua framework/env/ui/partial.lua |
line diff
1.1 --- a/framework/env/ui/_partial_load_js.lua Fri Feb 12 18:40:22 2010 +0100 1.2 +++ b/framework/env/ui/_partial_load_js.lua Fri Feb 19 16:43:29 2010 +0100 1.3 @@ -1,10 +1,53 @@ 1.4 --[[-- 1.5 -ui._partial_load_js{ 1.6 +ui._partial_load_js( 1.7 + { 1.8 + module = module, 1.9 + view = view, 1.10 + id = id, 1.11 + params = params, 1.12 + target = target 1.13 + }, 1.14 + mode = mode 1.15 } 1.16 1.17 -TODO: documentation 1.18 +This function is not supposed to be called directly, but only to be used by 1.19 +ui.link{...} and ui.form{...}. 1.20 + 1.21 +It returns a JavaScript which can be used for onclick or onsubmit 1.22 +attributes in HTML to cause a partial load of contents. Behaviour differs 1.23 +for the following cases: 1.24 +a) module, view and target (and optionally id) are given as parameters 1.25 +b) neither module, view, id, nor target are given as parameters 1.26 + 1.27 +In case of a) the function will create a JavaScript which requests the 1.28 +given view (optionally with the given id and params) as JSON data. 1.29 + 1.30 +In case of b) the function will create a JavaScript requesting the view 1.31 +specified by the next outer ui.partial{...} call as JSON data. Request 1.32 +parameters specified by previous calls of add_partial_param_names({...}) 1.33 +are copied from the GET/POST parameters of the current request, while they 1.34 +can be overwritten using the "params" argument to this function. 1.35 1.36 -NOTE: may return nil 1.37 +If there is no outer ui.partial{...} call in case b), then this function 1.38 +returns nil. 1.39 + 1.40 +The called URL contains "_webmcp_json_slots[]" as GET parameters to 1.41 +indicate that slot contents should be returned as a JSON object, instead of 1.42 +being inserted to a page layout. 1.43 + 1.44 +TODO: Currently the slots requested are "default", "trace" and 1.45 +"system_error". The target for the slot "default" is passed as argument to 1.46 +this function or to ui.partial{...}. The targets for the slots "trace" and 1.47 +"system_error" are "trace" and "system_error". This is hardcoded and should 1.48 +be possible to change in future. The JavaScript will fail, if there are no 1.49 +HTML elements with id's "trace" and "system_error". 1.50 + 1.51 +A mode can be passed as second parameter to this function. When this mode 1.52 +is "nil" or non existent, the function creates JavaScript code to be used 1.53 +as onclick event for normal (GET) links. When mode is set to "form_normal" 1.54 +or "form_action", the returned code can be used as onsubmit event of web 1.55 +forms. "form_normal" is used when the form calls a view, "form_action" is 1.56 +used when the form calls an action. 1.57 1.58 --]]-- 1.59 1.60 @@ -33,6 +76,7 @@ 1.61 end 1.62 1.63 if ui._partial_state then 1.64 + -- TODO: do this only if args.view and args.target are unset!? 1.65 if ui._partial_state.params then 1.66 for key, value in pairs(ui._partial_state.params) do 1.67 params[key] = value
2.1 --- a/framework/env/ui/add_partial_param_names.lua Fri Feb 12 18:40:22 2010 +0100 2.2 +++ b/framework/env/ui/add_partial_param_names.lua Fri Feb 19 16:43:29 2010 +0100 2.3 @@ -3,7 +3,9 @@ 2.4 name_list 2.5 ) 2.6 2.7 -TODO: documentation 2.8 +This function adds names of GET/POST parameters to the list of parameters 2.9 +which are to be copied when calling ui._partial_load_js{...} or 2.10 +ui.link{..., partial = {...}} or ui.form{..., partial = {...}}. 2.11 2.12 --]]-- 2.13
3.1 --- a/framework/env/ui/enable_partial_loading.lua Fri Feb 12 18:40:22 2010 +0100 3.2 +++ b/framework/env/ui/enable_partial_loading.lua Fri Feb 19 16:43:29 2010 +0100 3.3 @@ -1,7 +1,15 @@ 3.4 --[[-- 3.5 ui.enable_partial_loading() 3.6 3.7 -TODO: documentation 3.8 +This function tells subsequent calls of ui.link{...} and ui.form{...} that 3.9 +partial loading should be enabled when requested by passing "partial" 3.10 +arguments to ui.link or ui.form. 3.11 + 3.12 +NOTE: To use partial loading, the slots being requested need to be 3.13 +white-listed by calling request.set_allowed_json_request_slots({...}) 3.14 +in the application configuration file. TODO: By now, at least the slot 3.15 +names "default", "trace" and "system_error" need to be white-listed, as 3.16 +these slots are currently hardwired in ui._partial_load_js(...). 3.17 3.18 --]]-- 3.19
4.1 --- a/framework/env/ui/form.lua Fri Feb 12 18:40:22 2010 +0100 4.2 +++ b/framework/env/ui/form.lua Fri Feb 19 16:43:29 2010 +0100 4.3 @@ -17,7 +17,14 @@ 4.4 ok = { ... }, -- routing when "ok" is returned by the called action 4.5 error = { ... }, -- routing when "error" is returned by the called action 4.6 ... = { ... } -- routing when "..." is returned by the called action 4.7 - } 4.8 + }, 4.9 + partial = { -- parameters for partial loading, see below 4.10 + module = module, 4.11 + view = view, 4.12 + id = id, 4.13 + params = params, 4.14 + target = target 4.15 + }, 4.16 content = function() 4.17 ... -- code creating the contents of the form 4.18 end 4.19 @@ -25,6 +32,10 @@ 4.20 4.21 This functions creates a web form, which encloses the content created by the given 'content' function. When a 'record' is given, ui.field.* helper functions will be able to automatically determine field values by using the given record. If 'read_only' is set to true, then a call of ui.submit{...} will be ignored, and ui.field.* helper functions will behave differently. 4.22 4.23 +When passing a table as "partial" argument, AND if partial loading has been enabled by calling ui.enable_partial_loading(), then ui._partial_load_js is 4.24 +used to create an onsubmit event. The "partial" setting table is passed to ui._partial_load_js as first argument. See ui._partial_load_js(...) for 4.25 +further documentation. 4.26 + 4.27 --]]-- 4.28 4.29 local function prepare_routing_params(params, routing, default_module)
5.1 --- a/framework/env/ui/is_partial_loading_enabled.lua Fri Feb 12 18:40:22 2010 +0100 5.2 +++ b/framework/env/ui/is_partial_loading_enabled.lua Fri Feb 19 16:43:29 2010 +0100 5.3 @@ -2,7 +2,8 @@ 5.4 result = 5.5 ui.is_partial_loading_enabled() 5.6 5.7 -TODO: documentation 5.8 +This function returns true, if partial loading has been enabled by calling 5.9 +ui.enable_partial_loading(). 5.10 5.11 --]]-- 5.12
6.1 --- a/framework/env/ui/link.lua Fri Feb 12 18:40:22 2010 +0100 6.2 +++ b/framework/env/ui/link.lua Fri Feb 19 16:43:29 2010 +0100 6.3 @@ -10,16 +10,22 @@ 6.4 routing = routing, -- optional routing information for action links, as described for ui.form{...} 6.5 text = text, -- link text 6.6 content = content, -- link content (overrides link text, except for submit buttons for action calls without JavaScript) 6.7 - partial = { -- TODO: documentation 6.8 + partial = { -- parameters for partial loading, see below 6.9 module = module, 6.10 view = view, 6.11 id = id, 6.12 - params = params 6.13 + params = params, 6.14 + target = target 6.15 } 6.16 } 6.17 6.18 This function inserts a link into the active slot. It may be either an internal application link ('module' given and 'view' or 'action' given), or a link to an external web page ('external' given), or a link to a file in the static file directory of the application ('static' given). 6.19 6.20 +When passing a table as "partial" argument, AND if partial loading has been enabled by calling ui.enable_partial_loading(), then ui._partial_load_js is 6.21 +used to create an onclick event (onsubmit event for action links). The 6.22 +"partial" setting table is passed to ui._partial_load_js as first argument. 6.23 +See ui._partial_load_js(...) for further documentation. 6.24 + 6.25 --]]-- 6.26 6.27 function ui.link(args)
7.1 --- a/framework/env/ui/partial.lua Fri Feb 12 18:40:22 2010 +0100 7.2 +++ b/framework/env/ui/partial.lua Fri Feb 19 16:43:29 2010 +0100 7.3 @@ -1,16 +1,22 @@ 7.4 --[[-- 7.5 ui.partial{ 7.6 - module = 7.7 - view = 7.8 - id = 7.9 - params = 7.10 - target = 7.11 + module = module, -- module to be used to reload inner contents 7.12 + view = view, -- view to be used to reload inner contents 7.13 + id = id, -- id to be used to reload inner contents 7.14 + params = params, -- params to be used to reload inner contents 7.15 + target = target, -- id of HTML element containing contents to be replaced 7.16 content = function() 7.17 - ... -- 7.18 + ... 7.19 end 7.20 } 7.21 7.22 -TODO: documentation 7.23 +Calling this function declares that the inner contents can be requested 7.24 +directly via the given module, view, id and params. The parameter "target" 7.25 +specifies the id of the HTML element, which should be replaced when 7.26 +reloading partially. 7.27 + 7.28 +The function has an effect on inner calls of ui.link{..., partial = {...}} 7.29 +and ui.form{..., partial = {...}}. 7.30 7.31 --]]-- 7.32