Package com.smartgwt.client.types

# Enum LocatorStrategy

java.lang.Object
java.lang.Enum<LocatorStrategy>
com.smartgwt.client.types.LocatorStrategy

All Implemented Interfaces:
  `ValueEnum`, `Serializable`, `Comparable<LocatorStrategy>`, `Constable`

public enum LocatorStrategy extends Enum<LocatorStrategy> implements ValueEnum
The AutoTest subsystem relies on generating and parsing identifier strings to identify components on the page. A very common pattern is identifying a specific component within a list of possible candidates. There are many many cases where this pattern is used, for example - members in a layout, tabs in a tabset, sections in a section stack.

In order to make these identifiers as robust as possible across minor changes to an application, (such as skin changes, minor layout changes, etc) the system will store multiple pieces of information about a component when generating an identification string to retrieve it from a list of candidates. The system has a default strategy for choosing the order in which to look at these pieces of information but in some cases this can be overridden by setting a `LocatorStrategy`.

By default we use the following strategies in order to identify a component from a list of candidates:

- `name`: Does not apply in all cases but in cases where a specified `name` attribute has meaning we will use it - for example for `sections in a section stack` or `images`.
- `title`: If a title is specified for the component this may be used as a legitimate identifier if it is unique within the component - for example differently titled tabs within a tabset.
- `index`: Locating by index is typically less robust than by name or title as it is likely to be affected by layout changes on the page.

If an explicit strategy is specified, that will be used to locate the component if possible. If no matching component is found using that strategy, we will continue to try the remaining strategies in order as described above. In other words setting a locatorStrategy to "title" will skip attempting to find a component by name, and instead attempt to find by title - or failing that by index.

In cases where the name is considered definitive, such as for `Tabs` or `FormItems`, no fallback check will occur if a name is provided in the locator but doesn't match a live object - the locator will fail to match anything. Furthermore, in the case of `Tabs`, `FormItems`, or collections other than `children of a widget`, if a title is present in the locator and you haven't specified specified "index" as the strategy, there may be no fallback check using the index if the locator title fails to match.

To avoid the Framework trying to match by name or title where they are assumed definitive and we skip fallback to the remaining locator attributes, you'll need to remove the name or title from the locator in question (or set the locatorStrategy to "index" in the case of the title).

Note that we also support matching by type (see `LocatorTypeStrategy`). Matching by type is used if we were unable to match by name or title or to disambiguate between multiple components with a matching title.

- ## Nested Class Summary

  ## Nested classes/interfaces inherited from class java.lang.Enum

  `Enum.EnumDesc<E extends Enum<E>>`

- ## Enum Constant Summary

  Enum Constants
  Enum Constant
  Description
  `INDEX`
  Match by index
  `NAME`
  Match by name if possible.
  `TITLE`
  Match by title if possible.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `String`
  `getValue()`
  `static LocatorStrategy`
  `valueOf(String name)`
  Returns the enum constant of this type with the specified name.
  `static LocatorStrategy[]`
  `values()`
  Returns an array containing the constants of this enum type, in the order they are declared.

  ### Methods inherited from class java.lang.Enum

  `clone, compareTo, describeConstable, equals, finalize, getDeclaringClass, hashCode, name, ordinal, toString, valueOf`

  ### Methods inherited from class java.lang.Object

  `getClass, notify, notifyAll, wait, wait, wait`

- ## Enum Constant Details

  - ### NAME

    public static final LocatorStrategy NAME
    Match by name if possible.

    If this enumerated value is used in a `Component XML` file or server-side DataSource descriptor (.ds.xml file), use the value "name".

  - ### TITLE

    public static final LocatorStrategy TITLE
    Match by title if possible.

    If this enumerated value is used in a `Component XML` file or server-side DataSource descriptor (.ds.xml file), use the value "title".

  - ### INDEX

    public static final LocatorStrategy INDEX
    Match by index

    If this enumerated value is used in a `Component XML` file or server-side DataSource descriptor (.ds.xml file), use the value "index".

- ## Method Details

  - ### values

    public static LocatorStrategy[] values()
    Returns an array containing the constants of this enum type, in the order they are declared.
    Returns:
      an array containing the constants of this enum type, in the order they are declared

  - ### valueOf

    public static LocatorStrategy valueOf(String name)
    Returns the enum constant of this type with the specified name. The string must match exactly an identifier used to declare an enum constant in this type. (Extraneous whitespace characters are not permitted.)
    Parameters:
      `name` - the name of the enum constant to be returned.
    Returns:
      the enum constant with the specified name
    Throws:
      `IllegalArgumentException` - if this enum type has no constant with the specified name
      `NullPointerException` - if the argument is null

  - ### getValue

    public String getValue()
    Specified by:
      `getValue` in interface `ValueEnum`