From 8ede1a2ecbb62577afd32996956c5feaf7ddf9b6 Mon Sep 17 00:00:00 2001 From: Derek Jones Date: Wed, 5 Oct 2011 13:34:52 -0500 Subject: replacing the old HTML user guide with a Sphinx-managed user guide --- user_guide_src/source/libraries/user_agent.rst | 150 +++++++++++++++++++++++++ 1 file changed, 150 insertions(+) create mode 100644 user_guide_src/source/libraries/user_agent.rst (limited to 'user_guide_src/source/libraries/user_agent.rst') diff --git a/user_guide_src/source/libraries/user_agent.rst b/user_guide_src/source/libraries/user_agent.rst new file mode 100644 index 000000000..8099678e2 --- /dev/null +++ b/user_guide_src/source/libraries/user_agent.rst @@ -0,0 +1,150 @@ +################ +User Agent Class +################ + +The User Agent Class provides functions that help identify information +about the browser, mobile device, or robot visiting your site. In +addition you can get referrer information as well as language and +supported character-set information. + +Initializing the Class +====================== + +Like most other classes in CodeIgniter, the User Agent class is +initialized in your controller using the $this->load->library function:: + + $this->load->library('user_agent'); + +Once loaded, the object will be available using: $this->agent + +User Agent Definitions +====================== + +The user agent name definitions are located in a config file located at: +application/config/user_agents.php. You may add items to the various +user agent arrays if needed. + +Example +======= + +When the User Agent class is initialized it will attempt to determine +whether the user agent browsing your site is a web browser, a mobile +device, or a robot. It will also gather the platform information if it +is available. + +:: + + $this->load->library('user_agent'); if ($this->agent->is_browser()) {     $agent = $this->agent->browser().' '.$this->agent->version(); } elseif ($this->agent->is_robot()) {     $agent = $this->agent->robot(); } elseif ($this->agent->is_mobile()) {     $agent = $this->agent->mobile(); } else {     $agent = 'Unidentified User Agent'; } echo $agent; echo $this->agent->platform(); // Platform info (Windows, Linux, Mac, etc.) + +****************** +Function Reference +****************** + +$this->agent->is_browser() +=========================== + +Returns TRUE/FALSE (boolean) if the user agent is a known web browser. + +:: + + if ($this->agent->is_browser('Safari')) {     echo 'You are using Safari.'; } else if ($this->agent->is_browser()) {     echo 'You are using a browser.'; } + +.. note:: The string "Safari" in this example is an array key in the + list of browser definitions. You can find this list in + application/config/user_agents.php if you want to add new browsers or + change the stings. + +$this->agent->is_mobile() +========================== + +Returns TRUE/FALSE (boolean) if the user agent is a known mobile device. + +:: + + if ($this->agent->is_mobile('iphone')) {     $this->load->view('iphone/home'); } else if ($this->agent->is_mobile()) {     $this->load->view('mobile/home'); } else {     $this->load->view('web/home'); } + +$this->agent->is_robot() +========================= + +Returns TRUE/FALSE (boolean) if the user agent is a known robot. + +.. note:: The user agent library only contains the most common robot + definitions. It is not a complete list of bots. There are hundreds of + them so searching for each one would not be very efficient. If you find + that some bots that commonly visit your site are missing from the list + you can add them to your application/config/user_agents.php file. + +$this->agent->is_referral() +============================ + +Returns TRUE/FALSE (boolean) if the user agent was referred from another +site. + +$this->agent->browser() +======================= + +Returns a string containing the name of the web browser viewing your +site. + +$this->agent->version() +======================= + +Returns a string containing the version number of the web browser +viewing your site. + +$this->agent->mobile() +====================== + +Returns a string containing the name of the mobile device viewing your +site. + +$this->agent->robot() +===================== + +Returns a string containing the name of the robot viewing your site. + +$this->agent->platform() +======================== + +Returns a string containing the platform viewing your site (Linux, +Windows, OS X, etc.). + +$this->agent->referrer() +======================== + +The referrer, if the user agent was referred from another site. +Typically you'll test for this as follows:: + + if ($this->agent->is_referral()) {     echo $this->agent->referrer(); } + +$this->agent->agent_string() +============================= + +Returns a string containing the full user agent string. Typically it +will be something like this:: + + Mozilla/5.0 (Macintosh; U; Intel Mac OS X; en-US; rv:1.8.0.4) Gecko/20060613 Camino/1.0.2 + +$this->agent->accept_lang() +============================ + +Lets you determine if the user agent accepts a particular language. +Example:: + + if ($this->agent->accept_lang('en')) {     echo 'You accept English!'; } + +.. note:: This function is not typically very reliable since some + browsers do not provide language info, and even among those that do, it + is not always accurate. + +$this->agent->accept_charset() +=============================== + +Lets you determine if the user agent accepts a particular character set. +Example:: + + if ($this->agent->accept_charset('utf-8')) {     echo 'You browser supports UTF-8!'; } + +.. note:: This function is not typically very reliable since some + browsers do not provide character-set info, and even among those that + do, it is not always accurate. -- cgit v1.2.3-24-g4f1b From 06cd162f1b9ed88a8a903468e6eafd79248d383e Mon Sep 17 00:00:00 2001 From: Derek Jones Date: Wed, 5 Oct 2011 15:30:47 -0500 Subject: fixed code block samples for User Agent lib --- user_guide_src/source/libraries/user_agent.rst | 62 +++++++++++++++++++++++--- 1 file changed, 56 insertions(+), 6 deletions(-) (limited to 'user_guide_src/source/libraries/user_agent.rst') diff --git a/user_guide_src/source/libraries/user_agent.rst b/user_guide_src/source/libraries/user_agent.rst index 8099678e2..855ece29d 100644 --- a/user_guide_src/source/libraries/user_agent.rst +++ b/user_guide_src/source/libraries/user_agent.rst @@ -34,7 +34,28 @@ is available. :: - $this->load->library('user_agent'); if ($this->agent->is_browser()) {     $agent = $this->agent->browser().' '.$this->agent->version(); } elseif ($this->agent->is_robot()) {     $agent = $this->agent->robot(); } elseif ($this->agent->is_mobile()) {     $agent = $this->agent->mobile(); } else {     $agent = 'Unidentified User Agent'; } echo $agent; echo $this->agent->platform(); // Platform info (Windows, Linux, Mac, etc.) + $this->load->library('user_agent'); + + if ($this->agent->is_browser()) + { + $agent = $this->agent->browser().' '.$this->agent->version(); + } + elseif ($this->agent->is_robot()) + { + $agent = $this->agent->robot(); + } + elseif ($this->agent->is_mobile()) + { + $agent = $this->agent->mobile(); + } + else + { + $agent = 'Unidentified User Agent'; + } + + echo $agent; + + echo $this->agent->platform(); // Platform info (Windows, Linux, Mac, etc.) ****************** Function Reference @@ -47,7 +68,15 @@ Returns TRUE/FALSE (boolean) if the user agent is a known web browser. :: - if ($this->agent->is_browser('Safari')) {     echo 'You are using Safari.'; } else if ($this->agent->is_browser()) {     echo 'You are using a browser.'; } + if ($this->agent->is_browser('Safari')) + { + echo 'You are using Safari.'; + } + else if ($this->agent->is_browser()) + { + echo 'You are using a browser.'; + } + .. note:: The string "Safari" in this example is an array key in the list of browser definitions. You can find this list in @@ -61,7 +90,19 @@ Returns TRUE/FALSE (boolean) if the user agent is a known mobile device. :: - if ($this->agent->is_mobile('iphone')) {     $this->load->view('iphone/home'); } else if ($this->agent->is_mobile()) {     $this->load->view('mobile/home'); } else {     $this->load->view('web/home'); } + if ($this->agent->is_mobile('iphone')) + { + $this->load->view('iphone/home'); + } + else if ($this->agent->is_mobile()) + { + $this->load->view('mobile/home'); + } + else + { + $this->load->view('web/home'); + } + $this->agent->is_robot() ========================= @@ -115,7 +156,10 @@ $this->agent->referrer() The referrer, if the user agent was referred from another site. Typically you'll test for this as follows:: - if ($this->agent->is_referral()) {     echo $this->agent->referrer(); } + if ($this->agent->is_referral()) + { + echo $this->agent->referrer(); + } $this->agent->agent_string() ============================= @@ -131,7 +175,10 @@ $this->agent->accept_lang() Lets you determine if the user agent accepts a particular language. Example:: - if ($this->agent->accept_lang('en')) {     echo 'You accept English!'; } + if ($this->agent->accept_lang('en')) + { + echo 'You accept English!'; + } .. note:: This function is not typically very reliable since some browsers do not provide language info, and even among those that do, it @@ -143,7 +190,10 @@ $this->agent->accept_charset() Lets you determine if the user agent accepts a particular character set. Example:: - if ($this->agent->accept_charset('utf-8')) {     echo 'You browser supports UTF-8!'; } + if ($this->agent->accept_charset('utf-8')) + { + echo 'You browser supports UTF-8!'; + } .. note:: This function is not typically very reliable since some browsers do not provide character-set info, and even among those that -- cgit v1.2.3-24-g4f1b