diff options
Diffstat (limited to 'user_guide_src/source/helpers/url_helper.rst')
| -rw-r--r-- | user_guide_src/source/helpers/url_helper.rst | 450 |
1 files changed, 219 insertions, 231 deletions
diff --git a/user_guide_src/source/helpers/url_helper.rst b/user_guide_src/source/helpers/url_helper.rst index 7a49f188d..3bdcb8e17 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,354 @@ 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: Site URL + :rtype: string -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. + 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. -Segments can be optionally passed to the function as a string or an -array. Here is a string example:: + 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. - echo site_url('news/local/123'); + Segments can be optionally passed to the function as a string or an + array. Here is a string example:: -The above example would return something like: -*http://example.com/index.php/news/local/123* + echo site_url('news/local/123'); -Here is an example of segments passed as an array:: + The above example would return something like: + *http://example.com/index.php/news/local/123* - $segments = array('news', 'local', '123'); - echo site_url($segments); + Here is an example of segments passed as an array:: -This function is an alias for ``CI_Config::site_url()``. For more info, -please see the :doc:`Config Library <../libraries/config>` documentation. + $segments = array('news', 'local', '123'); + echo site_url($segments); -base_url() -=========== + This function is an alias for ``CI_Config::site_url()``. For more info, + please see the :doc:`Config Library <../libraries/config>` documentation. -.. 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: Base URL + :rtype: 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() -============= +.. function:: current_url() -.. php:function:: current_url() + :returns: The current URL + :rtype: string - :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() -============ +.. function:: uri_string() -.. php:function:: uri_string() + :returns: An URI string + :rtype: 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() -============ +.. function:: index_page() -.. php:function:: index_page() + :returns: 'index_page' value + :rtype: mixed - :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 + :returns: HTML hyperlink (anchor tag) + :rtype: 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 + :returns: Pop-up hyperlink + :rtype: 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 + :returns: A "mail to" hyperlink + :rtype: 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. + :returns: A spam-safe "mail to" hyperlink + :rtype: string -auto_link() -=========== + 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. -.. 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 + :returns: Linkified string + :rtype: 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 + :returns: URL-formatted string + :rtype: 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 + :returns: Protocol-prefixed URL string + :rtype: 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 + :rtype: 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 |