Skip to content

WindowAttributes

Jump to bottom
Mark Reeves edited this page Jan 3, 2018 · 7 revisions

Note WindowAttributes is no longer applied in the client as it causes significant accessibility problems and is incompatible with most modern and all mobile browsers. WLink may still open a link in a new window/tab but all other attributes are ignored. WindowAttributes will be removed from WComponents 2.

The rest of this document applies only to WComponents versions before 1.4.

WindowAttributes is a sub-component of WLink, WInternalLink and WContentLink. It is used to provide a set of parameters for opening a new window when invoking a link. This is considered harmful.

Using WindowAttributes

WindowAttributes is used with WLink. The easiest way to create a WLink with WindowAttributes is to use WLink.Builder which supports chaining to set the various properties.

// Build a WLink with WindowAttributes. THis assumes strings
// * DESCRIPTION being the link text
// * URL being the URL to link to
// * WINDOW_NAME being the name of the popup window.
// Not everything is needed this is just an extreme example.
WLink aLink = new WLink.Builder(DESCRIPTION, URL)
    .windowName(WINDOW_NAME) // the window name of the window to open
    .top(TOP) // top position in pixels
    .left(LEFT) // left position in pixels
    .width(WIDTH) // popup width in pixels
    .height(HEIGHT) // popup height in pixels
    .resizeable(true) // allow resize
    .menubar(true) // allow menu bar
    .toolbar(true) // allow toolbar
    .location(true) // allow address box
    .status(true) // allow status bar
    .scrollbars(true) // allow scrollbars
    .build();

Under most circumstances only windowName should be set. This will create a HTML a element with a target attribute set. If any other properties are set then the WLink will output a HTML button element. See WLink for more details.

// With strings
// * DESCRIPTION being the link text
// * URL being the URL to link to
// * WINDOW_NAME being the name of the popup window:
WLink aLink = new WLink.Builder(DESCRIPTION, URL)
    .windowName(WINDOW_NAME).build();

WindowAttributes has a default constructor and may be instantiated then have its properties set later.

WindowAttributes attrib = new WindowAttributes();

// ...
// The window name could be context specific
// for example all help opens in a `helpWindow`
// assume string someWindowName
attrib.setWindowName(someWindowName);

Usability

WindowAttributes is used to make a Wlink open in a pop-up window or tab. If it is absolutely required that a WLink does this then, under most circumstances it is strongly recommended that only the [windowName] property be set. See MDN for a good discussion of usability issues of window.open which is the ultimate output of WindowAttributes if properties other than [windowName] are set.

Mobile usability

Pop-up windows are very bad for all users and particularly bad for mobile users. In particular, if an application is likely to be used on a mobile device then the [top], left, [width] and height properties should never be set and it is strongly recommended that if a WLink must open a popup window that only [windowName] should be set.

IE on Windows Mobile 8

No popups will work on Windows Mobile 8, including links using the target attribute. If your application has a supported user base which includes users of Windows Mobile 8 then the application cannot use WindowAttributes.

Accessibility

When a Wlink has WindowAttributes with properties in addition to [windowName] the button element produced to open the pop-up will be marked with the attribute aria-haspopup="true". This is the minimum we can do to help AT users be pre-informed that a button will open a pop-up but it is not in itself sufficient. It is best practice to ensure that all users are aware a link or button will open a new window (or browser tab) before they invoke the link. This is best done in the link text as it is then available to all users.

Properties of WindowAttributes

The following properties are used to determine specific options in the pop-up window. Only the name property is required and if it is the only property specified then all other properties are ignored and the user agent will determine how to open and decorate the pop-up window. If any property is specified in addition to the name property then all unspecified properties will be given their default value.

Warning

The properties which effect the visibility of certain browser components are all commonly ignored by many user agents and are able to be easily overridden. These must never be relied upon to provide isolation of the pop-up window for 'security' purposes or to disable browser function simply because this will not work.

This includes turning off the location bar to 'hide' the URL of a particular page. This is simply a pointless exercise. If you are intending to turn off browser components in a pop up you should do so purely for aesthetic reasons and in the full knowledge that all of these properties are easily over-ridden.

User overrides

Some user agents may ignore any of the following properties other than the name property. Some user agents allow users to determine how a pop up will open and may be in a new tab rather than a new window in which case all properties other than name are irrelevant. All modern user agents include pop-up blockers so if your link has a pop-up you should forewarn the user of this so they may decide whether to disable the pop-up blocker.

WindowName

This is an internal reference to the window name and is not exposed to the user. Several WLink components may have WindowAttributes with the same name property. These will cause the pop-up to open in the same window as each other with all invocations after the first replacing the previous content.

If a WLink is to open in a new window this property must be explicitly specified for each instance of a WLink with a pop-up in your UI. A new and unique window may be specified using the name _blank if no other properties are specified; note, however, that this is considered a very bad thing

// A WLink which will _always_ open a new window/tab. Using strings
// * DESCRIPTION being the link text
// * URL being the URL to link to:
WLink aLink = new WLink.Builder(DESCRIPTION, URL)
    .windowName("_blank").build();

// given WindowAttribute attrib and string someWindowName
attrib.setWindowName(someWindowName);

Internet Explorer Issue

Internet Explorer takes an approach to the name property which deviates from published standards and is poorly documented. To ensure cross-browser functionality it is recommended that the following method be used for specifying a name:

  • If the pop up must be unique and no other properties are specified use the name _blank;
  • In all other cases specify a name which starts with a letter and contains only letters and numbers (/[a-zA-Z][a-zA-Z0-9]*/). Note: do not use \w in the regular expression as this may include _ which may, under some circumstances, break IE.

Top

This is used to specify the position of the top of the pop-up relative to the top of the user's screen in pixels. If not specified the default is determined by the user agent. Some user agents may ignore this even if they implement other properties. This property should probably not be set. It is strongly recommended that this property is never set if the application will be used outside of an Intranet with known client browsers and hardware.

// given WindowAttribute attrib and int TOP
attrib.setTop(TOP);

Left

This is used to specify the position of the left edge of the pop-up relative to the left edge of the user's screen in pixels. If not specified the default is determined by the user agent. Some user agents may ignore this even if they implement other properties. This property should probably not be set. It is strongly recommended that this property is never set if the application will be used outside of an Intranet with known client browsers and hardware.

// given WindowAttribute attrib and int LEFT
attrib.setLeft(LEFT);

Width

This is used to specify the width of the pop-up in pixels. Some user agents may ignore this even if they implement other properties. This property should probably not be set. It is strongly recommended that this property is never set if the application will be used outside of an Intranet with known client browsers and hardware.

// given WindowAttribute attrib and int WIDTH
attrib.setWidth(WIDTH);

Height

This is used to specify the height of the pop-up in pixels. Some user agents may ignore this even if they implement other properties. This property should probably not be set. It is strongly recommended that this property is never set if the application will be used outside of an Intranet with known client browsers and hardware.

// given WindowAttribute attrib and int HEIGHT
attrib.setHeight(HEIGHT);

Resizeable

Under review: the option to specify a pop up window as not resizeable may be removed as it can cause significant accessibility and usability issues.

This Boolean property is used to indicate whether the pop-up window is resizeable by the user and defaults to false if any property other than name is set. Many modern user agents ignore this property and a pop-up is always resizeable; others provide a mechanism for the user to override this property and set all pop-ups to be resizeable.

// given WindowAttribute attrib
attrib.setResizeable(true);

NOTE: If any property other than name is set then this property should always be specified to be true. This will allow users to resize a pop-up which may, for example, be necessary if they use a large font or have a small screen.

Menubar

This Boolean property is used to indicate whether the user agents menu bar is shown and defaults to false if any property other than name is set.

// given WindowAttribute attrib
attrib.setMenubar(true);

Toolbar

This Boolean property is used to indicate whether the user agents tool bar (if any) is shown and defaults to false if any property other than name is set.

// given WindowAttribute attrib
attrib.setToolbar(true);

Location

This Boolean property is used to indicate whether the user agents address/location bar (if any) is shown and defaults to false if any property other than name is set.

// given WindowAttribute attrib
attrib.setLocation(true);

Status

This Boolean property is used to indicate whether the user agents status bar (if any) is shown and defaults to false if any property other than name is set.

// given WindowAttribute attrib
attrib.setStatus(true);

Scrollbars

Under review: the option to specify a pop up window as not showing scroll bars may be removed as it can cause significant accessibility and usability issues.

This Boolean property is used to indicate whether the user agents scroll bars (if any) is shown and defaults to false if any property other than name is set.

// given WindowAttribute attrib
attrib.setScrollbars(true);

NOTE: If any property other than name is set then this property should always be specified to be true. This will allow users to scroll the content within a dialog if the content is larger than the dialog's size and may be necessary, for example, if they use a large font or a screen magnifier, or have a small screen.

Related components

Further information

[top]: #top) [width]: #width [windowName]: #windowname

Some start pages

Clone this wiki locally