Storyboard Lua DOM Module

The Storyboard gredom Lua module provides a limited access to the hierarchical model used by the Storyboard Engine. This functionality is provided as an external Lua module and is located in the lib/gredom.so file of the Storyboard Engine target distributions.

The DOM module provides two sets of function interfaces. The first set of functions are associated with the gredom namespace and are used to lookup or access an Lua object (table) that contains a special set of methods (metatable entries) that are used to extract additional information about the object. In this documentation the object returned from the gredom namespace functions will be referred to as a DOMOBJECT object. Methods associated with the DOMOBJECT object must be invoked using the Lua colon (:) notation for example DOMOBJECT:get_name()

gredom.get_application

gre.get_application()

Get an object handle for the application root


Returns:
        A DOMOBJECT object that represents the application.
                    

gredom.get_object

gre.get_object(fqn)

Get an object handle for the


Parameters:
        fqn    The fully qualified name of the model entry (screen, layer, control), or a short name to
                 autosearch for a match

Returns:
        A DOMOBJECT object that represents the named model object.
                    

DOMOBJECT:get_name

DOMOBJECT:get_name()

Gets the name of the specified DOM Object


Returns:
        The name of the specified DOMOBJECT
                    

DOMOBJECT:get_type

DOMOBJECT:get_type()

Gets the Storyboard type of the specified DOMOBJECT. The type may be one of gredom.APP, gredom.SCREEN, gredom.LAYER, gredom.LAYER_INSTANCE, gredom.GROUP grecom.CONTROL, gredom.TABLE, gredom.TEMPLATE.


Returns:
        A the type of the specified DOMOBJECT.
                    

DOMOBJECT:get_parents

DOMOBJECT:get_parents()

Gets the parent DOMOBJECT objects for the specified DOMOBJECT. An array of parents is returned because in some cases, such as for a layer, there may be more than one parent representation.


Returns:
        An array table containing the parent DOMOBJECT entries.
                    

DOMOBJECT:get_children

DOMOBJECT:get_children()

Gets the child DOMOBJECT objects for the specified DOMOBJECT. This function returns only the model objects and does not include the variables.


Returns:
        An array table containing the child DOMOBJECT entries
                    

DOMOBJECT:get_variables

DOMOBJECT:get_variables()

Gets variables associated with the specified DOMOBJECT


Returns:
        An array table containing the variables associated with this object.
                    

Lua DOM Samples

require("gredom")

-- Print a list of all of the user variables associated with a specified
-- control
function print_variables(control_name)
    -- Get the DOM object for the control name passed in
    local domObject = gredom.get_object(control_name)
    if(domObject == nil) then
      print("Can't find name for " .. tostring(control_name))
      return
    end

    -- Get the variables defined on this DOM object
    local vars = domObject:get_variables()
    if(vars == nil or #vars == 0) then
      print("No variables for " .. control_name)
    else
      print("Variables for " .. control_name)
      for i=1,#vars do
          print("# " .. tostring(vars[i]))
      end
    end
end

-- Print out all of the screens where this control's container layer is
-- being used
function print_used_on_screens(control_name)
    -- Get the DOM object for the control name passed in
    local domObject = gredom.get_object(control_name)
    if(domObject == nil) then
      print("Can't find name for " .. tostring(control_name))
      return
    end

    -- Build up the full path to this object
    -- Walk up the tree looking at all parents adding screens we find
    local screen_list = {}
    local parent_list = {}
    table.insert(parent_list, domObject:get_parents())

    local i = 1
    while i <= #parent_list do
      local parents = parent_list[i]
      for p=1,#parents do
        -- If this was a screen, add it to our collection
        if parents[p]:get_type() == gredom.SCREEN then
          screen_list[parents[p]] = true
        else
          -- If this has parents of its own, then add them to the search
          -- list
          parents = parents[p]:get_parents()
          if(parents ~= nil and #parents > 0) then
            table.insert(parent_list, parents)
          end
        end
      end
      i = i + 1
    end

    -- Print out all of the screens that we have identified
    print(control_name .. " is used on the following screens:")
    for screen,v in pairs(screen_list) do
      print("# " .. screen:get_name())
    end
end

-- Invoke our DOM example functions with the context control
function CBDom(mapargs)
  print_used_on_screens(mapargs.context_control)
  print_variables(mapargs.context_control)
end