Commits

jbe  committed f3d3203

Documentation for partial loading added

NOTE: Previous changeset d76a8857ba62 also modified behaviour of ui.script: Scripts containing "]]>" are now rejected to avoid ambiguities

  • Participants
  • Parent commits d76a885
  • Tags v1.0.7

Comments (0)

Files changed (7)

File framework/env/ui/_partial_load_js.lua

 --[[--
-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{...}.
 
-NOTE: may return nil
+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.
+
+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.
 
 --]]--
 
   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

File framework/env/ui/add_partial_param_names.lua

   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 = {...}}.
 
 --]]--
 

File framework/env/ui/enable_partial_loading.lua

 --[[--
 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(...).
 
 --]]--
 

File framework/env/ui/form.lua

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

File framework/env/ui/is_partial_loading_enabled.lua

 result =
 ui.is_partial_loading_enabled()
 
-TODO: documentation
+This function returns true, if partial loading has been enabled by calling
+ui.enable_partial_loading().
 
 --]]--
 

File framework/env/ui/link.lua

   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)

File framework/env/ui/partial.lua

 --[[--
 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 = {...}}.
 
 --]]--