/ 
App-Context-0.968
River stage one • 2 direct dependents • 2 total dependents
/ App::UserAgent

NAME

App::UserAgent - the browser this session is connected to

SYNOPSIS

# ... official way to get a UserAgent object ...
use App;
$context = App->context();
$user_agent = $context->user_agent();  # get the user_agent

if ($user_agent->supports("html.input.style")) {
   # do something
}

DESCRIPTION

A UserAgent class models the browser connected to this session. It is used to determine what capabilities are supported by the user agent.

Constructor Methods:

new()

The App::UserAgent->new() method is rarely called directly. That is because a $user_agent should always be instantiated by getting it from the $context [ $context->user_agent() ].

* Signature: $user_agent = App::UserAgent->new($context);
* Signature: $user_agent = App::UserAgent->new();
* Param:  $context        App::Context
* Return: $user_agent     App::UserAgent
* Throws: <none>
* Since:  0.01

Sample Usage: 

[Common Use]
$context = App->context();
$user_agent = $context->user_agent();

[Internal Use Only]
$user_agent = App::UserAgent->new();

Public Methods

supports()

The supports() method returns whether or not a "feature" or "capability" is supported by a user agent (browser).

* Signature: $bool = $self->supports($capability);
* Param:  $capability     string
* Return: $bool           boolean
* Throws: <none>
* Since:  0.01

Sample Usage: 

if ($ua->supports("html.input.style")) {
    # do something
}

The following are some of the types of capabilities that the browser may or may not support. The capability categorization scheme is derived from the O'Reilly book, "Dynamic HTML: The Definitive Reference", which has sections on HTML, DOM, CSS, and JavaScript. Java and HTTP capabilities are also defined. Finally, hints are defined which simply tell the session objects what to use on certain browsers.

html.<tag>
html.<tag>.<attrib>
html.input.style
html.input.style.border-width

dom
dom.<object_class>
dom.<object_class>.<attribute>

style
style.css1
style.css2
style.<attribute>

js
js.1.0
js.1.1
js.1.2
js.<class>.<method>
js.<class>.<attribute>

java.1.0.0
java.1.2.2
java.1.3.0

http.header.accept-encoding.x-gzip
http.header.accept-encoding.x-compress

session_object.Stylizable.style

get()

The get() method retrieves attributes of the user agent.

* Signature: $bool = $self->parse($http_user_agent);
* Param:  $http_user_agent string
* Return: $bool            boolean
* Throws: <none>
* Since:  0.01

Sample Usage: 

$http_user_agent = "Mozilla/4.0 (compatible; MSIE 5.5; Windows NT)";
@ua = $user_agent->parse($http_user_agent);
@ua = $App::UserAgent->parse($ENV{HTTP_USER_AGENT});
($uatype, $uaver, $ostype, $osver, $arch, $lang) = @ua;

The following attributes of the $user_agent are also defined. The bracketed values ([value]) are the defaults if no other value can be determined by the HTTP_USER_AGENT string and the other HTTP headers.

uatype - User Agent type       (i.e. [unknown], NS, IE, Opera, Konqueror, Mozilla)
uaver  - User Agent version    (i.e. [1.0], 4.0, 4.7, 5.01) (always numeric)
ostype - Oper System type      (i.e. [unknown], Windows, Macintosh, Linux, FreeBSD, HP-UX, SunOS, AIX, IRIX, OSF1)
osver  - Oper System version   (i.e. [unknown], 16, 3.1, 95, 98, 2000, ME, NT 5.1)
arch   - Hardware Architecture (i.e. [unknown], i386, i586, i686, ppc, sun4u, 9000/835)
lang   - Preferred Language    (i.e. [en], en-us, fr-ca, ja, de)

There is very little reason for any SessionObject code to call get() directly. SessionObjects should rather use the supports() method to determine whether a capability is supported by the browser. The supports method will consult these attributes and its capability matrix to determine whether the capability is supported or not.

sub get { my ($self, $attribute) = @_; $self->{$attribute}; }

############################################################################# # parse() #############################################################################

parse()

The parse() method parses an HTTP_USER_AGENT string and returns the resulting attributes of the browser.

* Signature: $bool = $self->parse($http_user_agent);
* Param:  $http_user_agent string
* Return: $bool            boolean
* Throws: <none>
* Since:  0.01

Sample Usage: 

$http_user_agent = "Mozilla/4.0 (compatible; MSIE 5.5; Windows NT)";
@ua = $user_agent->parse($http_user_agent);
@ua = $App::UserAgent->parse($ENV{HTTP_USER_AGENT});
($uatype, $uaver, $ostype, $osver, $arch, $lang) = @ua;

Note: Two additional attributes, $mozver and $iever are probably going to be needed. They represent the Netscape/Mozilla version that the software claims to operate like (IE has always included this) and the IE version that the software claims to operate like (Opera includes this). This will allow for a cascading of one type of compatibility matrix into another.

Protected Methods

get_support_matrix()

The get_support_matrix() method returns whether or not a "feature" or "capability" is supported by a user agent (browser).

* Signature: $support_matrix = $ua->get_support_matrix($uatype, $uaver, $ostype, $osver, $arch, $lang);
* Param:  $uatype         string
* Param:  $uaver          float
* Param:  $ostype         string
* Param:  $osver          string
* Param:  $arch           string
* Param:  $lang           string
* Return: $support_matrix {}
* Throws: <none>
* Since:  0.01

Sample Usage: 

$support_matrix = $self->get_support_matrix($uatype, $uaver, $ostype, $osver, $arch, $lang);

The following are some of the types of capabilities that the browser may or may not support.