/**
 * Base (common / universal) function for search form controls.
 *
 * @param  mixed  aValue       (int) Frame ID if search by Frame
 *                             (int) Interface Instance ID if search by Interface
 *                             (obj) Reference to form
 * @param  string aControlName Control Name
 * @param  string aAttrName    Form attribute name for comparison with "aValue". If "aValue" is reference to form, may be false or unsigned.
 * @return mixed               FALSE if no controls found, control's array otherwise
 * @access private
*/
function _getControlsCommon(aValue, aControlName, aAttrName)
{
    if (!aValue)      return false;
    if (!aControlName) return false;
    var ctls = document.getElementsByName(aControlName);
    if (!ctls || !ctls.length) return false;
    var out        = new Array();
    var form       = false;
    var vNeedValue = false;
    for (var i = 0; i < ctls.length; i++ ) {
        form   = ctls[i].form;
        if (!form) continue;
        if ((aAttrName == 'attr_frame_id') || (aAttrName == 'attr_instance_id')) {
            vNeedValue = form.getAttribute(aAttrName);
            if (vNeedValue == aValue) out[out.length] = ctls[i];
        } else if (!aAttrName) {
            if (form == aValue)       out[out.length] = ctls[i];
        }
    }
    return out.length ? out : false;
}

/**
 * Find form by Frame ID
 * 
 * @param  int    frameId     Frame ID
 * @return mixed              FALSE if form not found, reference to form otherwise
 * @access public
*/
function getFormByFrame(frameId)
{
    if (!frameId) return false;
    var fb = document.getElementById('framebox_' + frameId);
    if (!fb) return false;
    var forms = fb.getElementsByTagName('FORM');
    for (var i = 0; i < forms.length; i++ ) {
        if (frameId != 1) {
            var vFrameId = forms[i].getAttribute('attr_frame_id');
            if (vFrameId && vFrameId == frameId) return forms[i];
        } else {
            return forms[i];
        }
    }
    return false;
}

/**
 * Get interface ID by form
 * 
 * @param  obj    form        Reference to form
 * @return mixed              Interface Instance ID on success, null on failure (attribute is not present)
 * @access public
*/
function getInterfaceByForm(form)
{
    return form.getAttribute('attr_instance_id');
}
function getPluginByForm(form)
{
    return form.getAttribute('attr_plugin_num');
}

/**
 * Get frame ID by form
 * 
 * @param  obj    form        Reference to form
 * @return mixed              Frame ID on success, null on failure (attribute is not present)
 * @access public
*/
function getFrameByForm(form)
{
    return form.getAttribute('attr_frame_id');
}

/**
 * Find form's controls by control Name and form's Frame ID
 * 
 * @param  int    frameId     Frame ID
 * @param  string controlName Control Name
 * @return mixed              FALSE if no controls found, control's array otherwise
 * @access public
*/
function getControlsByFrame(frameId, controlName)
{
    return _getControlsCommon(frameId, controlName, 'attr_frame_id')
}

/**
 * Find form's controls by control Name and form's Instance ID
 * 
 * @param  int    instanceId  Interface Instance ID
 * @param  string controlName Control Name
 * @return mixed              FALSE if no controls found, control's array otherwise
 * @access public
*/
function getControlsByInterface(instanceId, controlName)
{
    return _getControlsCommon(instanceId, controlName, 'attr_instance_id')
}

/**
 * Find form's controls by control Name
 * 
 * @param  obj    form        Reference to form
 * @param  string controlName Control Name
 * @return mixed              FALSE if no controls found, control's collection otherwise
 * @access public
*/
function getControlsByForm(form, controlName)
{
    return _getControlsCommon(form, controlName)
}

/**
 * Find frame element by ID
 * 
 * @param  int    frameId   Frame ID
 * @param  string elementId Element ID without Frame ID postfix.
 * @return mixed            FALSE if no elements found, element otherwise.
 * @access public
*/
function getFrameElementById(frameId, elementId)
{
    if (!frameId)   return false;
    if (!elementId) return false;
    var ctls = document.getElementById(elementId + '_' + frameId);
    return ctls;
}

/**
 * Find frame elements by Name
 * 
 * @param  int    frameId        Frame ID.
 * @param  string elementOldName Element Name without Frame ID postfix.
 * @return mixed                 FALSE if no elements found, element's collection otherwise.
 * @access public
*/
function getFrameElementsByName(frameId, elementOldName)
{
    if (!frameId)        return false;
    if (!elementOldName) return false;
    var ctls = document.getElementsByName(elementOldName + '_' + frameId);
    if (!ctls || !ctls.length) return false;
    return ctls;
}