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
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  

Impressum / About Us