/**
 ******************************************************************************
 *
 * Confidential Property of Documentum, Inc.
 * (c) Copyright Documentum, Inc. 2001.
 * All Rights reserved.
 * May not be used without prior written agreement
 * signed by a Documentum corporate officer.
 *
 ******************************************************************************
 *
 * Project        Lister
 * File           locate.js
 * Description    the javascript responsible for finding frames
 * Created on     19th June 2001
 * Tab width      3
 *
 ******************************************************************************
 *
 * PVCS Maintained Data
 *
 * Revision       $$
 * Modified on    $$
 *
 * Log at EOF
 *
 ******************************************************************************
 */

// top level window
var topLevelWnd = null;

/**
 * Initialise top level window
 */
function getTopLevelWnd()
{
   if (topLevelWnd == null)
   {
      topLevelWnd = this;
      while (topLevelWnd.parent != topLevelWnd && isDispatchableWindow(topLevelWnd.parent))
      {
         topLevelWnd = topLevelWnd.parent;
      }
      while (topLevelWnd.opener != null && isDispatchableWindow(topLevelWnd.opener))
      {
         topLevelWnd = topLevelWnd.opener;
      }
   }

   return topLevelWnd;
}

/**
 * Search down the frame hierachy for an object with the specified name and return it's path
 *
 * @param frameName            the name to find
 *
 * @return the found frame path
 */
function getAbsoluteFramePath(frameName)
{
   var absolutePath = null;
   var framePath = getRelativeFramePath(getTopLevelWnd(), frameName);
   if (framePath != null)
   {
      absolutePath = "getTopLevelWnd()." + framePath;
   }

   return absolutePath;
}

/**
 * Search down the frame hierachy for an object with the specified name
 *
 * @param containerFrame       the object whose frames we are examining
 * @param frameName            the name to find
 *
 * @return the found frame path
 */
function getRelativeFramePath(containerFrame, frameName)
{
   var framePath = null;

   for (var iChildFrame = 0; iChildFrame < containerFrame.frames.length; iChildFrame++)
   {
      var objChildFrame = containerFrame.frames[iChildFrame];
      if (isAccessibleWindow(objChildFrame) && objChildFrame.name == frameName)
      {
         framePath = "frames[" + iChildFrame + "]";
         break;
      }
   }

   if (framePath == null)
   {
      for (var iChildFrame = 0; iChildFrame < containerFrame.frames.length; iChildFrame++)
      {
         var childFramePath = getRelativeFramePath(containerFrame.frames[iChildFrame], frameName);
         if (childFramePath != null)
         {
            framePath = "frames[" + iChildFrame + "]." + childFramePath;
            break;
         }
      }
   }

   return framePath;
}

/**
 * Get framename path to passed window - where a framename path is a '/'
 * separated list of framenames.
 *
 * @param  window object
 *
 * @return framename path to window, or null if the window is not in the frameset
 */
function getFrameNamePath(wnd)
{
   // recurively build parent's frame path
   if (wnd == getTopLevelWnd())
   {
      return "";
   }

   var parent = wnd.parent;
   if (parent != null)
   {
      for (var i = 0; i < parent.frames.length; i++)
      {
         var frameWnd = parent.frames[i];
         if (frameWnd == wnd)
         {
            var parentFrameNamePath = getFrameNamePath(parent);
            if (parentFrameNamePath != null)
            {
               return parentFrameNamePath + '/' + frameWnd.name;
            }
         }
      }
   }

   return null;
}

/**
 * returns whether the passed framename path exists in the current frameset
 *
 * @param framePath  Frame name path
 *
 * @return Whether frameNamePath exists
 */
function isValidFrameNamePath(frameNamePath)
{
   return _isValidFrameNamePath(getTopLevelWnd(), frameNamePath.substring(1));
}
function _isValidFrameNamePath(wnd, frameNamePath)
{
   // extract name from framename path
   var slash = frameNamePath.indexOf("/");
   if (slash != -1)
   {
      var frameName = frameNamePath.substring(0, slash);
      for (var i = 0; i < wnd.frames.length; i++)
      {
         if (wnd.frames[i].name == frameName)
         {
            return _isValidFrameNamePath(wnd.frames[i], frameNamePath.substring(slash+1))
         }
      }

      return false;
   }
   else
   {
      return true;
   }
}

/**
 * Walk down a frame path if it is nest.jsp, until the actual frame at
 * the bottom (the leaf) is found. Note that the leaves of nest.jsp are not
 * named, so it is necessary to walk down like this to get to the jsp that is
 * being displayed.
 * @param strFramePath The frame path to walk down - eval(strFramePath) should
 *                     return a valid frame object for this to work.
 *
 * @return String  The final frame path.
 */
function walkDownFrameSet(strFramePath)
{
   var strResult = strFramePath;
   if ((strResult != null) && (typeof strResult != "undefined"))
   {
      //Walk down to the leaf
      var strFrameUrl = eval(strResult).document.location.href;
      while ((eval(strResult).isNest != null) && (typeof eval(strResult).isNest != "undefined"))
      {
         //Drill down into frames[0] of nest.jsp, update strResult and get its href
         strResult += ".frames[0]";
         strFrameUrl = eval(strResult).document.location.href;
      }
   }
   return strResult;
}

/**
 * Determine if the specified window allows testing of existence of
 * dispatch events.
 *
 * NOTE: Windows which contain a document loaded from a domain that is
 *       different to the one that this script executes in, are subject
 *       to strict browser security. This means that the frame does not
 *       allow interrogation of its properties. MS Knowledge Base
 *       article Q167796.
 *
 * NOTE: Also, windows which contain applications such as word and
 *       excel behave strangely when interrogated.
 *
 * @param   wnd            the window to test
 *
 * @return                 true => allows testing,
 *                         false => does not allow testing
 */
function isDispatchableWindow(wnd)
{
   var bIsDispatchable = false;

   if (typeof(wnd.getTopLevelWnd) != "undefined")
   {
      bIsDispatchable = isAccessibleWindow(wnd);
   }

   return bIsDispatchable;

} // isDispatchableWindow

/**
 * Determine if the specified window can be accessed although it may not be initialized yet.
 *
 * NOTE: Windows which contain a document loaded from a domain that is
 *       different to the one that this script executes in, are subject
 *       to strict browser security. This means that the frame does not
 *       allow interrogation of its properties. MS Knowledge Base
 *       article Q167796.
 *
 * NOTE: Also, windows which contain applications such as word and
 *       excel behave strangely when interrogated.
 *
 * @param   wnd            the window to test
 *
 * @return                 true => allows testing,
 *                         false => does not allow testing
 */
function isAccessibleWindow(wnd)
{
   var bIsAccessible = false;

   // Test for application
   if (typeof(wnd.frames) == "object")
   {
      // Test for another domain
      if ("x" + wnd.location + "x" != "xx")
      {
         // Test for application
         if (typeof(wnd.frames) == "object")
         {
            bIsAccessible = true;
         }
      }
   }

   return bIsAccessible;

} // isAccessibleWindow

/**
 * Return whether passed window is initialised (fully loaded)
 *
 * @param   wnd            the window to test
 *
 * @return                 true => allows testing,
 *                         false => does not allow testing
 */
function isWindowInitialised(wnd)
{
   var bWindowInitialised = false;

   if (isDispatchableWindow(wnd) == true)
   {
      // the g_bWindowInitialised flag is initialised by the FormTag
      if (typeof(wnd.g_bWindowInitialised) != "undefined")
      {
         bWindowInitialised = wnd.g_bWindowInitialised;
      }
      else
      {
         bWindowInitialised = true;
      }
   }

   return bWindowInitialised;
}

/**
 * create test hook image used by test automation tools to determine when the
 * window has been initialised.
 *
 * @param contextPath context path E.g. '/webtop'
 */
function createTestHook(contextPath)
{
   var element = window.document.createElement("IMG");

   element.id = "wdk_window_initialised";
   element.src = contextPath + "/wdk/modalFade.gif";

   with (element.style)
   {
		top = 1;
		left = 1;
   	width = 1;
		height = 1;
      alt = "";
      overflow = "hidden";
		position = "absolute";
		visibility = "visible";
   }

	window.document.body.appendChild(element);
}

/**
 * Sets the focus on the specified frame
 *
 * @param   strFrameName   the frame to switch to
 *
 */
function setFocusOnFrame(strFrameName)
{
   var strFramePath = getAbsoluteFramePath(strFrameName);
   var frameWindow = eval(getAbsoluteFramePath(strFrameName)); 
   frameWindow.focus();
}