# HG changeset patch # User jbe # Date 1266594209 -3600 # Node ID f3d3203cd2e44f882378861a7e22eacdf1f496a9 # Parent d76a8857ba629e716ee61194af3e4ed807214542 Documentation for partial loading added NOTE: Previous changeset d76a8857ba62 also modified behaviour of ui.script: Scripts containing "]]>" are now rejected to avoid ambiguities diff -r d76a8857ba62 -r f3d3203cd2e4 framework/env/ui/_partial_load_js.lua --- a/framework/env/ui/_partial_load_js.lua Fri Feb 12 18:40:22 2010 +0100 +++ b/framework/env/ui/_partial_load_js.lua Fri Feb 19 16:43:29 2010 +0100 @@ -1,10 +1,53 @@ --[[-- -ui._partial_load_js{ +ui._partial_load_js( + { + module = module, + view = view, + id = id, + params = params, + target = target + }, + mode = mode } -TODO: documentation +This function is not supposed to be called directly, but only to be used by +ui.link{...} and ui.form{...}. + +It returns a JavaScript which can be used for onclick or onsubmit +attributes in HTML to cause a partial load of contents. Behaviour differs +for the following cases: +a) module, view and target (and optionally id) are given as parameters +b) neither module, view, id, nor target are given as parameters + +In case of a) the function will create a JavaScript which requests the +given view (optionally with the given id and params) as JSON data. + +In case of b) the function will create a JavaScript requesting the view +specified by the next outer ui.partial{...} call as JSON data. Request +parameters specified by previous calls of add_partial_param_names({...}) +are copied from the GET/POST parameters of the current request, while they +can be overwritten using the "params" argument to this function. -NOTE: may return nil +If there is no outer ui.partial{...} call in case b), then this function +returns nil. + +The called URL contains "_webmcp_json_slots[]" as GET parameters to +indicate that slot contents should be returned as a JSON object, instead of +being inserted to a page layout. + +TODO: Currently the slots requested are "default", "trace" and +"system_error". The target for the slot "default" is passed as argument to +this function or to ui.partial{...}. The targets for the slots "trace" and +"system_error" are "trace" and "system_error". This is hardcoded and should +be possible to change in future. The JavaScript will fail, if there are no +HTML elements with id's "trace" and "system_error". + +A mode can be passed as second parameter to this function. When this mode +is "nil" or non existent, the function creates JavaScript code to be used +as onclick event for normal (GET) links. When mode is set to "form_normal" +or "form_action", the returned code can be used as onsubmit event of web +forms. "form_normal" is used when the form calls a view, "form_action" is +used when the form calls an action. --]]-- @@ -33,6 +76,7 @@ end if ui._partial_state then + -- TODO: do this only if args.view and args.target are unset!? if ui._partial_state.params then for key, value in pairs(ui._partial_state.params) do params[key] = value diff -r d76a8857ba62 -r f3d3203cd2e4 framework/env/ui/add_partial_param_names.lua --- a/framework/env/ui/add_partial_param_names.lua Fri Feb 12 18:40:22 2010 +0100 +++ b/framework/env/ui/add_partial_param_names.lua Fri Feb 19 16:43:29 2010 +0100 @@ -3,7 +3,9 @@ name_list ) -TODO: documentation +This function adds names of GET/POST parameters to the list of parameters +which are to be copied when calling ui._partial_load_js{...} or +ui.link{..., partial = {...}} or ui.form{..., partial = {...}}. --]]-- diff -r d76a8857ba62 -r f3d3203cd2e4 framework/env/ui/enable_partial_loading.lua --- a/framework/env/ui/enable_partial_loading.lua Fri Feb 12 18:40:22 2010 +0100 +++ b/framework/env/ui/enable_partial_loading.lua Fri Feb 19 16:43:29 2010 +0100 @@ -1,7 +1,15 @@ --[[-- ui.enable_partial_loading() -TODO: documentation +This function tells subsequent calls of ui.link{...} and ui.form{...} that +partial loading should be enabled when requested by passing "partial" +arguments to ui.link or ui.form. + +NOTE: To use partial loading, the slots being requested need to be +white-listed by calling request.set_allowed_json_request_slots({...}) +in the application configuration file. TODO: By now, at least the slot +names "default", "trace" and "system_error" need to be white-listed, as +these slots are currently hardwired in ui._partial_load_js(...). --]]-- diff -r d76a8857ba62 -r f3d3203cd2e4 framework/env/ui/form.lua --- a/framework/env/ui/form.lua Fri Feb 12 18:40:22 2010 +0100 +++ b/framework/env/ui/form.lua Fri Feb 19 16:43:29 2010 +0100 @@ -17,7 +17,14 @@ ok = { ... }, -- routing when "ok" is returned by the called action error = { ... }, -- routing when "error" is returned by the called action ... = { ... } -- routing when "..." is returned by the called action - } + }, + partial = { -- parameters for partial loading, see below + module = module, + view = view, + id = id, + params = params, + target = target + }, content = function() ... -- code creating the contents of the form end @@ -25,6 +32,10 @@ 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. +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 +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 +further documentation. + --]]-- local function prepare_routing_params(params, routing, default_module) diff -r d76a8857ba62 -r f3d3203cd2e4 framework/env/ui/is_partial_loading_enabled.lua --- a/framework/env/ui/is_partial_loading_enabled.lua Fri Feb 12 18:40:22 2010 +0100 +++ b/framework/env/ui/is_partial_loading_enabled.lua Fri Feb 19 16:43:29 2010 +0100 @@ -2,7 +2,8 @@ result = ui.is_partial_loading_enabled() -TODO: documentation +This function returns true, if partial loading has been enabled by calling +ui.enable_partial_loading(). --]]-- diff -r d76a8857ba62 -r f3d3203cd2e4 framework/env/ui/link.lua --- a/framework/env/ui/link.lua Fri Feb 12 18:40:22 2010 +0100 +++ b/framework/env/ui/link.lua Fri Feb 19 16:43:29 2010 +0100 @@ -10,16 +10,22 @@ routing = routing, -- optional routing information for action links, as described for ui.form{...} text = text, -- link text content = content, -- link content (overrides link text, except for submit buttons for action calls without JavaScript) - partial = { -- TODO: documentation + partial = { -- parameters for partial loading, see below module = module, view = view, id = id, - params = params + params = params, + target = target } } 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). +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 +used to create an onclick event (onsubmit event for action links). The +"partial" setting table is passed to ui._partial_load_js as first argument. +See ui._partial_load_js(...) for further documentation. + --]]-- function ui.link(args) diff -r d76a8857ba62 -r f3d3203cd2e4 framework/env/ui/partial.lua --- a/framework/env/ui/partial.lua Fri Feb 12 18:40:22 2010 +0100 +++ b/framework/env/ui/partial.lua Fri Feb 19 16:43:29 2010 +0100 @@ -1,16 +1,22 @@ --[[-- ui.partial{ - module = - view = - id = - params = - target = + module = module, -- module to be used to reload inner contents + view = view, -- view to be used to reload inner contents + id = id, -- id to be used to reload inner contents + params = params, -- params to be used to reload inner contents + target = target, -- id of HTML element containing contents to be replaced content = function() - ... -- + ... end } -TODO: documentation +Calling this function declares that the inner contents can be requested +directly via the given module, view, id and params. The parameter "target" +specifies the id of the HTML element, which should be replaced when +reloading partially. + +The function has an effect on inner calls of ui.link{..., partial = {...}} +and ui.form{..., partial = {...}}. --]]--