JarCastingCross Domain Utils
A set of utilities for dealing with cross-domain windows
Public methods
getDomain(win : Window) => string
Get the full domain of the specified window, as a string.
winmust be a window on the same domain as the current window, or an exception will be raised- This can be overridden / mocked by setting
win.mockDomain = 'mock://some-domain.com';.mock://is required to ensure the window can not spoof actualhttp://orhttps://domains
getDomainFromUrl(url : string) => string
Get the full domain from the specified url, as a string.
- it will try to extract the domain from the url string if it starts with well known protocols (
http://,https://,file://, and additionallymock://urls) - if url string does not contain a known protocol, it will try to extract the domain calling
getDomainusing the current window as input
getActualDomain(win : Window) => string
Same as getDomain but overriding / mocking is disabled. it will return the real full domain of the specified window.
isBlankDomain(win : Window) => boolean
Returns if the domain for the specified window is blank, or about:blank
winmust be a window on the same domain as the current window, or an exception will be raisedwinmay be a window or iframe that has been newly opened by the current window
isSameDomain(win : Window) => boolean
Returns if the specified window is on the same domain as the current window.
- Does so without raising any errors or console warnings, even in Safari where wrapping the check
try/catchstill raises a console warning.
getParent(win : Window) => ?Window
Gets the parent of the specified window, if the window has a parent.
- Only returns the parent of iframes
- Returns void if the window is the top-level window
getOpener(win : Window) => ?Window
Gets the opener of the specified window, if the window has an opener.
- Only returns the opener of windows opened with
window.open - Returns void if the window is the top-level window
getParents(win : Window) => Array<Window>
Gets all of the hierarchical parents of the specified window.
- Only returns the parents of iframes
- Returns a blank array if the window is the top-level window
isAncestorParent(ancestor : Window, win : Window) => boolean
Returns true if the ancestor is a direct or non-direct parent of the specified window.
getFrames(win : Window) => Array<Window>
Returns an array of all direct child frames found in a given window.
- Only returns direct children
getAllChildFrames(win : Window) => Array<Window>
Returns an array of all recursive child frames found in a given window, and in the child-frames of that window.
- Recursively searches for all direct and indirect children
getTop(win : Window) => Window
Gets the top-level parent of the specified window.
getAllFramesInWindow(win : Window) => Array<Window>
Returns an array of all recursive child frames found in a given window, and in the child-frames of that window, including the specified window.
- Recursively searches for all direct and indirect children
isTop(win : Window) => boolean
Returns true if the specified window is the top level window, without any parents.
isFrameWindowClosed(frame : HTMLIFrameElement) => boolean
Returns true if the window attached to an iframe element is closed, by checking if the frame is still attached to an open document.
- Prefer
isWindowClosedwhen possible
isWindowClosed(win : Window) => boolean
Returns true if a window has been closed
- In IE/Edge, this check is not 100% reliable for frame windows where the frame has been removed from the DOM. Such window objects give no indication that they are closed.
getUserAgent(win : Window) => string
Gets the user agent for the specified window
- Window must be on the same domain as the current window
- Uses
win.navigator.mockUserAgentif specified, to allow for mocking / tests.
getFrameByName(win : Window, name : string) => ?Window
Gets a frame window with the given name, if it exists as a child of the specified window.
findChildFrameByName(win : Window, name : string) => ?Window
Recursively searches for a given frame window inside the children specified window.
findFrameByName(win : Window, name : string) => ?Window
Recursively searches for a given frame window inside the entire frame hierarchy of the specified window.
- Searches both the children and the parent windows recursively for the frame.
isParent(parent : Window, child : Window) => boolean
Returns true if the specified parent window is the parent of the specified child window.
isOpener(opener : Window, child : Window) => boolean
Returns true if the specified opener window is the opener of the specified child window.
getAncestor(win : Window) => ?Window
Gets either the parent or the opener of the specified window, if either is present.
getAncestors(win : Window) => Array<Window>
Recursively gets either the parent or the opener of the specified window, if either is present, and returns an array of the entire ancestor hierarchy.
isAncestor(ancestor : Window, child : Window) => boolean
Returns true if the specified ancestor window is the parent or the opener of the specified child window.
isPopup(win : Window) => boolean
Returns true if the specified window has been opened with window.open (i.e. if it is a popup window)
isIframe(win : Window) => boolean
Returns true if the specified window has been opened as an iframe.
getDistanceFromTop(win : Window) => number
Gets the numerical distance from the specified window to the top level window in that window's hierarchy.
- If the specified window is at the top, this will return 0.
getNthParent(win : Window, n : number) => ?Window
Gets the window n levels up from the specified window, if it exists.
isSameTopWindow(win1 : window, win2 : Window) => boolean
Returns true if the windows are in the same hierarchy, with the same top level window
- Will return false if one of the windows is a popup and the other window is not a frame inside that popup.
isWindow(obj : Window) => boolean
Returns true if the specified object is a window instance
onCloseWindow(win : Window, callback : Function, interval : number) => { cancel : Function }
Calls the callback when the specified window closes, with checks running on the specified interval.
- Returns a listener object with a
.cancel()method, to stop the loop
matchDomain(pattern : (string | RegExp | Array<string>), domain : string) => boolean
Returns true if the specified domain matches the pattern. The pattern can be one of:
- A literal string
- A regular expression
- An array of possible domains as strings
Tasks
All of the tasks are listed in the package.json file under the scripts section
| Command | Description |
|---|---|
| npm run build | Builds the dist files |
| npm test | Runs the test suite. Lint + Type + Karma |
Debugging
Run the debug task and pass the next tasks as argument.
npm run debug -- npm run build
npm run debug -- npm test
npm run debug -- npm run karma -- --browsers=Chrome
