summaryrefslogtreecommitdiffstats
path: root/user_guide_src/source/helpers
diff options
context:
space:
mode:
authorDerek Jones <derek.jones@ellislab.com>2013-07-20 01:01:52 +0200
committerDerek Jones <derek.jones@ellislab.com>2013-07-20 01:01:52 +0200
commitabbf518a5ec7c81bf928ced417b7670490f0f0d3 (patch)
treeec1974a8d8a27227926813b4bdb269f80b66eebc /user_guide_src/source/helpers
parent261ba1cfadc13340f169556b7aeba2fd7ac2f570 (diff)
Update URL Helper docs
Diffstat (limited to 'user_guide_src/source/helpers')
-rw-r--r--user_guide_src/source/helpers/url_helper.rst408
1 files changed, 195 insertions, 213 deletions
diff --git a/user_guide_src/source/helpers/url_helper.rst b/user_guide_src/source/helpers/url_helper.rst
index 7a49f188d..24c7e259f 100644
--- a/user_guide_src/source/helpers/url_helper.rst
+++ b/user_guide_src/source/helpers/url_helper.rst
@@ -4,7 +4,12 @@ URL Helper
The URL Helper file contains functions that assist in working with URLs.
-.. contents:: Page Contents
+.. contents::
+ :local:
+
+.. raw:: html
+
+ <div class="custom-index container"></div>
Loading this Helper
===================
@@ -15,371 +20,348 @@ This helper is loaded using the following code::
The following functions are available:
-site_url()
-==========
+Available Functions
+===================
-.. php:function:: site_url($uri = '', $protocol = NULL)
+.. function:: site_url([$uri = ''[, $protocol = NULL]])
:param string $uri: URI string
:param string $protocol: Protocol, e.g. 'http' or 'https'
:returns: string
-Returns your site URL, as specified in your config file. The index.php
-file (or whatever you have set as your site **index_page** in your config
-file) will be added to the URL, as will any URI segments you pass to the
-function, plus the **url_suffix** as set in your config file.
+ Returns your site URL, as specified in your config file. The index.php
+ file (or whatever you have set as your site **index_page** in your config
+ file) will be added to the URL, as will any URI segments you pass to the
+ function, plus the **url_suffix** as set in your config file.
+
+ You are encouraged to use this function any time you need to generate a
+ local URL so that your pages become more portable in the event your URL
+ changes.
-You are encouraged to use this function any time you need to generate a
-local URL so that your pages become more portable in the event your URL
-changes.
+ Segments can be optionally passed to the function as a string or an
+ array. Here is a string example::
-Segments can be optionally passed to the function as a string or an
-array. Here is a string example::
+ echo site_url('news/local/123');
- echo site_url('news/local/123');
+ The above example would return something like:
+ *http://example.com/index.php/news/local/123*
-The above example would return something like:
-*http://example.com/index.php/news/local/123*
+ Here is an example of segments passed as an array::
-Here is an example of segments passed as an array::
+ $segments = array('news', 'local', '123');
+ echo site_url($segments);
- $segments = array('news', 'local', '123');
- echo site_url($segments);
+ This function is an alias for ``CI_Config::site_url()``. For more info,
+ please see the :doc:`Config Library <../libraries/config>` documentation.
-This function is an alias for ``CI_Config::site_url()``. For more info,
-please see the :doc:`Config Library <../libraries/config>` documentation.
-base_url()
-===========
-.. php:function:: base_url($uri = '', $protocol = NULL)
+.. function:: base_url($uri = '', $protocol = NULL)
:param string $uri: URI string
:param string $protocol: Protocol, e.g. 'http' or 'https'
:returns: string
-Returns your site base URL, as specified in your config file. Example::
+ Returns your site base URL, as specified in your config file. Example::
- echo base_url();
+ echo base_url();
-This function returns the same thing as :php:func:`site_url()`, without
-the *index_page* or *url_suffix* being appended.
+ This function returns the same thing as :func:`site_url()`, without
+ the *index_page* or *url_suffix* being appended.
-Also like :php:func:`site_url()`, you can supply segments as a string or
-an array. Here is a string example::
+ Also like :func:`site_url()`, you can supply segments as a string or
+ an array. Here is a string example::
- echo base_url("blog/post/123");
+ echo base_url("blog/post/123");
-The above example would return something like:
-*http://example.com/blog/post/123*
+ The above example would return something like:
+ *http://example.com/blog/post/123*
-This is useful because unlike :php:func:`site_url()`, you can supply a
-string to a file, such as an image or stylesheet. For example::
+ This is useful because unlike :func:`site_url()`, you can supply a
+ string to a file, such as an image or stylesheet. For example::
- echo base_url("images/icons/edit.png");
+ echo base_url("images/icons/edit.png");
-This would give you something like:
-*http://example.com/images/icons/edit.png*
+ This would give you something like:
+ *http://example.com/images/icons/edit.png*
-This function is an alias for ``CI_Config::base_url()``. For more info,
-please see the :doc:`Config Library <../libraries/config>` documentation.
+ This function is an alias for ``CI_Config::base_url()``. For more info,
+ please see the :doc:`Config Library <../libraries/config>` documentation.
-current_url()
-=============
-.. php:function:: current_url()
+.. function:: current_url()
:returns: string
-Returns the full URL (including segments) of the page being currently
-viewed.
+ Returns the full URL (including segments) of the page being currently
+ viewed.
-.. note:: Calling this function is the same as doing this:
- |
- | site_url(uri_string());
+ .. note:: Calling this function is the same as doing this:
+ |
+ | site_url(uri_string());
-uri_string()
-============
-.. php:function:: uri_string()
+.. function:: uri_string()
:returns: string
-Returns the URI segments of any page that contains this function.
-For example, if your URL was this::
+ Returns the URI segments of any page that contains this function.
+ For example, if your URL was this::
- http://some-site.com/blog/comments/123
+ http://some-site.com/blog/comments/123
-The function would return::
+ The function would return::
- blog/comments/123
+ blog/comments/123
-This function is an alias for ``CI_Config::uri_string()``. For more info,
-please see the :doc:`Config Library <../libraries/config>` documentation.
+ This function is an alias for ``CI_Config::uri_string()``. For more info,
+ please see the :doc:`Config Library <../libraries/config>` documentation.
-index_page()
-============
-.. php:function:: index_page()
+.. function:: index_page()
:returns: string
-Returns your site **index_page**, as specified in your config file.
-Example::
+ Returns your site **index_page**, as specified in your config file.
+ Example::
- echo index_page();
+ echo index_page();
-anchor()
-========
-.. php:function:: anchor($uri = '', $title = '', $attributes = '')
+.. function:: anchor($uri = '', $title = '', $attributes = '')
:param string $uri: URI string
:param string $title: Anchor title
:param mixed $attributes: HTML attributes
:returns: string
-Creates a standard HTML anchor link based on your local site URL.
+ Creates a standard HTML anchor link based on your local site URL.
-The first parameter can contain any segments you wish appended to the
-URL. As with the :php:func:`site_url()` function above, segments can
-be a string or an array.
+ The first parameter can contain any segments you wish appended to the
+ URL. As with the :func:`site_url()` function above, segments can
+ be a string or an array.
-.. note:: If you are building links that are internal to your application
- do not include the base URL (http://...). This will be added
- automatically from the information specified in your config file.
- Include only the URI segments you wish appended to the URL.
+ .. note:: If you are building links that are internal to your application
+ do not include the base URL (http://...). This will be added
+ automatically from the information specified in your config file.
+ Include only the URI segments you wish appended to the URL.
-The second segment is the text you would like the link to say. If you
-leave it blank, the URL will be used.
+ The second segment is the text you would like the link to say. If you
+ leave it blank, the URL will be used.
-The third parameter can contain a list of attributes you would like
-added to the link. The attributes can be a simple string or an
-associative array.
+ The third parameter can contain a list of attributes you would like
+ added to the link. The attributes can be a simple string or an
+ associative array.
-Here are some examples::
+ Here are some examples::
- echo anchor('news/local/123', 'My News', 'title="News title"');
- // Prints: <a href="http://example.com/index.php/news/local/123" title="News title">My News</a>
+ echo anchor('news/local/123', 'My News', 'title="News title"');
+ // Prints: <a href="http://example.com/index.php/news/local/123" title="News title">My News</a>
- echo anchor('news/local/123', 'My News', array('title' => 'The best news!'));
- // Prints: <a href="http://example.com/index.php/news/local/123" title="The best news!">My News</a>
+ echo anchor('news/local/123', 'My News', array('title' => 'The best news!'));
+ // Prints: <a href="http://example.com/index.php/news/local/123" title="The best news!">My News</a>
- echo anchor('', 'Click here');
- // Prints: <a href="http://example.com">Click Here</a>
+ echo anchor('', 'Click here');
+ // Prints: <a href="http://example.com">Click Here</a>
-anchor_popup()
-==============
-.. php:function:: anchor_popup($uri = '', $title = '', $attributes = FALSE)
+.. function:: anchor_popup($uri = '', $title = '', $attributes = FALSE)
:param string $uri: URI string
:param string $title: Anchor title
:param mixed $attributes: HTML attributes
:returns: string
-Nearly identical to the :php:func:``anchor()`` function except that it
-opens the URL in a new window. You can specify JavaScript window
-attributes in the third parameter to control how the window is opened.
-If the third parameter is not set it will simply open a new window with
-your own browser settings.
+ Nearly identical to the :func:`anchor()` function except that it
+ opens the URL in a new window. You can specify JavaScript window
+ attributes in the third parameter to control how the window is opened.
+ If the third parameter is not set it will simply open a new window with
+ your own browser settings.
-Here is an example with attributes::
+ Here is an example with attributes::
- $atts = array(
- 'width' => 800,
- 'height' => 600,
- 'scrollbars' => 'yes',
- 'status'      => 'yes',
- 'resizable'   => 'yes',
- 'screenx' => 0,
- 'screeny' => 0,
- 'window_name' => '_blank'
- );
+ $atts = array(
+ 'width' => 800,
+ 'height' => 600,
+ 'scrollbars' => 'yes',
+ 'status'      => 'yes',
+ 'resizable'   => 'yes',
+ 'screenx' => 0,
+ 'screeny' => 0,
+ 'window_name' => '_blank'
+ );
- echo anchor_popup('news/local/123', 'Click Me!', $atts);
+ echo anchor_popup('news/local/123', 'Click Me!', $atts);
-.. note:: The above attributes are the function defaults so you only need to
- set the ones that are different from what you need. If you want the
- function to use all of its defaults simply pass an empty array in the
- third parameter:
- |
- | echo anchor_popup('news/local/123', 'Click Me!', array());
+ .. note:: The above attributes are the function defaults so you only need to
+ set the ones that are different from what you need. If you want the
+ function to use all of its defaults simply pass an empty array in the
+ third parameter:
+ |
+ | echo anchor_popup('news/local/123', 'Click Me!', array());
-.. note:: The **window_name** is not really an attribute, but an argument to
- the JavaScript `window.open() <http://www.w3schools.com/jsref/met_win_open.asp>`
- method, which accepts either a window name or a window target.
+ .. note:: The **window_name** is not really an attribute, but an argument to
+ the JavaScript `window.open() <http://www.w3schools.com/jsref/met_win_open.asp>`
+ method, which accepts either a window name or a window target.
-.. note:: Any other attribute than the listed above will be parsed as an
- HTML attribute to the anchor tag.
+ .. note:: Any other attribute than the listed above will be parsed as an
+ HTML attribute to the anchor tag.
-mailto()
-========
-.. php:function:: mailto($email, $title = '', $attributes = '')
+.. function:: mailto($email, $title = '', $attributes = '')
:param string $email: E-mail address
:param string $title: Anchor title
:param mixed $attributes: HTML attributes
:returns: string
-Creates a standard HTML e-mail link. Usage example::
+ Creates a standard HTML e-mail link. Usage example::
- echo mailto('me@my-site.com', 'Click Here to Contact Me');
+ echo mailto('me@my-site.com', 'Click Here to Contact Me');
-As with the :php:func:`anchor()` tab above, you can set attributes using the
-third parameter::
+ As with the :func:`anchor()` tab above, you can set attributes using the
+ third parameter::
- $attributes = array('title' => 'Mail me');
- echo mailto('me@my-site.com', 'Contact Me', $attributes);
+ $attributes = array('title' => 'Mail me');
+ echo mailto('me@my-site.com', 'Contact Me', $attributes);
-safe_mailto()
-=============
-.. php:function:: safe_mailto($email, $title = '', $attributes = '')
+.. function:: safe_mailto($email, $title = '', $attributes = '')
:param string $email: E-mail address
:param string $title: Anchor title
:param mixed $attributes: HTML attributes
:returns: string
-Identical to the :php:func:`mailto()` function except it writes an obfuscated
-version of the *mailto* tag using ordinal numbers written with JavaScript to
-help prevent the e-mail address from being harvested by spam bots.
+ Identical to the :func:`mailto()` function except it writes an obfuscated
+ version of the *mailto* tag using ordinal numbers written with JavaScript to
+ help prevent the e-mail address from being harvested by spam bots.
-auto_link()
-===========
-.. php:function:: auto_link($str, $type = 'both', $popup = FALSE)
+.. function:: auto_link($str, $type = 'both', $popup = FALSE)
:param string $str: Input string
:param string $type: Link type ('email', 'url' or 'both')
:param bool $popup: Whether to create popup links
:returns: string
-Automatically turns URLs and e-mail addresses contained in a string into
-links. Example::
+ Automatically turns URLs and e-mail addresses contained in a string into
+ links. Example::
- $string = auto_link($string);
+ $string = auto_link($string);
-The second parameter determines whether URLs and e-mails are converted or
-just one or the other. Default behavior is both if the parameter is not
-specified. E-mail links are encoded as :php:func:`safe_mailto()` as shown
-above.
+ The second parameter determines whether URLs and e-mails are converted or
+ just one or the other. Default behavior is both if the parameter is not
+ specified. E-mail links are encoded as :func:`safe_mailto()` as shown
+ above.
-Converts only URLs::
+ Converts only URLs::
- $string = auto_link($string, 'url');
+ $string = auto_link($string, 'url');
-Converts only e-mail addresses::
+ Converts only e-mail addresses::
- $string = auto_link($string, 'email');
+ $string = auto_link($string, 'email');
-The third parameter determines whether links are shown in a new window.
-The value can be TRUE or FALSE (boolean)::
+ The third parameter determines whether links are shown in a new window.
+ The value can be TRUE or FALSE (boolean)::
- $string = auto_link($string, 'both', TRUE);
+ $string = auto_link($string, 'both', TRUE);
-url_title()
-===========
-.. php:function:: url_title($str, $separator = '-', $lowercase = FALSE)
+.. function:: url_title($str, $separator = '-', $lowercase = FALSE)
:param string $str: Input string
:param string $separator: Word separator
:param string $lowercase: Whether to transform the output string to lower-case
:returns: string
-Takes a string as input and creates a human-friendly URL string. This is
-useful if, for example, you have a blog in which you'd like to use the
-title of your entries in the URL. Example::
+ Takes a string as input and creates a human-friendly URL string. This is
+ useful if, for example, you have a blog in which you'd like to use the
+ title of your entries in the URL. Example::
- $title = "What's wrong with CSS?";
- $url_title = url_title($title);
- // Produces: Whats-wrong-with-CSS
+ $title = "What's wrong with CSS?";
+ $url_title = url_title($title);
+ // Produces: Whats-wrong-with-CSS
-The second parameter determines the word delimiter. By default dashes
-are used. Preferred options are: **-** (dash) or **_** (underscore)
+ The second parameter determines the word delimiter. By default dashes
+ are used. Preferred options are: **-** (dash) or **_** (underscore)
-Example::
+ Example::
- $title = "What's wrong with CSS?";
- $url_title = url_title($title, 'underscore');
- // Produces: Whats_wrong_with_CSS
+ $title = "What's wrong with CSS?";
+ $url_title = url_title($title, 'underscore');
+ // Produces: Whats_wrong_with_CSS
-.. note:: Old usage of 'dash' and 'underscore' as the second parameter
- is DEPRECATED.
+ .. note:: Old usage of 'dash' and 'underscore' as the second parameter
+ is DEPRECATED.
-The third parameter determines whether or not lowercase characters are
-forced. By default they are not. Options are boolean TRUE/FALSE.
+ The third parameter determines whether or not lowercase characters are
+ forced. By default they are not. Options are boolean TRUE/FALSE.
-Example::
+ Example::
- $title = "What's wrong with CSS?";
- $url_title = url_title($title, 'underscore', TRUE);
- // Produces: whats_wrong_with_css
+ $title = "What's wrong with CSS?";
+ $url_title = url_title($title, 'underscore', TRUE);
+ // Produces: whats_wrong_with_css
-prep_url()
-----------
-.. php:function:: prep_url($str = '')
+.. function:: prep_url($str = '')
:param string $str: URL string
:returns: string
-This function will add http:// in the event that a protocol prefix
-is missing from a URL.
+ This function will add http:// in the event that a protocol prefix
+ is missing from a URL.
-Pass the URL string to the function like this::
+ Pass the URL string to the function like this::
- $url = prep_url('example.com');
+ $url = prep_url('example.com');
-redirect()
-==========
-.. php:function:: redirect($uri = '', $method = 'auto', $code = NULL)
+.. function:: redirect($uri = '', $method = 'auto', $code = NULL)
:param string $uri: URI string
:param string $method: Redirect method ('auto', 'location' or 'refresh')
:param string $code: HTTP Response code (usually 302 or 303)
:returns: void
-Does a "header redirect" to the URI specified. If you specify the full
-site URL that link will be built, but for local links simply providing
-the URI segments to the controller you want to direct to will create the
-link. The function will build the URL based on your config file values.
+ Does a "header redirect" to the URI specified. If you specify the full
+ site URL that link will be built, but for local links simply providing
+ the URI segments to the controller you want to direct to will create the
+ link. The function will build the URL based on your config file values.
-The optional second parameter allows you to force a particular redirection
-method. The available methods are **auto**, **location** and **refresh**,
-with location being faster but less reliable on IIS servers.
-The default is **auto**, which will attempt to intelligently choose the
-method based on the server environment.
+ The optional second parameter allows you to force a particular redirection
+ method. The available methods are **auto**, **location** and **refresh**,
+ with location being faster but less reliable on IIS servers.
+ The default is **auto**, which will attempt to intelligently choose the
+ method based on the server environment.
-The optional third parameter allows you to send a specific HTTP Response
-Code - this could be used for example to create 301 redirects for search
-engine purposes. The default Response Code is 302. The third parameter is
-*only* available with **location** redirects, and not *refresh*. Examples::
+ The optional third parameter allows you to send a specific HTTP Response
+ Code - this could be used for example to create 301 redirects for search
+ engine purposes. The default Response Code is 302. The third parameter is
+ *only* available with **location** redirects, and not *refresh*. Examples::
- if ($logged_in == FALSE)
- {      
- redirect('/login/form/');
- }
+ if ($logged_in == FALSE)
+ {      
+ redirect('/login/form/');
+ }
- // with 301 redirect
- redirect('/article/13', 'location', 301);
+ // with 301 redirect
+ redirect('/article/13', 'location', 301);
-.. note:: In order for this function to work it must be used before anything
- is outputted to the browser since it utilizes server headers.
+ .. note:: In order for this function to work it must be used before anything
+ is outputted to the browser since it utilizes server headers.
-.. note:: For very fine grained control over headers, you should use the
- `Output Library </libraries/output>` ``set_header()`` method.
+ .. note:: For very fine grained control over headers, you should use the
+ `Output Library </libraries/output>` ``set_header()`` method.
-.. note:: To IIS users: if you hide the `Server` HTTP header, the *auto*
- method won't detect IIS, in that case it is advised you explicitly
- use the **refresh** method.
+ .. note:: To IIS users: if you hide the `Server` HTTP header, the *auto*
+ method won't detect IIS, in that case it is advised you explicitly
+ use the **refresh** method.
-.. note:: When the **location** method is used, an HTTP status code of 303
- will *automatically* be selected when the page is currently accessed
- via POST and HTTP/1.1 is used.
+ .. note:: When the **location** method is used, an HTTP status code of 303
+ will *automatically* be selected when the page is currently accessed
+ via POST and HTTP/1.1 is used.
-.. important:: This function will terminate script execution. \ No newline at end of file
+ .. important:: This function will terminate script execution. \ No newline at end of file