diff options
author | Andrey Andreev <narf@devilix.net> | 2014-02-08 17:18:33 +0100 |
---|---|---|
committer | Andrey Andreev <narf@devilix.net> | 2014-02-08 17:18:33 +0100 |
commit | f733d6db7345ccc5d7ed516fd22ea03cc245cbc4 (patch) | |
tree | 0f5eec61542d5c1142709610f5ccaf3908cf36f5 /user_guide_src/source/helpers | |
parent | 93326a5b1bbaade4d416ad17a768cab27337ec5b (diff) | |
parent | 28c2c975b118016d07212ed8e7c22ff280309f82 (diff) |
Merge branch 'feature/user-guide-cleanup' into develop
Diffstat (limited to 'user_guide_src/source/helpers')
21 files changed, 2173 insertions, 2195 deletions
diff --git a/user_guide_src/source/helpers/array_helper.rst b/user_guide_src/source/helpers/array_helper.rst index 9435b3ac7..4805f581a 100644 --- a/user_guide_src/source/helpers/array_helper.rst +++ b/user_guide_src/source/helpers/array_helper.rst @@ -5,7 +5,12 @@ Array Helper The Array Helper file contains functions that assist in working with arrays. -.. contents:: Page Contents +.. contents:: + :local: + +.. raw:: html + + <div class="custom-index container"></div> Loading this Helper =================== @@ -14,114 +19,115 @@ This helper is loaded using the following code:: $this->load->helper('array'); + +Available Functions +=================== + The following functions are available: -element() -========= -.. php:function:: element($item, $array, $default = NULL) +.. function:: element($item, $array[, $default = NULL]) :param string $item: Item to fetch from the array :param array $array: Input array :param bool $default: What to return if the array isn't valid :returns: NULL on failure or the array item. + :rtype: mixed -Lets you fetch an item from an array. The function tests whether the -array index is set and whether it has a value. If a value exists it is -returned. If a value does not exist it returns NULL, or whatever you've -specified as the default value via the third parameter. + Lets you fetch an item from an array. The function tests whether the + array index is set and whether it has a value. If a value exists it is + returned. If a value does not exist it returns NULL, or whatever you've + specified as the default value via the third parameter. -Example:: + Example:: - $array = array( - 'color' => 'red', - 'shape' => 'round', - 'size' => '' - ); + $array = array( + 'color' => 'red', + 'shape' => 'round', + 'size' => '' + ); - echo element('color', $array); // returns "red" - echo element('size', $array, 'foobar'); // returns "foobar" + echo element('color', $array); // returns "red" + echo element('size', $array, 'foobar'); // returns "foobar" -elements() -========== -.. php:function:: elements($items, $array, $default = NULL) +.. function:: elements($items, $array[, $default = NULL]) :param string $item: Item to fetch from the array :param array $array: Input array :param bool $default: What to return if the array isn't valid :returns: NULL on failure or the array item. + :rtype: mixed -Lets you fetch a number of items from an array. The function tests -whether each of the array indices is set. If an index does not exist it -is set to NULL, or whatever you've specified as the default value via -the third parameter. + Lets you fetch a number of items from an array. The function tests + whether each of the array indices is set. If an index does not exist it + is set to NULL, or whatever you've specified as the default value via + the third parameter. -Example:: + Example:: - $array = array( - 'color' => 'red', - 'shape' => 'round', - 'radius' => '10', - 'diameter' => '20' - ); + $array = array( + 'color' => 'red', + 'shape' => 'round', + 'radius' => '10', + 'diameter' => '20' + ); - $my_shape = elements(array('color', 'shape', 'height'), $array); + $my_shape = elements(array('color', 'shape', 'height'), $array); -The above will return the following array:: + The above will return the following array:: - array( - 'color' => 'red', - 'shape' => 'round', - 'height' => NULL - ); + array( + 'color' => 'red', + 'shape' => 'round', + 'height' => NULL + ); -You can set the third parameter to any default value you like. -:: + You can set the third parameter to any default value you like. + :: - $my_shape = elements(array('color', 'shape', 'height'), $array, 'foobar'); + $my_shape = elements(array('color', 'shape', 'height'), $array, 'foobar'); -The above will return the following array:: + The above will return the following array:: - array( - 'color' => 'red', - 'shape' => 'round', - 'height' => 'foobar' - ); + array( + 'color' => 'red', + 'shape' => 'round', + 'height' => 'foobar' + ); -This is useful when sending the ``$_POST`` array to one of your Models. -This prevents users from sending additional POST data to be entered into -your tables. + This is useful when sending the ``$_POST`` array to one of your Models. + This prevents users from sending additional POST data to be entered into + your tables. -:: + :: - $this->load->model('post_model'); - $this->post_model->update( - elements(array('id', 'title', 'content'), $_POST) - ); + $this->load->model('post_model'); + $this->post_model->update( + elements(array('id', 'title', 'content'), $_POST) + ); -This ensures that only the id, title and content fields are sent to be -updated. + This ensures that only the id, title and content fields are sent to be + updated. -random_element() -================ -.. php:function:: random_element($array) +.. function:: random_element($array) :param array $array: Input array - :returns: string (a random element from the array) + :returns: A random element from the array + :rtype: mixed -Takes an array as input and returns a random element from it. + Takes an array as input and returns a random element from it. -Usage example:: + Usage example:: - $quotes = array( - "I find that the harder I work, the more luck I seem to have. - Thomas Jefferson", - "Don't stay in bed, unless you can make money in bed. - George Burns", - "We didn't lose the game; we just ran out of time. - Vince Lombardi", - "If everything seems under control, you're not going fast enough. - Mario Andretti", - "Reality is merely an illusion, albeit a very persistent one. - Albert Einstein", - "Chance favors the prepared mind - Louis Pasteur" - ); + $quotes = array( + "I find that the harder I work, the more luck I seem to have. - Thomas Jefferson", + "Don't stay in bed, unless you can make money in bed. - George Burns", + "We didn't lose the game; we just ran out of time. - Vince Lombardi", + "If everything seems under control, you're not going fast enough. - Mario Andretti", + "Reality is merely an illusion, albeit a very persistent one. - Albert Einstein", + "Chance favors the prepared mind - Louis Pasteur" + ); - echo random_element($quotes);
\ No newline at end of file + echo random_element($quotes);
\ No newline at end of file diff --git a/user_guide_src/source/helpers/captcha_helper.rst b/user_guide_src/source/helpers/captcha_helper.rst index f47173453..d83490b8e 100644 --- a/user_guide_src/source/helpers/captcha_helper.rst +++ b/user_guide_src/source/helpers/captcha_helper.rst @@ -5,56 +5,24 @@ CAPTCHA Helper The CAPTCHA Helper file contains functions that assist in creating CAPTCHA images. -.. contents:: Page Contents +.. contents:: + :local: + +.. raw:: html + + <div class="custom-index container"></div> Loading this Helper =================== -This helper is loaded using the following code -:: +This helper is loaded using the following code:: $this->load->helper('captcha'); -The following functions are available: - -create_captcha() -================ - -.. php:function:: function create_captcha($data = '', $img_path = '', $img_url = '', $font_path = '') - - :param array $data: Array of data for the CAPTCHA - :param string $img_path: Path to create the image in - :param string $img_url: URL to the CAPTCHA image folder - :param string $font_path: Server path to font - :returns: array - -Takes an array of information to generate the CAPTCHA as input and -creates the image to your specifications, returning an array of -associative data about the image. - -:: - - array( - 'word' => CAPTCHA WORD, - 'time' => TIMESTAMP (in microtime), - 'image' => IMAGE TAG, - 'filename' => IMAGE FILE NAME - ) - -The **image** is the actual image tag:: - - <img src="http://example.com/captcha/12345.jpg" width="140" height="50" /> - -The **time** is the micro timestamp used as the image name without the -file extension. It will be a number like this: 1139612155.3422 - -The **word** is the word that appears in the captcha image, which if not -supplied to the function, will be a random string. - Using the CAPTCHA helper ------------------------- +======================== -Once loaded you can generate a captcha like this:: +Once loaded you can generate a CAPTCHA like this:: $vals = array( 'word' => 'Random word', @@ -133,7 +101,7 @@ CAPTCHA will be shown you'll have something like this:: $this->db->query($query); echo 'Submit the word you see below:'; - echo $cap['image']; + echo $cap['image']; echo '<input type="text" name="captcha" value="" />'; Then, on the page that accepts the submission you'll have something like @@ -153,4 +121,40 @@ this:: if ($row->count == 0) { echo 'You must submit the word that appears in the image.'; - }
\ No newline at end of file + } + +Available Functions +=================== + +The following functions are available: + +.. function:: create_captcha([$data = ''[, $img_path = ''[, $img_url = ''[, $font_path = '']]]]) + + :param array $data: Array of data for the CAPTCHA + :param string $img_path: Path to create the image in + :param string $img_url: URL to the CAPTCHA image folder + :param string $font_path: Server path to font + :returns: array('word' => $word, 'time' => $now, 'image' => $img) + :rtype: array + + Takes an array of information to generate the CAPTCHA as input and + creates the image to your specifications, returning an array of + associative data about the image. + + :: + + array( + 'image' => IMAGE TAG + 'time' => TIMESTAMP (in microtime) + 'word' => CAPTCHA WORD + ) + + The **image** is the actual image tag:: + + <img src="http://example.com/captcha/12345.jpg" width="140" height="50" /> + + The **time** is the micro timestamp used as the image name without the + file extension. It will be a number like this: 1139612155.3422 + + The **word** is the word that appears in the captcha image, which if not + supplied to the function, will be a random string.
\ No newline at end of file diff --git a/user_guide_src/source/helpers/cookie_helper.rst b/user_guide_src/source/helpers/cookie_helper.rst index c41193c3c..22fd0f77f 100644 --- a/user_guide_src/source/helpers/cookie_helper.rst +++ b/user_guide_src/source/helpers/cookie_helper.rst @@ -5,7 +5,12 @@ Cookie Helper The Cookie Helper file contains functions that assist in working with cookies. -.. contents:: Page Contents +.. contents:: + :local: + +.. raw:: html + + <div class="custom-index container"></div> Loading this Helper =================== @@ -14,14 +19,15 @@ This helper is loaded using the following code:: $this->load->helper('cookie'); +Available Functions +=================== + The following functions are available: -set_cookie() -============ -.. php:function:: set_cookie($name = '', $value = '', $expire = '', $domain = '', $path = '/', $prefix = '', $secure = FALSE, $httponly = FALSE) +.. function:: set_cookie($name[, $value = ''[, $expire = ''[, $domain = ''[, $path = '/'[, $prefix = ''[, $secure = FALSE[, $httponly = FALSE]]]]]]]]) - :param string $name: Cookie name + :param mixed $name: Cookie name *or* associative array of all of the parameters available to this function :param string $value: Cookie value :param int $expire: Number of seconds until expiration :param string $domain: Cookie domain (usually: .yourdomain.com) @@ -29,49 +35,44 @@ set_cookie() :param string $prefix: Cookie name prefix :param bool $secure: Whether to only send the cookie through HTTPS :param bool $httponly: Whether to hide the cookie from JavaScript - :returns: void + :rtype: void -This helper function gives you view file friendly syntax to set browser -cookies. Refer to the :doc:`Input Library <../libraries/input>` for a -description of its use, as this function is an alias for -``CI_Input::set_cookie()``. + This helper function gives you view file friendly syntax to set browser + cookies. Refer to the :doc:`Input Library <../libraries/input>` for a + description of its use, as this function is an alias for + ``CI_Input::set_cookie()``. -get_cookie() -============ -.. php:function:: get_cookie($index = '', $xss_clean = FALSE) +.. function:: get_cookie($index[, $xss_clean = NULL]]) :param string $index: Cookie name :param bool $xss_clean: Whether to apply XSS filtering to the returned value - :returns: mixed + :returns: The cookie value or NULL if not found + :rtype: mixed -This helper function gives you view file friendly syntax to get browser -cookies. Refer to the :doc:`Input Library <../libraries/input>` for a -description of itsuse, as this function is an alias for ``CI_Input::cookie()``. + This helper function gives you view file friendly syntax to get browser + cookies. Refer to the :doc:`Input Library <../libraries/input>` for a + description of its use, as this function is an alias for ``CI_Input::cookie()``. -delete_cookie() -=============== -.. php:function:: delete_cookie($name = '', $domain = '', $path = '/', $prefix = '') +.. function:: delete_cookie($name[, $domain = ''[, $path = '/'[, $prefix = '']]]]) :param string $name: Cookie name :param string $domain: Cookie domain (usually: .yourdomain.com) :param string $path: Cookie path :param string $prefix: Cookie name prefix - :returns: void - -Lets you delete a cookie. Unless you've set a custom path or other -values, only the name of the cookie is needed. - -:: + :rtype: void - delete_cookie('name'); + Lets you delete a cookie. Unless you've set a custom path or other + values, only the name of the cookie is needed. + :: -This function is otherwise identical to ``set_cookie()``, except that it -does not have the value and expiration parameters. You can submit an -array of values in the first parameter or you can set discrete -parameters. + delete_cookie('name'); -:: + This function is otherwise identical to ``set_cookie()``, except that it + does not have the value and expiration parameters. You can submit an + array of values in the first parameter or you can set discrete + parameters. + :: - delete_cookie($name, $domain, $path, $prefix)
\ No newline at end of file + delete_cookie($name, $domain, $path, $prefix)
\ No newline at end of file diff --git a/user_guide_src/source/helpers/date_helper.rst b/user_guide_src/source/helpers/date_helper.rst index 8126eba6c..39a9cb325 100644 --- a/user_guide_src/source/helpers/date_helper.rst +++ b/user_guide_src/source/helpers/date_helper.rst @@ -4,7 +4,12 @@ Date Helper The Date Helper file contains functions that help you work with dates. -.. contents:: Page Contents +.. contents:: + :local: + +.. raw:: html + + <div class="custom-index container"></div> Loading this Helper =================== @@ -13,396 +18,368 @@ This helper is loaded using the following code:: $this->load->helper('date'); +Available Functions +=================== + The following functions are available: -now() -===== -.. php:function:: now($timezone = NULL) +.. function:: now([$timezone = NULL]) :param string $timezone: Timezone - :returns: int - -Returns the current time as a UNIX timestamp, referenced either to your server's -local time or any PHP suported timezone, based on the "time reference" setting -in your config file. If you do not intend to set your master time reference to -any other PHP supported timezone (which you'll typically do if you run a site -that lets each user set their own timezone settings) there is no benefit to using -this function over PHP's ``time()`` function. - -:: + :returns: UNIX timestamp + :rtype: int - echo now('Australia/Victoria'); + Returns the current time as a UNIX timestamp, referenced either to your server's + local time or any PHP suported timezone, based on the "time reference" setting + in your config file. If you do not intend to set your master time reference to + any other PHP supported timezone (which you'll typically do if you run a site + that lets each user set their own timezone settings) there is no benefit to using + this function over PHP's ``time()`` function. + :: -If a timezone is not provided, it will return ``time()`` based on the -**time_reference** setting. + echo now('Australia/Victoria'); -mdate() -======= + If a timezone is not provided, it will return ``time()`` based on the + **time_reference** setting. -.. php:function:: mdate($datestr = '', $time = '') +.. function:: mdate([$datestr = ''[, $time = '']]) - :param string $datestr: Date string - :param int $time: UNIX timestamp - :returns: int - -This function is identical to PHP's `date() <http://www.php.net/date>`_ -function, except that it lets you use MySQL style date codes, where each -code letter is preceded with a percent sign, e.g. `%Y %m %d` + :param string $datestr: Date string + :param int $time: UNIX timestamp + :returns: MySQL-formatted date + :rtype: string -The benefit of doing dates this way is that you don't have to worry -about escaping any characters that are not date codes, as you would -normally have to do with the ``date()`` function. + This function is identical to PHP's `date() <http://www.php.net/date>`_ + function, except that it lets you use MySQL style date codes, where each + code letter is preceded with a percent sign, e.g. `%Y %m %d` -Example:: + The benefit of doing dates this way is that you don't have to worry + about escaping any characters that are not date codes, as you would + normally have to do with the ``date()`` function. - $datestring = 'Year: %Y Month: %m Day: %d - %h:%i %a'; - $time = time(); - echo mdate($datestring, $time); + Example:: -If a timestamp is not included in the second parameter the current time -will be used. + $datestring = 'Year: %Y Month: %m Day: %d - %h:%i %a'; + $time = time(); + echo mdate($datestring, $time); -standard_date() -=============== + If a timestamp is not included in the second parameter the current time + will be used. -.. php:function:: standard_date($fmt = 'DATE_RFC822', $time = NULL) +.. function:: standard_date([$fmt = 'DATE_RFC822'[, $time = NULL]]) :param string $fmt: Date format - :param int $time: UNIX timestamp - :returns: string - -Lets you generate a date string in one of several standardized formats. + :param int $time: UNIX timestamp + :returns: Formatted date or FALSE on invalid format + :rtype: string -Example:: + Lets you generate a date string in one of several standardized formats. - $format = 'DATE_RFC822'; - $time = time(); - echo standard_date($format, $time); + Example:: -.. note:: This function is DEPRECATED. Use the native ``date()`` combined with - `DateTime's format constants - <http://www.php.net/manual/en/class.datetime.php#datetime.constants.types>`_ - instead: + $format = 'DATE_RFC822'; + $time = time(); + echo standard_date($format, $time); - | - | echo date(DATE_RFC822, time()); + .. note:: This function is DEPRECATED. Use the native ``date()`` combined with + `DateTime's format constants + <http://www.php.net/manual/en/class.datetime.php#datetime.constants.types>`_ + instead:: -Supported formats ------------------ + echo date(DATE_RFC822, time()); -=============== ======================= ====================================== -Constant Description Example -=============== ======================= ====================================== -DATE_ATOM Atom 2005-08-15T16:13:03+0000 -DATE_COOKIE HTTP Cookies Sun, 14 Aug 2005 16:13:03 UTC -DATE_ISO8601 ISO-8601 2005-08-14T16:13:03+00:00 -DATE_RFC822 RFC 822 Sun, 14 Aug 05 16:13:03 UTC -DATE_RFC850 RFC 850 Sunday, 14-Aug-05 16:13:03 UTC -DATE_RFC1036 RFC 1036 Sunday, 14-Aug-05 16:13:03 UTC -DATE_RFC1123 RFC 1123 Sun, 14 Aug 2005 16:13:03 UTC -DATE_RFC2822 RFC 2822 Sun, 14 Aug 2005 16:13:03 +0000 -DATE_RSS RSS Sun, 14 Aug 2005 16:13:03 UTC -DATE_W3C W3C 2005-08-14T16:13:03+0000 -=============== ======================= ====================================== + **Supported formats:** -local_to_gmt() -============== + =============== ======================= ====================================== + Constant Description Example + =============== ======================= ====================================== + DATE_ATOM Atom 2005-08-15T16:13:03+0000 + DATE_COOKIE HTTP Cookies Sun, 14 Aug 2005 16:13:03 UTC + DATE_ISO8601 ISO-8601 2005-08-14T16:13:03+00:00 + DATE_RFC822 RFC 822 Sun, 14 Aug 05 16:13:03 UTC + DATE_RFC850 RFC 850 Sunday, 14-Aug-05 16:13:03 UTC + DATE_RFC1036 RFC 1036 Sunday, 14-Aug-05 16:13:03 UTC + DATE_RFC1123 RFC 1123 Sun, 14 Aug 2005 16:13:03 UTC + DATE_RFC2822 RFC 2822 Sun, 14 Aug 2005 16:13:03 +0000 + DATE_RSS RSS Sun, 14 Aug 2005 16:13:03 UTC + DATE_W3C W3C 2005-08-14T16:13:03+0000 + =============== ======================= ====================================== -.. php:function:: local_to_gmt($time = '') +.. function:: local_to_gmt([$time = '']) :param int $time: UNIX timestamp - :returns: string + :returns: UNIX timestamp + :rtype: int -Takes a UNIX timestamp as input and returns it as GMT. + Takes a UNIX timestamp as input and returns it as GMT. -Example:: + Example:: - $gmt = local_to_gmt(time()); + $gmt = local_to_gmt(time()); -gmt_to_local() -============== +.. function:: gmt_to_local([$time = ''[, $timezone = 'UTC'[, $dst = FALSE]]]) -.. php:function:: gmt_to_local($time = '', $timezone = 'UTC', $dst = FALSE) - - :param int $time: UNIX timestamp + :param int $time: UNIX timestamp :param string $timezone: Timezone - :param bool $dst: Whether DST is active - :returns: int - -Takes a UNIX timestamp (referenced to GMT) as input, and converts it to -a localized timestamp based on the timezone and Daylight Saving Time -submitted. + :param bool $dst: Whether DST is active + :returns: UNIX timestamp + :rtype: int -Example:: + Takes a UNIX timestamp (referenced to GMT) as input, and converts it to + a localized timestamp based on the timezone and Daylight Saving Time + submitted. - $timestamp = 1140153693; - $timezone = 'UM8'; - $daylight_saving = TRUE; - echo gmt_to_local($timestamp, $timezone, $daylight_saving); + Example:: + $timestamp = 1140153693; + $timezone = 'UM8'; + $daylight_saving = TRUE; + echo gmt_to_local($timestamp, $timezone, $daylight_saving); -.. note:: For a list of timezones see the reference at the bottom of this page. -mysql_to_unix() -=============== + .. note:: For a list of timezones see the reference at the bottom of this page. -.. php:function:: mysql_to_unix($time = '') +.. function:: mysql_to_unix([$time = '']) - :param int $time: UNIX timestamp - :returns: int + :param string $time: MySQL timestamp + :returns: UNIX timestamp + :rtype: int -Takes a MySQL Timestamp as input and returns it as a UNIX timestamp. + Takes a MySQL Timestamp as input and returns it as a UNIX timestamp. -Example:: + Example:: - $unix = mysql_to_unix('20061124092345'); + $unix = mysql_to_unix('20061124092345'); -unix_to_human() -=============== - -.. php:function:: unix_to_human($time = '', $seconds = FALSE, $fmt = 'us') +.. function:: unix_to_human([$time = ''[, $seconds = FALSE[, $fmt = 'us']]]) :param int $time: UNIX timestamp :param bool $seconds: Whether to show seconds :param string $fmt: format (us or euro) - :returns: integer - -Takes a UNIX timestamp as input and returns it in a human readable -format with this prototype:: + :returns: Formatted date + :rtype: string - YYYY-MM-DD HH:MM:SS AM/PM + Takes a UNIX timestamp as input and returns it in a human readable + format with this prototype:: -This can be useful if you need to display a date in a form field for -submission. + YYYY-MM-DD HH:MM:SS AM/PM -The time can be formatted with or without seconds, and it can be set to -European or US format. If only the timestamp is submitted it will return -the time without seconds formatted for the U.S. + This can be useful if you need to display a date in a form field for + submission. -Examples:: + The time can be formatted with or without seconds, and it can be set to + European or US format. If only the timestamp is submitted it will return + the time without seconds formatted for the U.S. - $now = time(); - echo unix_to_human($now); // U.S. time, no seconds - echo unix_to_human($now, TRUE, 'us'); // U.S. time with seconds - echo unix_to_human($now, TRUE, 'eu'); // Euro time with seconds + Examples:: -human_to_unix() -=============== + $now = time(); + echo unix_to_human($now); // U.S. time, no seconds + echo unix_to_human($now, TRUE, 'us'); // U.S. time with seconds + echo unix_to_human($now, TRUE, 'eu'); // Euro time with seconds -.. php:function:: human_to_unix($datestr = '') +.. function:: human_to_unix([$datestr = '']) - :param int $datestr: Date string - :returns: int UNIX timestamp or FALSE on failure + :param int $datestr: Date string + :returns: UNIX timestamp or FALSE on failure + :rtype: int -The opposite of the :php:func:`unix_to_time()` function. Takes a "human" -time as input and returns it as a UNIX timestamp. This is useful if you -accept "human" formatted dates submitted via a form. Returns boolean FALSE -date string passed to it is not formatted as indicated above. + The opposite of the :func:`unix_to_time()` function. Takes a "human" + time as input and returns it as a UNIX timestamp. This is useful if you + accept "human" formatted dates submitted via a form. Returns boolean FALSE + date string passed to it is not formatted as indicated above. -Example:: + Example:: - $now = time(); - $human = unix_to_human($now); - $unix = human_to_unix($human); + $now = time(); + $human = unix_to_human($now); + $unix = human_to_unix($human); -nice_date() -=========== - -.. php:function:: nice_date($bad_date = '', $format = FALSE) +.. function:: nice_date([$bad_date = ''[, $format = FALSE]]) :param int $bad_date: The terribly formatted date-like string :param string $format: Date format to return (same as PHP's ``date()`` function) - :returns: string - -This function can take a number poorly-formed date formats and convert -them into something useful. It also accepts well-formed dates. + :returns: Formatted date + :rtype: string -The function will return a UNIX timestamp by default. You can, optionally, -pass a format string (the same type as the PHP ``date()`` function accepts) -as the second parameter. + This function can take a number poorly-formed date formats and convert + them into something useful. It also accepts well-formed dates. -Example:: + The function will return a UNIX timestamp by default. You can, optionally, + pass a format string (the same type as the PHP ``date()`` function accepts) + as the second parameter. - $bad_date = '199605'; - // Should Produce: 1996-05-01 - $better_date = nice_date($bad_date, 'Y-m-d'); + Example:: - $bad_date = '9-11-2001'; - // Should Produce: 2001-09-11 - $better_date = nice_date($bad_date, 'Y-m-d'); + $bad_date = '199605'; + // Should Produce: 1996-05-01 + $better_date = nice_date($bad_date, 'Y-m-d'); -timespan() -========== + $bad_date = '9-11-2001'; + // Should Produce: 2001-09-11 + $better_date = nice_date($bad_date, 'Y-m-d'); -.. php:function:: timespan($seconds = 1, $time = '', $units = '') +.. function:: timespan([$seconds = 1[, $time = ''[, $units = '']]]) :param int $seconds: Number of seconds :param string $time: UNIX timestamp :param int $units: Number of time units to display - :returns: string + :returns: Formatted time difference + :rtype: string -Formats a UNIX timestamp so that is appears similar to this:: + Formats a UNIX timestamp so that is appears similar to this:: - 1 Year, 10 Months, 2 Weeks, 5 Days, 10 Hours, 16 Minutes + 1 Year, 10 Months, 2 Weeks, 5 Days, 10 Hours, 16 Minutes -The first parameter must contain a UNIX timestamp. -The second parameter must contain a timestamp that is greater that the -first timestamp. -The thirdparameter is optional and limits the number of time units to display. + The first parameter must contain a UNIX timestamp. + The second parameter must contain a timestamp that is greater that the + first timestamp. + The thirdparameter is optional and limits the number of time units to display. -If the second parameter empty, the current time will be used. + If the second parameter empty, the current time will be used. -The most common purpose for this function is to show how much time has -elapsed from some point in time in the past to now. + The most common purpose for this function is to show how much time has + elapsed from some point in time in the past to now. -Example:: + Example:: - $post_date = '1079621429'; - $now = time(); - $units = 2; - echo timespan($post_date, $now, $units); + $post_date = '1079621429'; + $now = time(); + $units = 2; + echo timespan($post_date, $now, $units); -.. note:: The text generated by this function is found in the following language - file: `language/<your_lang>/date_lang.php` + .. note:: The text generated by this function is found in the following language + file: `language/<your_lang>/date_lang.php` -days_in_month() -=============== - -.. php:function:: days_in_month($month = 0, $year = '') +.. function:: days_in_month([$month = 0[, $year = '']]) :param int $month: a numeric month :param int $year: a numeric year - :returns: int - -Returns the number of days in a given month/year. Takes leap years into -account. + :returns: Count of days in the specified month + :rtype: int -Example:: + Returns the number of days in a given month/year. Takes leap years into + account. - echo days_in_month(06, 2005); + Example:: -If the second parameter is empty, the current year will be used. + echo days_in_month(06, 2005); -date_range() -============ + If the second parameter is empty, the current year will be used. -.. php:function:: date_range($unix_start = '', $mixed = '', $is_unix = TRUE, $format = 'Y-m-d') +.. function:: date_range([$unix_start = ''[, $mixed = ''[, $is_unix = TRUE[, $format = 'Y-m-d']]]]) :param int $unix_start: UNIX timestamp of the range start date :param int $mixed: UNIX timestamp of the range end date or interval in days :param bool $is_unix: set to FALSE if $mixed is not a timestamp :param string $format: Output date format, same as in ``date()`` - :returns: array - -Returns a list of dates within a specified period. + :returns: An array of dates + :rtype: array -Example:: + Returns a list of dates within a specified period. - $range = date_range('2012-01-01', '2012-01-15'); - echo "First 15 days of 2012:"; - foreach ($range as $date) - { - echo $date."\n"; - } + Example:: -timezones() -=========== + $range = date_range('2012-01-01', '2012-01-15'); + echo "First 15 days of 2012:"; + foreach ($range as $date) + { + echo $date."\n"; + } -.. php:function:: timezones($tz = '') +.. function:: timezones([$tz = '']) - :param string $tz: a numeric timezone - :returns: string + :param string $tz: A numeric timezone + :returns: Hour difference from UTC + :rtype: int -Takes a timezone reference (for a list of valid timezones, see the -"Timezone Reference" below) and returns the number of hours offset from -UTC. + Takes a timezone reference (for a list of valid timezones, see the + "Timezone Reference" below) and returns the number of hours offset from + UTC. -Example:: + Example:: - echo timezones('UM5'); + echo timezones('UM5'); -This function is useful when used with :php:func:`timezone_menu()`. + This function is useful when used with :func:`timezone_menu()`. -timezone_menu() -=============== - -.. php:function:: timezone_menu($default = 'UTC', $class = '', $name = 'timezones', $attributes = '') +.. function:: timezone_menu([$default = 'UTC'[, $class = ''[, $name = 'timezones'[, $attributes = '']]]]) :param string $default: Timezone :param string $class: Class name :param string $name: Menu name :param mixed $attributes: HTML attributes - :returns: string - -Generates a pull-down menu of timezones, like this one: - -.. raw:: html - - <form action="#"> - <select name="timezones"> - <option value='UM12'>(UTC -12:00) Baker/Howland Island</option> - <option value='UM11'>(UTC -11:00) Samoa Time Zone, Niue</option> - <option value='UM10'>(UTC -10:00) Hawaii-Aleutian Standard Time, Cook Islands, Tahiti</option> - <option value='UM95'>(UTC -9:30) Marquesas Islands</option> - <option value='UM9'>(UTC -9:00) Alaska Standard Time, Gambier Islands</option> - <option value='UM8'>(UTC -8:00) Pacific Standard Time, Clipperton Island</option> - <option value='UM7'>(UTC -7:00) Mountain Standard Time</option> - <option value='UM6'>(UTC -6:00) Central Standard Time</option> - <option value='UM5'>(UTC -5:00) Eastern Standard Time, Western Caribbean Standard Time</option> - <option value='UM45'>(UTC -4:30) Venezuelan Standard Time</option> - <option value='UM4'>(UTC -4:00) Atlantic Standard Time, Eastern Caribbean Standard Time</option> - <option value='UM35'>(UTC -3:30) Newfoundland Standard Time</option> - <option value='UM3'>(UTC -3:00) Argentina, Brazil, French Guiana, Uruguay</option> - <option value='UM2'>(UTC -2:00) South Georgia/South Sandwich Islands</option> - <option value='UM1'>(UTC -1:00) Azores, Cape Verde Islands</option> - <option value='UTC' selected='selected'>(UTC) Greenwich Mean Time, Western European Time</option> - <option value='UP1'>(UTC +1:00) Central European Time, West Africa Time</option> - <option value='UP2'>(UTC +2:00) Central Africa Time, Eastern European Time, Kaliningrad Time</option> - <option value='UP3'>(UTC +3:00) Moscow Time, East Africa Time</option> - <option value='UP35'>(UTC +3:30) Iran Standard Time</option> - <option value='UP4'>(UTC +4:00) Azerbaijan Standard Time, Samara Time</option> - <option value='UP45'>(UTC +4:30) Afghanistan</option> - <option value='UP5'>(UTC +5:00) Pakistan Standard Time, Yekaterinburg Time</option> - <option value='UP55'>(UTC +5:30) Indian Standard Time, Sri Lanka Time</option> - <option value='UP575'>(UTC +5:45) Nepal Time</option> - <option value='UP6'>(UTC +6:00) Bangladesh Standard Time, Bhutan Time, Omsk Time</option> - <option value='UP65'>(UTC +6:30) Cocos Islands, Myanmar</option> - <option value='UP7'>(UTC +7:00) Krasnoyarsk Time, Cambodia, Laos, Thailand, Vietnam</option> - <option value='UP8'>(UTC +8:00) Australian Western Standard Time, Beijing Time, Irkutsk Time</option> - <option value='UP875'>(UTC +8:45) Australian Central Western Standard Time</option> - <option value='UP9'>(UTC +9:00) Japan Standard Time, Korea Standard Time, Yakutsk Time</option> - <option value='UP95'>(UTC +9:30) Australian Central Standard Time</option> - <option value='UP10'>(UTC +10:00) Australian Eastern Standard Time, Vladivostok Time</option> - <option value='UP105'>(UTC +10:30) Lord Howe Island</option> - <option value='UP11'>(UTC +11:00) Magadan Time, Solomon Islands, Vanuatu</option> - <option value='UP115'>(UTC +11:30) Norfolk Island</option> - <option value='UP12'>(UTC +12:00) Fiji, Gilbert Islands, Kamchatka Time, New Zealand Standard Time</option> - <option value='UP1275'>(UTC +12:45) Chatham Islands Standard Time</option> - <option value='UP13'>(UTC +13:00) Phoenix Islands Time, Tonga</option> - <option value='UP14'>(UTC +14:00) Line Islands</option> - </select> - </form> - - -This menu is useful if you run a membership site in which your users are -allowed to set their local timezone value. - -The first parameter lets you set the "selected" state of the menu. For -example, to set Pacific time as the default you will do this:: - - echo timezone_menu('UM8'); - -Please see the timezone reference below to see the values of this menu. - -The second parameter lets you set a CSS class name for the menu. - -The fourth parameter lets you set one or more attributes on the generated select tag. - -.. note:: The text contained in the menu is found in the following - language file: `language/<your_lang>/date_lang.php` - + :returns: HTML drop down menu with time zones + :rtype: string + + Generates a pull-down menu of timezones, like this one: + + .. raw:: html + + <form action="#"> + <select name="timezones"> + <option value='UM12'>(UTC -12:00) Baker/Howland Island</option> + <option value='UM11'>(UTC -11:00) Samoa Time Zone, Niue</option> + <option value='UM10'>(UTC -10:00) Hawaii-Aleutian Standard Time, Cook Islands, Tahiti</option> + <option value='UM95'>(UTC -9:30) Marquesas Islands</option> + <option value='UM9'>(UTC -9:00) Alaska Standard Time, Gambier Islands</option> + <option value='UM8'>(UTC -8:00) Pacific Standard Time, Clipperton Island</option> + <option value='UM7'>(UTC -7:00) Mountain Standard Time</option> + <option value='UM6'>(UTC -6:00) Central Standard Time</option> + <option value='UM5'>(UTC -5:00) Eastern Standard Time, Western Caribbean Standard Time</option> + <option value='UM45'>(UTC -4:30) Venezuelan Standard Time</option> + <option value='UM4'>(UTC -4:00) Atlantic Standard Time, Eastern Caribbean Standard Time</option> + <option value='UM35'>(UTC -3:30) Newfoundland Standard Time</option> + <option value='UM3'>(UTC -3:00) Argentina, Brazil, French Guiana, Uruguay</option> + <option value='UM2'>(UTC -2:00) South Georgia/South Sandwich Islands</option> + <option value='UM1'>(UTC -1:00) Azores, Cape Verde Islands</option> + <option value='UTC' selected='selected'>(UTC) Greenwich Mean Time, Western European Time</option> + <option value='UP1'>(UTC +1:00) Central European Time, West Africa Time</option> + <option value='UP2'>(UTC +2:00) Central Africa Time, Eastern European Time, Kaliningrad Time</option> + <option value='UP3'>(UTC +3:00) Moscow Time, East Africa Time</option> + <option value='UP35'>(UTC +3:30) Iran Standard Time</option> + <option value='UP4'>(UTC +4:00) Azerbaijan Standard Time, Samara Time</option> + <option value='UP45'>(UTC +4:30) Afghanistan</option> + <option value='UP5'>(UTC +5:00) Pakistan Standard Time, Yekaterinburg Time</option> + <option value='UP55'>(UTC +5:30) Indian Standard Time, Sri Lanka Time</option> + <option value='UP575'>(UTC +5:45) Nepal Time</option> + <option value='UP6'>(UTC +6:00) Bangladesh Standard Time, Bhutan Time, Omsk Time</option> + <option value='UP65'>(UTC +6:30) Cocos Islands, Myanmar</option> + <option value='UP7'>(UTC +7:00) Krasnoyarsk Time, Cambodia, Laos, Thailand, Vietnam</option> + <option value='UP8'>(UTC +8:00) Australian Western Standard Time, Beijing Time, Irkutsk Time</option> + <option value='UP875'>(UTC +8:45) Australian Central Western Standard Time</option> + <option value='UP9'>(UTC +9:00) Japan Standard Time, Korea Standard Time, Yakutsk Time</option> + <option value='UP95'>(UTC +9:30) Australian Central Standard Time</option> + <option value='UP10'>(UTC +10:00) Australian Eastern Standard Time, Vladivostok Time</option> + <option value='UP105'>(UTC +10:30) Lord Howe Island</option> + <option value='UP11'>(UTC +11:00) Magadan Time, Solomon Islands, Vanuatu</option> + <option value='UP115'>(UTC +11:30) Norfolk Island</option> + <option value='UP12'>(UTC +12:00) Fiji, Gilbert Islands, Kamchatka Time, New Zealand Standard Time</option> + <option value='UP1275'>(UTC +12:45) Chatham Islands Standard Time</option> + <option value='UP13'>(UTC +13:00) Phoenix Islands Time, Tonga</option> + <option value='UP14'>(UTC +14:00) Line Islands</option> + </select> + </form> + + + This menu is useful if you run a membership site in which your users are + allowed to set their local timezone value. + + The first parameter lets you set the "selected" state of the menu. For + example, to set Pacific time as the default you will do this:: + + echo timezone_menu('UM8'); + + Please see the timezone reference below to see the values of this menu. + + The second parameter lets you set a CSS class name for the menu. + + The fourth parameter lets you set one or more attributes on the generated select tag. + + .. note:: The text contained in the menu is found in the following + language file: `language/<your_lang>/date_lang.php` Timezone Reference ================== @@ -411,47 +388,47 @@ The following table indicates each timezone and its location. Note some of the location lists have been abridged for clarity and formatting. -=========== ===================================================================== -Time Zone Location -=========== ===================================================================== -UM12 (UTC - 12:00) Baker/Howland Island -UM11 (UTC - 11:00) Samoa Time Zone, Niue -UM10 (UTC - 10:00) Hawaii-Aleutian Standard Time, Cook Islands -UM95 (UTC - 09:30) Marquesas Islands -UM9 (UTC - 09:00) Alaska Standard Time, Gambier Islands -UM8 (UTC - 08:00) Pacific Standard Time, Clipperton Island -UM7 (UTC - 11:00) Mountain Standard Time -UM6 (UTC - 06:00) Central Standard Time -UM5 (UTC - 05:00) Eastern Standard Time, Western Caribbean -UM45 (UTC - 04:30) Venezuelan Standard Time -UM4 (UTC - 04:00) Atlantic Standard Time, Eastern Caribbean -UM35 (UTC - 03:30) Newfoundland Standard Time -UM3 (UTC - 03:00) Argentina, Brazil, French Guiana, Uruguay -UM2 (UTC - 02:00) South Georgia/South Sandwich Islands -UM1 (UTC -1:00) Azores, Cape Verde Islands -UTC (UTC) Greenwich Mean Time, Western European Time -UP1 (UTC +1:00) Central European Time, West Africa Time -UP2 (UTC +2:00) Central Africa Time, Eastern European Time -UP3 (UTC +3:00) Moscow Time, East Africa Time -UP35 (UTC +3:30) Iran Standard Time -UP4 (UTC +4:00) Azerbaijan Standard Time, Samara Time -UP45 (UTC +4:30) Afghanistan -UP5 (UTC +5:00) Pakistan Standard Time, Yekaterinburg Time -UP55 (UTC +5:30) Indian Standard Time, Sri Lanka Time -UP575 (UTC +5:45) Nepal Time -UP6 (UTC +6:00) Bangladesh Standard Time, Bhutan Time, Omsk Time -UP65 (UTC +6:30) Cocos Islands, Myanmar -UP7 (UTC +7:00) Krasnoyarsk Time, Cambodia, Laos, Thailand, Vietnam -UP8 (UTC +8:00) Australian Western Standard Time, Beijing Time -UP875 (UTC +8:45) Australian Central Western Standard Time -UP9 (UTC +9:00) Japan Standard Time, Korea Standard Time, Yakutsk -UP95 (UTC +9:30) Australian Central Standard Time -UP10 (UTC +10:00) Australian Eastern Standard Time, Vladivostok Time -UP105 (UTC +10:30) Lord Howe Island -UP11 (UTC +11:00) Magadan Time, Solomon Islands, Vanuatu -UP115 (UTC +11:30) Norfolk Island -UP12 (UTC +12:00) Fiji, Gilbert Islands, Kamchatka, New Zealand -UP1275 (UTC +12:45) Chatham Islands Standard Time -UP13 (UTC +13:00) Phoenix Islands Time, Tonga -UP14 (UTC +14:00) Line Islands +=========== ===================================================================== +Time Zone Location +=========== ===================================================================== +UM12 (UTC - 12:00) Baker/Howland Island +UM11 (UTC - 11:00) Samoa Time Zone, Niue +UM10 (UTC - 10:00) Hawaii-Aleutian Standard Time, Cook Islands +UM95 (UTC - 09:30) Marquesas Islands +UM9 (UTC - 09:00) Alaska Standard Time, Gambier Islands +UM8 (UTC - 08:00) Pacific Standard Time, Clipperton Island +UM7 (UTC - 11:00) Mountain Standard Time +UM6 (UTC - 06:00) Central Standard Time +UM5 (UTC - 05:00) Eastern Standard Time, Western Caribbean +UM45 (UTC - 04:30) Venezuelan Standard Time +UM4 (UTC - 04:00) Atlantic Standard Time, Eastern Caribbean +UM35 (UTC - 03:30) Newfoundland Standard Time +UM3 (UTC - 03:00) Argentina, Brazil, French Guiana, Uruguay +UM2 (UTC - 02:00) South Georgia/South Sandwich Islands +UM1 (UTC -1:00) Azores, Cape Verde Islands +UTC (UTC) Greenwich Mean Time, Western European Time +UP1 (UTC +1:00) Central European Time, West Africa Time +UP2 (UTC +2:00) Central Africa Time, Eastern European Time +UP3 (UTC +3:00) Moscow Time, East Africa Time +UP35 (UTC +3:30) Iran Standard Time +UP4 (UTC +4:00) Azerbaijan Standard Time, Samara Time +UP45 (UTC +4:30) Afghanistan +UP5 (UTC +5:00) Pakistan Standard Time, Yekaterinburg Time +UP55 (UTC +5:30) Indian Standard Time, Sri Lanka Time +UP575 (UTC +5:45) Nepal Time +UP6 (UTC +6:00) Bangladesh Standard Time, Bhutan Time, Omsk Time +UP65 (UTC +6:30) Cocos Islands, Myanmar +UP7 (UTC +7:00) Krasnoyarsk Time, Cambodia, Laos, Thailand, Vietnam +UP8 (UTC +8:00) Australian Western Standard Time, Beijing Time +UP875 (UTC +8:45) Australian Central Western Standard Time +UP9 (UTC +9:00) Japan Standard Time, Korea Standard Time, Yakutsk +UP95 (UTC +9:30) Australian Central Standard Time +UP10 (UTC +10:00) Australian Eastern Standard Time, Vladivostok Time +UP105 (UTC +10:30) Lord Howe Island +UP11 (UTC +11:00) Magadan Time, Solomon Islands, Vanuatu +UP115 (UTC +11:30) Norfolk Island +UP12 (UTC +12:00) Fiji, Gilbert Islands, Kamchatka, New Zealand +UP1275 (UTC +12:45) Chatham Islands Standard Time +UP13 (UTC +13:00) Phoenix Islands Time, Tonga +UP14 (UTC +14:00) Line Islands =========== =====================================================================
\ No newline at end of file diff --git a/user_guide_src/source/helpers/directory_helper.rst b/user_guide_src/source/helpers/directory_helper.rst index a785ebc8c..3004316a8 100644 --- a/user_guide_src/source/helpers/directory_helper.rst +++ b/user_guide_src/source/helpers/directory_helper.rst @@ -5,7 +5,12 @@ Directory Helper The Directory Helper file contains functions that assist in working with directories. -.. contents:: Page Contents +.. contents:: + :local: + +.. raw:: html + + <div class="custom-index container"></div> Loading this Helper =================== @@ -16,64 +21,63 @@ This helper is loaded using the following code $this->load->helper('directory'); +Available Functions +=================== + The following functions are available: -directory_map() -=============== - -This function reads the directory path specified in the first parameter -and builds an array representation of it and all its contained files. - -.. php:method:: directory_map($source_dir[, $directory_depth = 0[, $hidden = FALSE]]) - - :param string $source_dir: path to the ource directory - :param integer $directory_depth: depth of directories to traverse (0 = - fully recursive, 1 = current dir, etc) - :param boolean $hidden: whether to include hidden directories - -Examples:: - - $map = directory_map('./mydirectory/'); - -.. note:: Paths are almost always relative to your main index.php file. - - -Sub-folders contained within the directory will be mapped as well. If -you wish to control the recursion depth, you can do so using the second -parameter (integer). A depth of 1 will only map the top level directory:: - - $map = directory_map('./mydirectory/', 1); - -By default, hidden files will not be included in the returned array. To -override this behavior, you may set a third parameter to true (boolean):: - - $map = directory_map('./mydirectory/', FALSE, TRUE); - -Each folder name will be an array index, while its contained files will -be numerically indexed. Here is an example of a typical array:: - - Array ( - [libraries] => Array - ( - [0] => benchmark.html - [1] => config.html - ["database/"] => Array - ( - [0] => query_builder.html - [1] => binds.html - [2] => configuration.html - [3] => connecting.html - [4] => examples.html - [5] => fields.html - [6] => index.html - [7] => queries.html - ) - [2] => email.html - [3] => file_uploading.html - [4] => image_lib.html - [5] => input.html - [6] => language.html - [7] => loader.html - [8] => pagination.html - [9] => uri.html - )
\ No newline at end of file + +.. function:: directory_map($source_dir[, $directory_depth = 0[, $hidden = FALSE]]) + + :param string $source_dir: Path to the ource directory + :param int $directory_depth: Depth of directories to traverse (0 = fully recursive, 1 = current dir, etc) + :param bool $hidden: Whether to include hidden directories + :returns: An array of files + :rtype: array + + Examples:: + + $map = directory_map('./mydirectory/'); + + .. note:: Paths are almost always relative to your main index.php file. + + + Sub-folders contained within the directory will be mapped as well. If + you wish to control the recursion depth, you can do so using the second + parameter (integer). A depth of 1 will only map the top level directory:: + + $map = directory_map('./mydirectory/', 1); + + By default, hidden files will not be included in the returned array. To + override this behavior, you may set a third parameter to true (boolean):: + + $map = directory_map('./mydirectory/', FALSE, TRUE); + + Each folder name will be an array index, while its contained files will + be numerically indexed. Here is an example of a typical array:: + + Array ( + [libraries] => Array + ( + [0] => benchmark.html + [1] => config.html + ["database/"] => Array + ( + [0] => query_builder.html + [1] => binds.html + [2] => configuration.html + [3] => connecting.html + [4] => examples.html + [5] => fields.html + [6] => index.html + [7] => queries.html + ) + [2] => email.html + [3] => file_uploading.html + [4] => image_lib.html + [5] => input.html + [6] => language.html + [7] => loader.html + [8] => pagination.html + [9] => uri.html + )
\ No newline at end of file diff --git a/user_guide_src/source/helpers/download_helper.rst b/user_guide_src/source/helpers/download_helper.rst index 860c568b9..f374d491f 100644 --- a/user_guide_src/source/helpers/download_helper.rst +++ b/user_guide_src/source/helpers/download_helper.rst @@ -4,7 +4,12 @@ Download Helper The Download Helper lets you download data to your desktop. -.. contents:: Page Contents +.. contents:: + :local: + +.. raw:: html + + <div class="custom-index container"></div> Loading this Helper =================== @@ -13,38 +18,39 @@ This helper is loaded using the following code:: $this->load->helper('download'); +Available Functions +=================== + The following functions are available: -force_download() -================ -.. php:function:: force_download($filename = '', $data = '', $set_mime = FALSE) +.. function:: force_download([$filename = ''[, $data = ''[, $set_mime = FALSE]]]) :param string $filename: Filename :param mixed $data: File contents :param bool $set_mime: Whether to try to send the actual MIME type - :returns: void + :rtype: void -Generates server headers which force data to be downloaded to your -desktop. Useful with file downloads. The first parameter is the **name -you want the downloaded file to be named**, the second parameter is the -file data. + Generates server headers which force data to be downloaded to your + desktop. Useful with file downloads. The first parameter is the **name + you want the downloaded file to be named**, the second parameter is the + file data. -If you set the second parameter to NULL and ``$filename`` is an existing, readable -file path, then its content will be read instead. + If you set the second parameter to NULL and ``$filename`` is an existing, readable + file path, then its content will be read instead. -If you set the third parameter to boolean TRUE, then the actual file MIME type -(based on the filename extension) will be sent, so that if your browser has a -handler for that type - it can use it. + If you set the third parameter to boolean TRUE, then the actual file MIME type + (based on the filename extension) will be sent, so that if your browser has a + handler for that type - it can use it. -Example:: + Example:: - $data = 'Here is some text!'; - $name = 'mytext.txt'; - force_download($name, $data); + $data = 'Here is some text!'; + $name = 'mytext.txt'; + force_download($name, $data); -If you want to download an existing file from your server you'll need to -do the following:: + If you want to download an existing file from your server you'll need to + do the following:: - // Contents of photo.jpg will be automatically read - force_download('/path/to/photo.jpg', NULL);
\ No newline at end of file + // Contents of photo.jpg will be automatically read + force_download('/path/to/photo.jpg', NULL);
\ No newline at end of file diff --git a/user_guide_src/source/helpers/email_helper.rst b/user_guide_src/source/helpers/email_helper.rst index 10adf1d0e..b665ce548 100644 --- a/user_guide_src/source/helpers/email_helper.rst +++ b/user_guide_src/source/helpers/email_helper.rst @@ -6,9 +6,14 @@ The Email Helper provides some assistive functions for working with Email. For a more robust email solution, see CodeIgniter's :doc:`Email Class <../libraries/email>`. -.. contents:: Page Contents +.. important:: The Email helper is **deprecated**. -.. important:: The Email helper is DEPRECATED. +.. contents:: + :local: + +.. raw:: html + + <div class="custom-index container"></div> Loading this Helper =================== @@ -17,51 +22,53 @@ This helper is loaded using the following code:: $this->load->helper('email'); +Available Functions +=================== + The following functions are available: -valid_email() -============= -.. php:function:: valid_email($email) +.. function:: valid_email($email) - :param string $email: Email address - :returns: bool + :param string $email: E-mail address + :returns: TRUE if a valid email is supplied, FALSE otherwise + :rtype: bool -Checks if the input is a correctly formatted e-mail address. Note that is -doesn't actually prove that the address will be able recieve mail, but -simply that it is a validly formed address. + Checks if the input is a correctly formatted e-mail address. Note that is + doesn't actually prove that the address will be able recieve mail, but + simply that it is a validly formed address. -Example:: + Example:: - if (valid_email('email@somesite.com')) - { - echo 'email is valid'; - } - else - { - echo 'email is not valid'; - } + if (valid_email('email@somesite.com')) + { + echo 'email is valid'; + } + else + { + echo 'email is not valid'; + } -.. note:: All that this function does is to use PHP's native ``filter_var()``: - | - | (bool) filter_var($email, FILTER_VALIDATE_EMAIL); + .. note:: All that this function does is to use PHP's native ``filter_var()``:: -send_email() -============ + (bool) filter_var($email, FILTER_VALIDATE_EMAIL); -.. php:function:: send_email($recipient, $subject, $message) +.. function:: send_email($recipient, $subject, $message) :param string $recipient: E-mail address :param string $subject: Mail subject :param string $message: Message body - :returns: bool + :returns: TRUE if the mail was successfully sent, FALSE in case of an error + :rtype: bool + + Sends an email using PHP's native `mail() <http://www.php.net/function.mail>`_ + function. + + .. note:: All that this function does is to use PHP's native ``mail`` -Sends an email using PHP's native `mail() <http://www.php.net/function.mail>`_ -function. + :: -.. note:: All that this function does is to use PHP's native ``mail``: - | - | mail($recipient, $subject, $message); + mail($recipient, $subject, $message); -For a more robust email solution, see CodeIgniter's :doc:`Email Library -<../libraries/email>`. + For a more robust email solution, see CodeIgniter's :doc:`Email Library + <../libraries/email>`.
\ No newline at end of file diff --git a/user_guide_src/source/helpers/file_helper.rst b/user_guide_src/source/helpers/file_helper.rst index 194d4348f..59cabcce2 100644 --- a/user_guide_src/source/helpers/file_helper.rst +++ b/user_guide_src/source/helpers/file_helper.rst @@ -4,7 +4,12 @@ File Helper The File Helper file contains functions that assist in working with files. -.. contents:: Page Contents +.. contents:: + :local: + +.. raw:: html + + <div class="custom-index container"></div> Loading this Helper =================== @@ -13,204 +18,185 @@ This helper is loaded using the following code:: $this->load->helper('file'); +Available Functions +=================== + The following functions are available: -read_file() -=========== -.. php:function:: read_file($file) +.. function:: read_file($file) :param string $file: File path - :returns: string or FALSE on failure + :returns: File contents or FALSE on failure + :rtype: string -Returns the data contained in the file specified in the path. + Returns the data contained in the file specified in the path. -Example:: + Example:: - $string = read_file('./path/to/file.php'); + $string = read_file('./path/to/file.php'); -The path can be a relative or full server path. Returns FALSE (boolean) on failure. + The path can be a relative or full server path. Returns FALSE (boolean) on failure. -.. note:: The path is relative to your main site index.php file, NOT your - controller or view files. CodeIgniter uses a front controller so paths - are always relative to the main site index. + .. note:: The path is relative to your main site index.php file, NOT your + controller or view files. CodeIgniter uses a front controller so paths + are always relative to the main site index. -.. note:: This function is DEPRECATED. Use the native ``file_get_contents()`` - instead. + .. note:: This function is DEPRECATED. Use the native ``file_get_contents()`` + instead. -.. important:: If your server is running an **open_basedir** restriction this - function might not work if you are trying to access a file above the - calling script. + .. important:: If your server is running an **open_basedir** restriction this + function might not work if you are trying to access a file above the + calling script. -write_file() -============ - -.. php:function:: write_file($path, $data, $mode = 'wb') +.. function:: write_file($path, $data[, $mode = 'wb']) :param string $path: File path :param string $data: Data to write to file :param string $mode: ``fopen()`` mode - :returns: bool - -Writes data to the file specified in the path. If the file does not exist then the -function will create it. + :returns: TRUE if the write was successful, FALSE in case of an error + :rtype: bool -Example:: + Writes data to the file specified in the path. If the file does not exist then the + function will create it. - $data = 'Some file data'; - if ( ! write_file('./path/to/file.php', $data)) - { - echo 'Unable to write the file'; - } - else - { - echo 'File written!'; - } + Example:: -You can optionally set the write mode via the third parameter:: + $data = 'Some file data'; + if ( ! write_file('./path/to/file.php', $data)) + { + echo 'Unable to write the file'; + } + else + { + echo 'File written!'; + } - write_file('./path/to/file.php', $data, 'r+'); + You can optionally set the write mode via the third parameter:: -The default mode is 'wb'. Please see the `PHP user guide <http://php.net/fopen>`_ -for mode options. + write_file('./path/to/file.php', $data, 'r+'); -.. note: In order for this function to write data to a file, its permissions must - be set such that it is writable (666, 777, etc.). If the file does not - already exist, the directory containing it must be writable. + The default mode is 'wb'. Please see the `PHP user guide <http://php.net/fopen>`_ + for mode options. -.. note:: The path is relative to your main site index.php file, NOT your - controller or view files. CodeIgniter uses a front controller so paths - are always relative to the main site index. + .. note: In order for this function to write data to a file, its permissions must + be set such that it is writable (666, 777, etc.). If the file does not + already exist, the directory containing it must be writable. -.. note:: This function acquires an exclusive lock on the file while writing to it. + .. note:: The path is relative to your main site index.php file, NOT your + controller or view files. CodeIgniter uses a front controller so paths + are always relative to the main site index. -delete_files() -============== + .. note:: This function acquires an exclusive lock on the file while writing to it. -.. php:function:: delete_files($path, $del_dir = FALSE, $htdocs = FALSE) +.. function:: delete_files($path[, $del_dir = FALSE[, $htdocs = FALSE]]) :param string $path: Directory path :param bool $del_dir: Whether to also delete directories :param bool $htdocs: Whether to skip deleting .htaccess and index page files - :returns: bool + :returns: TRUE on success, FALSE in case of an error + :rtype: bool -Deletes ALL files contained in the supplied path. + Deletes ALL files contained in the supplied path. -Example:: + Example:: - delete_files('./path/to/directory/'); + delete_files('./path/to/directory/'); -If the second parameter is set to TRUE, any directories contained within the supplied -root path will be deleted as well. + If the second parameter is set to TRUE, any directories contained within the supplied + root path will be deleted as well. -Example:: + Example:: - delete_files('./path/to/directory/', TRUE); + delete_files('./path/to/directory/', TRUE); -.. note:: The files must be writable or owned by the system in order to be deleted. + .. note:: The files must be writable or owned by the system in order to be deleted. -get_filenames() -=============== - -.. php:function:: get_filenames($source_dir, $include_path = FALSE) +.. function:: get_filenames($source_dir[, $include_path = FALSE]) :param string $source_dir: Directory path :param bool $include_path: Whether to include the path as part of the filenames - :returns: array + :returns: An array of file names + :rtype: array -Takes a server path as input and returns an array containing the names of all files -contained within it. The file path can optionally be added to the file names by setting -the second parameter to TRUE. + Takes a server path as input and returns an array containing the names of all files + contained within it. The file path can optionally be added to the file names by setting + the second parameter to TRUE. -Example:: + Example:: - $controllers = get_filenames(APPPATH.'controllers/'); + $controllers = get_filenames(APPPATH.'controllers/'); -get_dir_file_info() -=================== - -.. php:function:: get_dir_file_info($source_dir, $top_level_only) +.. function:: get_dir_file_info($source_dir, $top_level_only) :param string $source_dir: Directory path - :param bool $top_level_only: Whether to look only at the specified directory - (excluding sub-directories) - :returns: array - -Reads the specified directory and builds an array containing the filenames, filesize, -dates, and permissions. Sub-folders contained within the specified path are only read -if forced by sending the second parameter to FALSE, as this can be an intensive -operation. + :param bool $top_level_only: Whether to look only at the specified directory (excluding sub-directories) + :returns: An array containing info on the supplied directory's contents + :rtype: array -Example:: + Reads the specified directory and builds an array containing the filenames, filesize, + dates, and permissions. Sub-folders contained within the specified path are only read + if forced by sending the second parameter to FALSE, as this can be an intensive + operation. - $models_info = get_dir_file_info(APPPATH.'models/'); + Example:: -get_file_info() -=============== + $models_info = get_dir_file_info(APPPATH.'models/'); -.. php:function: get_file_info($file, $returned_values = array('name', 'server_path', 'size', 'date')) +.. function:: get_file_info($file[, $returned_values = array('name', 'server_path', 'size', 'date')]) :param string $file: File path :param array $returned_values: What type of info to return - :returns: array or FALSE on failure - -Given a file and path, returns (optionally) the *name*, *path*, *size* and *date modified* -information attributes for a file. Second parameter allows you to explicitly declare what -information you want returned. - -Valid ``$returned_values`` options are: `name`, `size`, `date`, `readable`, `writeable`, -`executable` and `fileperms`. + :returns: An array containing info on the specified file or FALSE on failure + :rtype: array -.. note:: The *writable* attribute is checked via PHP's ``is_writeable()`` function, which - known to have issues on the IIS webserver. Consider using *fileperms* instead, - which returns information from PHP's ``fileperms()`` function. + Given a file and path, returns (optionally) the *name*, *path*, *size* and *date modified* + information attributes for a file. Second parameter allows you to explicitly declare what + information you want returned. -get_mime_by_extension() -======================= + Valid ``$returned_values`` options are: `name`, `size`, `date`, `readable`, `writeable`, + `executable` and `fileperms`. -.. php:function:: get_mime_by_extension($filename) +.. function:: get_mime_by_extension($filename) :param string $filename: File name - :returns: string or FALSE on failure + :returns: MIME type string or FALSE on failure + :rtype: string -Translates a filename extension into a MIME type based on *config/mimes.php*. -Returns FALSE if it can't determine the type, or read the MIME config file. + Translates a filename extension into a MIME type based on *config/mimes.php*. + Returns FALSE if it can't determine the type, or read the MIME config file. -:: + :: - $file = 'somefile.png'; - echo $file.' is has a mime type of '.get_mime_by_extension($file); + $file = 'somefile.png'; + echo $file.' is has a mime type of '.get_mime_by_extension($file); -.. note:: This is not an accurate way of determining file MIME types, and - is here strictly for convenience. It should not be used for security - purposes. + .. note:: This is not an accurate way of determining file MIME types, and + is here strictly for convenience. It should not be used for security + purposes. -symbolic_permissions() -====================== - -.. php:function:: symbolic_permissions($perms) +.. function:: symbolic_permissions($perms) :param int $perms: Permissions - :returns: string - -Takes numeric permissions (such as is returned by ``fileperms()``) and returns -standard symbolic notation of file permissions. + :returns: Symbolic permissions string + :rtype: string -:: + Takes numeric permissions (such as is returned by ``fileperms()``) and returns + standard symbolic notation of file permissions. - echo symbolic_permissions(fileperms('./index.php')); // -rw-r--r-- + :: -octal_permissions() -=================== + echo symbolic_permissions(fileperms('./index.php')); // -rw-r--r-- -.. php:function:: octal_permissions($perms) +.. function:: octal_permissions($perms) :param int $perms: Permissions - :returns: string + :returns: Octal permissions string + :rtype: string -Takes numeric permissions (such as is returned by ``fileperms()``) and returns -a three character octal notation of file permissions. + Takes numeric permissions (such as is returned by ``fileperms()``) and returns + a three character octal notation of file permissions. -:: + :: - echo octal_permissions(fileperms('./index.php')); // 644
\ No newline at end of file + echo octal_permissions(fileperms('./index.php')); // 644
\ No newline at end of file diff --git a/user_guide_src/source/helpers/form_helper.rst b/user_guide_src/source/helpers/form_helper.rst index f49027baa..4fa5f246b 100644 --- a/user_guide_src/source/helpers/form_helper.rst +++ b/user_guide_src/source/helpers/form_helper.rst @@ -5,7 +5,12 @@ Form Helper The Form Helper file contains functions that assist in working with forms. -.. contents:: Page Contents +.. contents:: + :local: + +.. raw:: html + + <div class="custom-index container"></div> Loading this Helper =================== @@ -14,713 +19,684 @@ This helper is loaded using the following code:: $this->load->helper('form'); +Available Functions +=================== + The following functions are available: -form_open() -=========== -.. php:function:: form_open($action = '', $attributes = '', $hidden = array()) +.. function:: form_open([$action = ''[, $attributes = ''[, $hidden = array()]]]) :param string $action: Form action/target URI string :param array $attributes: HTML attributes :param array $hidden: An array of hidden fields' definitions - :returns: string + :returns: An HTML form opening tag + :rtype: string -Creates an opening form tag with a base URL **built from your config preferences**. -It will optionally let you add form attributes and hidden input fields, and -will always add the `accept-charset` attribute based on the charset value in your -config file. + Creates an opening form tag with a base URL **built from your config preferences**. + It will optionally let you add form attributes and hidden input fields, and + will always add the `accept-charset` attribute based on the charset value in your + config file. -The main benefit of using this tag rather than hard coding your own HTML is that -it permits your site to be more portable in the event your URLs ever change. + The main benefit of using this tag rather than hard coding your own HTML is that + it permits your site to be more portable in the event your URLs ever change. -Here's a simple example:: + Here's a simple example:: - echo form_open('email/send'); + echo form_open('email/send'); -The above example would create a form that points to your base URL plus the -"email/send" URI segments, like this:: + The above example would create a form that points to your base URL plus the + "email/send" URI segments, like this:: - <form method="post" accept-charset="utf-8" action="http://example.com/index.php/email/send"> + <form method="post" accept-charset="utf-8" action="http://example.com/index.php/email/send"> -Adding Attributes -^^^^^^^^^^^^^^^^^ + **Adding Attributes** -Attributes can be added by passing an associative array to the second -parameter, like this:: + Attributes can be added by passing an associative array to the second + parameter, like this:: - $attributes = array('class' => 'email', 'id' => 'myform'); - echo form_open('email/send', $attributes); + $attributes = array('class' => 'email', 'id' => 'myform'); + echo form_open('email/send', $attributes); -Alternatively, you can specify the second parameter as a string:: + Alternatively, you can specify the second parameter as a string:: - echo form_open('email/send', 'class="email" id="myform"'); + echo form_open('email/send', 'class="email" id="myform"'); -The above examples would create a form similar to this:: + The above examples would create a form similar to this:: - <form method="post" accept-charset="utf-8" action="http://example.com/index.php/email/send" class="email" id="myform"> + <form method="post" accept-charset="utf-8" action="http://example.com/index.php/email/send" class="email" id="myform"> -Adding Hidden Input Fields -^^^^^^^^^^^^^^^^^^^^^^^^^^ + **Adding Hidden Input Fields** -Hidden fields can be added by passing an associative array to the -third parameter, like this:: + Hidden fields can be added by passing an associative array to the + third parameter, like this:: - $hidden = array('username' => 'Joe', 'member_id' => '234'); - echo form_open('email/send', '', $hidden); + $hidden = array('username' => 'Joe', 'member_id' => '234'); + echo form_open('email/send', '', $hidden); -You can skip the second parameter by passing any falsy value to it. + You can skip the second parameter by passing any falsy value to it. -The above example would create a form similar to this:: + The above example would create a form similar to this:: - <form method="post" accept-charset="utf-8" action="http://example.com/index.php/email/send"> - <input type="hidden" name="username" value="Joe" /> - <input type="hidden" name="member_id" value="234" /> + <form method="post" accept-charset="utf-8" action="http://example.com/index.php/email/send"> + <input type="hidden" name="username" value="Joe" /> + <input type="hidden" name="member_id" value="234" /> -form_open_multipart() -===================== -.. php:function:: form_open_multipart($action = '', $attributes = array(), $hidden = array()) +.. function:: form_open_multipart([$action = ''[, $attributes = array()[, $hidden = array()]]) :param string $action: Form action/target URI string :param array $attributes: HTML attributes :param array $hidden: An array of hidden fields' definitions - :returns: string + :returns: An HTML multipart form opening tag + :rtype: string -This function is absolutely identical to :php:func:`form_open()` above, -except that it adds a *multipart* attribute, which is necessary if you -would like to use the form to upload files with. + This function is absolutely identical to :func:`form_open()` above, + except that it adds a *multipart* attribute, which is necessary if you + would like to use the form to upload files with. -form_hidden() -============= -.. php:function:: form_hidden($name, $value = '') +.. function:: form_hidden($name[, $value = '']) :param string $name: Field name :param string $value: Field value - :returns: string - -Lets you generate hidden input fields. You can either submit a -name/value string to create one field:: + :returns: An HTML hidden input field tag + :rtype: string - form_hidden('username', 'johndoe'); - // Would produce: <input type="hidden" name="username" value="johndoe" /> + Lets you generate hidden input fields. You can either submit a + name/value string to create one field:: -... or you can submit an associative array to create multiple fields:: + form_hidden('username', 'johndoe'); + // Would produce: <input type="hidden" name="username" value="johndoe" /> - $data = array( - 'name' => 'John Doe', - 'email' => 'john@example.com', - 'url' => 'http://example.com' - ); + ... or you can submit an associative array to create multiple fields:: - echo form_hidden($data); + $data = array( + 'name' => 'John Doe', + 'email' => 'john@example.com', + 'url' => 'http://example.com' + ); - /* - Would produce: - <input type="hidden" name="name" value="John Doe" /> - <input type="hidden" name="email" value="john@example.com" /> - <input type="hidden" name="url" value="http://example.com" /> - */ + echo form_hidden($data); -You can also pass an associative array to the value field:: + /* + Would produce: + <input type="hidden" name="name" value="John Doe" /> + <input type="hidden" name="email" value="john@example.com" /> + <input type="hidden" name="url" value="http://example.com" /> + */ - $data = array( - 'name' => 'John Doe', - 'email' => 'john@example.com', - 'url' => 'http://example.com' - ); + You can also pass an associative array to the value field:: - echo form_hidden('my_array', $data); + $data = array( + 'name' => 'John Doe', + 'email' => 'john@example.com', + 'url' => 'http://example.com' + ); - /* - Would produce: + echo form_hidden('my_array', $data); - <input type="hidden" name="my_array[name]" value="John Doe" /> - <input type="hidden" name="my_array[email]" value="john@example.com" /> - <input type="hidden" name="my_array[url]" value="http://example.com" /> - */ + /* + Would produce: -If you want to create hidden input fields with extra attributes:: + <input type="hidden" name="my_array[name]" value="John Doe" /> + <input type="hidden" name="my_array[email]" value="john@example.com" /> + <input type="hidden" name="my_array[url]" value="http://example.com" /> + */ - $data = array( - 'type' => 'hidden', - 'name' => 'email', - 'id' => 'hiddenemail', - 'value' => 'john@example.com', - 'class' => 'hiddenemail' - ); + If you want to create hidden input fields with extra attributes:: - echo form_input($data); + $data = array( + 'type' => 'hidden', + 'name' => 'email', + 'id' => 'hiddenemail', + 'value' => 'john@example.com', + 'class' => 'hiddenemail' + ); - /* - Would produce: + echo form_input($data); - <input type="hidden" name="email" value="john@example.com" id="hiddenemail" class="hiddenemail" /> - */ + /* + Would produce: -form_input() -============ + <input type="hidden" name="email" value="john@example.com" id="hiddenemail" class="hiddenemail" /> + */ -.. php:function:: form_input($data = '', $value = '', $extra = '') +.. function:: form_input([$data = ''[, $value = ''[, $extra = '']]) :param array $data: Field attributes data :param string $value: Field value :param string $extra: Extra attributes to be added to the tag *as is* - :returns: string - -Lets you generate a standard text input field. You can minimally pass -the field name and value in the first and second parameter:: + :returns: An HTML text input field tag + :rtype: string - echo form_input('username', 'johndoe'); + Lets you generate a standard text input field. You can minimally pass + the field name and value in the first and second parameter:: -Or you can pass an associative array containing any data you wish your -form to contain:: + echo form_input('username', 'johndoe'); - $data = array( - 'name' => 'username', - 'id' => 'username', - 'value' => 'johndoe', - 'maxlength' => '100', - 'size' => '50', - 'style' => 'width:50%' - ); + Or you can pass an associative array containing any data you wish your + form to contain:: - echo form_input($data); + $data = array( + 'name' => 'username', + 'id' => 'username', + 'value' => 'johndoe', + 'maxlength' => '100', + 'size' => '50', + 'style' => 'width:50%' + ); - /* - Would produce: + echo form_input($data); - <input type="text" name="username" value="johndoe" id="username" maxlength="100" size="50" style="width:50%" /> - */ + /* + Would produce: -If you would like your form to contain some additional data, like -JavaScript, you can pass it as a string in the third parameter:: + <input type="text" name="username" value="johndoe" id="username" maxlength="100" size="50" style="width:50%" /> + */ - $js = 'onClick="some_function()"'; - echo form_input('username', 'johndoe', $js); + If you would like your form to contain some additional data, like + JavaScript, you can pass it as a string in the third parameter:: -form_password() -=============== + $js = 'onClick="some_function()"'; + echo form_input('username', 'johndoe', $js); -.. php:function:: form_password($data = '', $value = '', $extra = '') +.. function:: form_password([$data = ''[, $value = ''[, $extra = '']]]) :param array $data: Field attributes data :param string $value: Field value :param string $extra: Extra attributes to be added to the tag *as is* - :returns: string + :returns: An HTML password input field tag + :rtype: string -This function is identical in all respects to the :php:func:`form_input()` -function above except that it uses the "password" input type. + This function is identical in all respects to the :func:`form_input()` + function above except that it uses the "password" input type. -form_upload() -============= -.. php:function:: form_upload($data = '', $value = '', $extra = '') +.. function:: form_upload([$data = ''[, $value = ''[, $extra = '']]]) :param array $data: Field attributes data :param string $value: Field value :param string $extra: Extra attributes to be added to the tag *as is* - :returns: string + :returns: An HTML file upload input field tag + :rtype: string -This function is identical in all respects to the :php:func:`form_input()` -function above except that it uses the "file" input type, allowing it to -be used to upload files. + This function is identical in all respects to the :func:`form_input()` + function above except that it uses the "file" input type, allowing it to + be used to upload files. -form_textarea() -=============== -.. php:function:: form_textarea($data = '', $value = '', $extra = '') +.. function:: form_textarea([$data = ''[, $value = ''[, $extra = '']]]) :param array $data: Field attributes data :param string $value: Field value :param string $extra: Extra attributes to be added to the tag *as is* - :returns: string + :returns: An HTML textarea tag + :rtype: string -This function is identical in all respects to the :php:func:`form_input()` -function above except that it generates a "textarea" type. + This function is identical in all respects to the :func:`form_input()` + function above except that it generates a "textarea" type. -.. note: Instead of the *maxlength* and *size* attributes in the above example, - you will instead specify *rows* and *cols*. + .. note:: Instead of the *maxlength* and *size* attributes in the above example, + you will instead specify *rows* and *cols*. -form_dropdown() -=============== - -.. php:function:: form_dropdown($name = '', $options = array(), $selected = array(), $extra = '') +.. function:: form_dropdown([$name = ''[, $options = array()[, $selected = array()[, $extra = '']]]]) :param string $name: Field name :param array $options: An associative array of options to be listed :param array $selected: List of fields to mark with the *selected* attribute :param string $extra: Extra attributes to be added to the tag *as is* - :returns: string - -Lets you create a standard drop-down field. The first parameter will -contain the name of the field, the second parameter will contain an -associative array of options, and the third parameter will contain the -value you wish to be selected. You can also pass an array of multiple -items through the third parameter, and CodeIgniter will create a -multiple select for you. - -Example:: - - $options = array( - 'small' => 'Small Shirt', - 'med' => 'Medium Shirt', - 'large' => 'Large Shirt', - 'xlarge' => 'Extra Large Shirt', - ); - - $shirts_on_sale = array('small', 'large'); - echo form_dropdown('shirts', $options, 'large'); - - /* - Would produce: - - <select name="shirts"> - <option value="small">Small Shirt</option> - <option value="med">Medium Shirt</option> - <option value="large" selected="selected">Large Shirt</option> - <option value="xlarge">Extra Large Shirt</option> - </select> - */ + :returns: An HTML dropdown select field tag + :rtype: string - echo form_dropdown('shirts', $options, $shirts_on_sale); + Lets you create a standard drop-down field. The first parameter will + contain the name of the field, the second parameter will contain an + associative array of options, and the third parameter will contain the + value you wish to be selected. You can also pass an array of multiple + items through the third parameter, and CodeIgniter will create a + multiple select for you. - /* - Would produce: + Example:: - <select name="shirts" multiple="multiple"> - <option value="small" selected="selected">Small Shirt</option> - <option value="med">Medium Shirt</option> - <option value="large" selected="selected">Large Shirt</option> - <option value="xlarge">Extra Large Shirt</option> - </select> - */ + $options = array( + 'small' => 'Small Shirt', + 'med' => 'Medium Shirt', + 'large' => 'Large Shirt', + 'xlarge' => 'Extra Large Shirt', + ); + + $shirts_on_sale = array('small', 'large'); + echo form_dropdown('shirts', $options, 'large'); + + /* + Would produce: + + <select name="shirts"> + <option value="small">Small Shirt</option> + <option value="med">Medium Shirt</option> + <option value="large" selected="selected">Large Shirt</option> + <option value="xlarge">Extra Large Shirt</option> + </select> + */ -If you would like the opening <select> to contain additional data, like -an id attribute or JavaScript, you can pass it as a string in the fourth -parameter:: + echo form_dropdown('shirts', $options, $shirts_on_sale); - $js = 'id="shirts" onChange="some_function();"'; - echo form_dropdown('shirts', $options, 'large', $js); + /* + Would produce: -If the array passed as ``$options`` is a multidimensional array, then -``form_dropdown()`` will produce an <optgroup> with the array key as the -label. + <select name="shirts" multiple="multiple"> + <option value="small" selected="selected">Small Shirt</option> + <option value="med">Medium Shirt</option> + <option value="large" selected="selected">Large Shirt</option> + <option value="xlarge">Extra Large Shirt</option> + </select> + */ -form_multiselect() -================== + If you would like the opening <select> to contain additional data, like + an id attribute or JavaScript, you can pass it as a string in the fourth + parameter:: -.. php:function:: form_multiselect($name = '', $options = array(), $selected = array(), $extra = '') + $js = 'id="shirts" onChange="some_function();"'; + echo form_dropdown('shirts', $options, 'large', $js); + + If the array passed as ``$options`` is a multidimensional array, then + ``form_dropdown()`` will produce an <optgroup> with the array key as the + label. + + +.. function:: form_multiselect([$name = ''[, $options = array()[, $selected = array()[, $extra = '']]]]) :param string $name: Field name :param array $options: An associative array of options to be listed :param array $selected: List of fields to mark with the *selected* attribute :param string $extra: Extra attributes to be added to the tag *as is* - :returns: string + :returns: An HTML dropdown multiselect field tag + :rtype: string -Lets you create a standard multiselect field. The first parameter will -contain the name of the field, the second parameter will contain an -associative array of options, and the third parameter will contain the -value or values you wish to be selected. + Lets you create a standard multiselect field. The first parameter will + contain the name of the field, the second parameter will contain an + associative array of options, and the third parameter will contain the + value or values you wish to be selected. -The parameter usage is identical to using :php:func:`form_dropdown()` above, -except of course that the name of the field will need to use POST array -syntax, e.g. foo[]. + The parameter usage is identical to using :func:`form_dropdown()` above, + except of course that the name of the field will need to use POST array + syntax, e.g. foo[]. -form_fieldset() -=============== -.. php:function:: form_fieldset($legend_text = '', $attributes = array()) +.. function:: form_fieldset([$legend_text = ''[, $attributes = array()]]) :param string $legend_text: Text to put in the <legend> tag :param array $attributes: Attributes to be set on the <fieldset> tag - :returns: string + :returns: An HTML fieldset opening tag + :rtype: string -Lets you generate fieldset/legend fields. + Lets you generate fieldset/legend fields. -Example:: + Example:: - echo form_fieldset('Address Information'); - echo "<p>fieldset content here</p>\n"; - echo form_fieldset_close(); + echo form_fieldset('Address Information'); + echo "<p>fieldset content here</p>\n"; + echo form_fieldset_close(); - /* - Produces: + /* + Produces: - <fieldset> - <legend>Address Information</legend> - <p>form content here</p> - </fieldset> - */ + <fieldset> + <legend>Address Information</legend> + <p>form content here</p> + </fieldset> + */ -Similar to other functions, you can submit an associative array in the -second parameter if you prefer to set additional attributes:: + Similar to other functions, you can submit an associative array in the + second parameter if you prefer to set additional attributes:: - $attributes = array( - 'id' => 'address_info', - 'class' => 'address_info' - ); + $attributes = array( + 'id' => 'address_info', + 'class' => 'address_info' + ); - echo form_fieldset('Address Information', $attributes); - echo "<p>fieldset content here</p>\n"; - echo form_fieldset_close(); + echo form_fieldset('Address Information', $attributes); + echo "<p>fieldset content here</p>\n"; + echo form_fieldset_close(); - /* - Produces: + /* + Produces: - <fieldset id="address_info" class="address_info"> - <legend>Address Information</legend> - <p>form content here</p> - </fieldset> - */ + <fieldset id="address_info" class="address_info"> + <legend>Address Information</legend> + <p>form content here</p> + </fieldset> + */ -form_fieldset_close() -===================== -.. php:function:: form_fieldset_close($extra = '') +.. function:: form_fieldset_close([$extra = '']) :param string $extra: Anything to append after the closing tag, *as is* - :returns: string + :returns: An HTML fieldset closing tag + :rtype: string + -Produces a closing </fieldset> tag. The only advantage to using this -function is it permits you to pass data to it which will be added below -the tag. For example + Produces a closing </fieldset> tag. The only advantage to using this + function is it permits you to pass data to it which will be added below + the tag. For example -:: + :: - $string = '</div></div>'; - echo form_fieldset_close($string); - // Would produce: </fieldset></div></div> + $string = '</div></div>'; + echo form_fieldset_close($string); + // Would produce: </fieldset></div></div> -form_checkbox() -=============== -.. php:function:: form_checkbox($data = '', $value = '', $checked = FALSE, $extra = '') +.. function:: form_checkbox([$data = ''[, $value = ''[, $checked = FALSE[, $extra = '']]]]) :param array $data: Field attributes data :param string $value: Field value :param bool $checked: Whether to mark the checkbox as being *checked* :param string $extra: Extra attributes to be added to the tag *as is* - :returns: string + :returns: An HTML checkbox input tag + :rtype: string -Lets you generate a checkbox field. Simple example:: + Lets you generate a checkbox field. Simple example:: - echo form_checkbox('newsletter', 'accept', TRUE); - // Would produce: <input type="checkbox" name="newsletter" value="accept" checked="checked" /> + echo form_checkbox('newsletter', 'accept', TRUE); + // Would produce: <input type="checkbox" name="newsletter" value="accept" checked="checked" /> -The third parameter contains a boolean TRUE/FALSE to determine whether -the box should be checked or not. + The third parameter contains a boolean TRUE/FALSE to determine whether + the box should be checked or not. -Similar to the other form functions in this helper, you can also pass an -array of attributes to the function:: + Similar to the other form functions in this helper, you can also pass an + array of attributes to the function:: - $data = array( - 'name' => 'newsletter', - 'id' => 'newsletter', - 'value' => 'accept', - 'checked' => TRUE, - 'style' => 'margin:10px' - ); + $data = array( + 'name' => 'newsletter', + 'id' => 'newsletter', + 'value' => 'accept', + 'checked' => TRUE, + 'style' => 'margin:10px' + ); - echo form_checkbox($data); - // Would produce: <input type="checkbox" name="newsletter" id="newsletter" value="accept" checked="checked" style="margin:10px" /> + echo form_checkbox($data); + // Would produce: <input type="checkbox" name="newsletter" id="newsletter" value="accept" checked="checked" style="margin:10px" /> -Also as with other functions, if you would like the tag to contain -additional data like JavaScript, you can pass it as a string in the -fourth parameter:: + Also as with other functions, if you would like the tag to contain + additional data like JavaScript, you can pass it as a string in the + fourth parameter:: - $js = 'onClick="some_function()"'; - echo form_checkbox('newsletter', 'accept', TRUE, $js) + $js = 'onClick="some_function()"'; + echo form_checkbox('newsletter', 'accept', TRUE, $js) -form_radio() -============ -.. php:function:: form_radio($data = '', $value = '', $checked = FALSE, $extra = '') +.. function:: form_radio([$data = ''[, $value = ''[, $checked = FALSE[, $extra = '']]]]) :param array $data: Field attributes data :param string $value: Field value :param bool $checked: Whether to mark the radio button as being *checked* :param string $extra: Extra attributes to be added to the tag *as is* - :returns: string + :returns: An HTML radio input tag + :rtype: string -This function is identical in all respects to the :php:func:`form_checkbox()` -function above except that it uses the "radio" input type. + This function is identical in all respects to the :func:`form_checkbox()` + function above except that it uses the "radio" input type. -form_label() -============ -.. php:function:: form_label($label_text = '', $id = '', $attributes = array()) +.. function:: form_label([$label_text = ''[, $id = ''[, $attributes = array()]]]) :param string $label_text: Text to put in the <label> tag :param string $id: ID of the form element that we're making a label for :param string $attributes: HTML attributes - :returns: string + :returns: An HTML field label tag + :rtype: string -Lets you generate a <label>. Simple example:: + Lets you generate a <label>. Simple example:: - echo form_label('What is your Name', 'username'); - // Would produce: <label for="username">What is your Name</label> + echo form_label('What is your Name', 'username'); + // Would produce: <label for="username">What is your Name</label> -Similar to other functions, you can submit an associative array in the -third parameter if you prefer to set additional attributes. + Similar to other functions, you can submit an associative array in the + third parameter if you prefer to set additional attributes. -Example:: + Example:: - $attributes = array( - 'class' => 'mycustomclass', - 'style' => 'color: #000;' - ); + $attributes = array( + 'class' => 'mycustomclass', + 'style' => 'color: #000;' + ); - echo form_label('What is your Name', 'username', $attributes); - // Would produce: <label for="username" class="mycustomclass" style="color: #000;">What is your Name</label> + echo form_label('What is your Name', 'username', $attributes); + // Would produce: <label for="username" class="mycustomclass" style="color: #000;">What is your Name</label> -form_submit() -============= -.. php:function:: form_submit($data = '', $value = '', $extra = '') +.. function:: form_submit([$data = ''[, $value = ''[, $extra = '']]]) :param string $data: Button name :param string $value: Button value :param string $extra: Extra attributes to be added to the tag *as is* - :returns: string + :returns: An HTML input submit tag + :rtype: string -Lets you generate a standard submit button. Simple example:: + Lets you generate a standard submit button. Simple example:: - echo form_submit('mysubmit', 'Submit Post!'); - // Would produce: <input type="submit" name="mysubmit" value="Submit Post!" /> + echo form_submit('mysubmit', 'Submit Post!'); + // Would produce: <input type="submit" name="mysubmit" value="Submit Post!" /> -Similar to other functions, you can submit an associative array in the -first parameter if you prefer to set your own attributes. The third -parameter lets you add extra data to your form, like JavaScript. + Similar to other functions, you can submit an associative array in the + first parameter if you prefer to set your own attributes. The third + parameter lets you add extra data to your form, like JavaScript. -form_reset() -============ -.. php:function:: form_reset($data = '', $value = '', $extra = '') +.. function:: form_reset([$data = ''[, $value = ''[, $extra = '']]]) :param string $data: Button name :param string $value: Button value :param string $extra: Extra attributes to be added to the tag *as is* - :returns: string + :returns: An HTML input reset button tag + :rtype: string -Lets you generate a standard reset button. Use is identical to -:php:func:`form_submit()`. + Lets you generate a standard reset button. Use is identical to + :func:`form_submit()`. -form_button() -============= -.. php:function:: form_button($data = '', $content = '', $extra = '') +.. function:: form_button([$data = ''[, $content = ''[, $extra = '']]]) :param string $data: Button name :param string $content: Button label :param string $extra: Extra attributes to be added to the tag *as is* - :returns: string + :returns: An HTML button tag + :rtype: string -Lets you generate a standard button element. You can minimally pass the -button name and content in the first and second parameter:: + Lets you generate a standard button element. You can minimally pass the + button name and content in the first and second parameter:: - echo form_button('name','content'); - // Would produce: <button name="name" type="button">Content</button> + echo form_button('name','content'); + // Would produce: <button name="name" type="button">Content</button> -Or you can pass an associative array containing any data you wish your -form to contain:: + Or you can pass an associative array containing any data you wish your + form to contain:: - $data = array( - 'name' => 'button', - 'id' => 'button', - 'value' => 'true', - 'type' => 'reset', - 'content' => 'Reset' - ); + $data = array( + 'name' => 'button', + 'id' => 'button', + 'value' => 'true', + 'type' => 'reset', + 'content' => 'Reset' + ); - echo form_button($data); - // Would produce: <button name="button" id="button" value="true" type="reset">Reset</button> + echo form_button($data); + // Would produce: <button name="button" id="button" value="true" type="reset">Reset</button> -If you would like your form to contain some additional data, like -JavaScript, you can pass it as a string in the third parameter:: + If you would like your form to contain some additional data, like + JavaScript, you can pass it as a string in the third parameter:: - $js = 'onClick="some_function()"'; - echo form_button('mybutton', 'Click Me', $js); + $js = 'onClick="some_function()"'; + echo form_button('mybutton', 'Click Me', $js); -form_close() -============ -.. php:function:: form_close($extra = '') +.. function:: form_close([$extra = '']) :param string $extra: Anything to append after the closing tag, *as is* - :returns: string + :returns: An HTML form closing tag + :rtype: string -Produces a closing </form> tag. The only advantage to using this -function is it permits you to pass data to it which will be added below -the tag. For example:: + Produces a closing </form> tag. The only advantage to using this + function is it permits you to pass data to it which will be added below + the tag. For example:: - $string = '</div></div>'; - echo form_close($string); - // Would produce: </form> </div></div> + $string = '</div></div>'; + echo form_close($string); + // Would produce: </form> </div></div> -form_prep() -=========== -.. php:function:: form_prep($str = '', $is_textarea = FALSE) +.. function:: form_prep([$str = ''[, $is_textarea = FALSE]]) :param string $str: Value to escape :param bool $is_textarea: Whether we're preparing for <textarea> or a regular input tag - :returns: string + :returns: Escaped value + :rtype: string -Allows you to safely use HTML and characters such as quotes within form -elements without breaking out of the form. + Allows you to safely use HTML and characters such as quotes within form + elements without breaking out of the form. -Consider this example:: + Consider this example:: - $string = 'Here is a string containing "quoted" text.'; - <input type="text" name="myform" value="$string" /> + $string = 'Here is a string containing "quoted" text.'; + <input type="text" name="myform" value="$string" /> -Since the above string contains a set of quotes it will cause the form -to break. The ``form_prep()`` function converts HTML so that it can be used -safely:: + Since the above string contains a set of quotes it will cause the form + to break. The ``form_prep()`` function converts HTML so that it can be used + safely:: - <input type="text" name="myform" value="<?php echo form_prep($string); ?>" /> + <input type="text" name="myform" value="<?php echo form_prep($string); ?>" /> -.. note:: If you use any of the form helper functions listed in this page the form - values will be prepped automatically, so there is no need to call this - function. Use it only if you are creating your own form elements. + .. note:: If you use any of the form helper functions listed in this page the form + values will be prepped automatically, so there is no need to call this + function. Use it only if you are creating your own form elements. -set_value() -=========== -.. php:function:: set_value($field = '', $default = '', $is_textarea = FALSE) +.. function:: set_value([$field = ''[, $default = ''[, $is_textarea = FALSE]]]) :param string $field: Field name :param string $default: Default value :param bool $is_textarea: Whether we're setting <textarea> content - :returns: string + :returns: Field value + :rtype: string -Permits you to set the value of an input form or textarea. You must -supply the field name via the first parameter of the function. The -second (optional) parameter allows you to set a default value for the -form. + Permits you to set the value of an input form or textarea. You must + supply the field name via the first parameter of the function. The + second (optional) parameter allows you to set a default value for the + form. -Example:: + Example:: - <input type="text" name="quantity" value="<?=set_value('quantity', '0');?>" size="50" /> + <input type="text" name="quantity" value="<?=set_value('quantity', '0');?>" size="50" /> -The above form will show "0" when loaded for the first time. + The above form will show "0" when loaded for the first time. -set_select() -============ -.. php:function:: set_select($field = '', $value = '', $default = FALSE) +.. function:: set_select([$field = ''[, $value = ''[, $default = FALSE]]]) :param string $field: Field name :param string $value: Value to check for :param string $default: Whether the value is also a default one - :returns: string - -If you use a <select> menu, this function permits you to display the -menu item that was selected. + :returns: 'selected' attribute or an empty string + :rtype: string -The first parameter must contain the name of the select menu, the second -parameter must contain the value of each item, and the third (optional) -parameter lets you set an item as the default (use boolean TRUE/FALSE). + If you use a <select> menu, this function permits you to display the + menu item that was selected. -Example:: + The first parameter must contain the name of the select menu, the second + parameter must contain the value of each item, and the third (optional) + parameter lets you set an item as the default (use boolean TRUE/FALSE). - <select name="myselect"> - <option value="one" <?php echo set_select('myselect', 'one', TRUE); ?> >One</option> - <option value="two" <?php echo set_select('myselect', 'two'); ?> >Two</option> - <option value="three" <?php echo set_select('myselect', 'three'); ?> >Three</option> - </select> + Example:: -set_checkbox() -============== + <select name="myselect"> + <option value="one" <?php echo set_select('myselect', 'one', TRUE); ?> >One</option> + <option value="two" <?php echo set_select('myselect', 'two'); ?> >Two</option> + <option value="three" <?php echo set_select('myselect', 'three'); ?> >Three</option> + </select> -.. php:function:: set_checkbox($field = '', $value = '', $default = FALSE) +.. function:: set_checkbox([$field = ''[, $value = ''[, $default = FALSE]]]) :param string $field: Field name :param string $value: Value to check for :param string $default: Whether the value is also a default one - :returns: string + :returns: 'checked' attribute or an empty string + :rtype: string -Permits you to display a checkbox in the state it was submitted. + Permits you to display a checkbox in the state it was submitted. -The first parameter must contain the name of the checkbox, the second -parameter must contain its value, and the third (optional) parameter -lets you set an item as the default (use boolean TRUE/FALSE). + The first parameter must contain the name of the checkbox, the second + parameter must contain its value, and the third (optional) parameter + lets you set an item as the default (use boolean TRUE/FALSE). -Example:: + Example:: - <input type="checkbox" name="mycheck" value="1" <?php echo set_checkbox('mycheck', '1'); ?> /> - <input type="checkbox" name="mycheck" value="2" <?php echo set_checkbox('mycheck', '2'); ?> /> + <input type="checkbox" name="mycheck" value="1" <?php echo set_checkbox('mycheck', '1'); ?> /> + <input type="checkbox" name="mycheck" value="2" <?php echo set_checkbox('mycheck', '2'); ?> /> -set_radio() -=========== - -.. php:function:: set_radio($field = '', $value = '', $default = FALSE) +.. function:: set_radio([$field = ''[, $value = ''[, $default = FALSE]]]) :param string $field: Field name :param string $value: Value to check for :param string $default: Whether the value is also a default one - :returns: string - -Permits you to display radio buttons in the state they were submitted. -This function is identical to the :php:func:`set_checkbox()` function above. + :returns: 'checked' attribute or an empty string + :rtype: string -Example:: + Permits you to display radio buttons in the state they were submitted. + This function is identical to the :func:`set_checkbox()` function above. - <input type="radio" name="myradio" value="1" <?php echo set_radio('myradio', '1', TRUE); ?> /> - <input type="radio" name="myradio" value="2" <?php echo set_radio('myradio', '2'); ?> /> + Example:: -.. note:: If you are using the Form Validation class, you must always specify - a rule for your field, even if empty, in order for the ``set_*()`` - functions to work. This is because if a Form Validation object is - defined, the control for ``set_*()`` is handed over to a method of the - class instead of the generic helper function. + <input type="radio" name="myradio" value="1" <?php echo set_radio('myradio', '1', TRUE); ?> /> + <input type="radio" name="myradio" value="2" <?php echo set_radio('myradio', '2'); ?> /> -form_error() -============ + .. note:: If you are using the Form Validation class, you must always specify + a rule for your field, even if empty, in order for the ``set_*()`` + functions to work. This is because if a Form Validation object is + defined, the control for ``set_*()`` is handed over to a method of the + class instead of the generic helper function. -.. php:function:: form_error($field = '', $prefix = '', $suffix = '') +.. function:: form_error([$field = ''[, $prefix = ''[, $suffix = '']]]) :param string $field: Field name :param string $prefix: Error opening tag :param string $suffix: Error closing tag - :returns: string + :returns: HTML-formatted form validation error message(s) + :rtype: string -Returns a validation error message from the :doc:`Form Validation Library -<../libraries/form_validation>`, associated with the specified field name. -You can optionally specify opening and closing tag(s) to put around the error -message. + Returns a validation error message from the :doc:`Form Validation Library + <../libraries/form_validation>`, associated with the specified field name. + You can optionally specify opening and closing tag(s) to put around the error + message. -Example:: + Example:: - // Assuming that the 'username' field value was incorrect: - echo form_error('myfield', '<div class="error">', '</div>'); + // Assuming that the 'username' field value was incorrect: + echo form_error('myfield', '<div class="error">', '</div>'); - // Would produce: <div class="error">Error message associated with the "username" field.</div> + // Would produce: <div class="error">Error message associated with the "username" field.</div> -validation_errors() -=================== -.. php:function:: validation_errors($prefix = '', $suffix = '') +.. function:: validation_errors([$prefix = ''[, $suffix = '']]) :param string $prefix: Error opening tag :param string $suffix: Error closing tag - :returns: string + :returns: HTML-formatted form validation error message(s) + :rtype: string -Similarly to the :php:func:`form_error()` function, returns all validation -error messages produced by the :doc:`Form Validation Library -<../libraries/form_validation>`, with optional opening and closing tags -around each of the messages. + Similarly to the :func:`form_error()` function, returns all validation + error messages produced by the :doc:`Form Validation Library + <../libraries/form_validation>`, with optional opening and closing tags + around each of the messages. -Example:: + Example:: - echo validation_errors('<span class="error">', '</span>'); + echo validation_errors('<span class="error">', '</span>'); - /* - Would produce, e.g.: + /* + Would produce, e.g.: - <span class="error">The "email" field doesn't contain a valid e-mail address!</span> - <span class="error">The "password" field doesn't match the "repeat_password" field!</span> + <span class="error">The "email" field doesn't contain a valid e-mail address!</span> + <span class="error">The "password" field doesn't match the "repeat_password" field!</span> - */
\ No newline at end of file + */
\ No newline at end of file diff --git a/user_guide_src/source/helpers/html_helper.rst b/user_guide_src/source/helpers/html_helper.rst index df53ebd2f..3324da8c0 100644 --- a/user_guide_src/source/helpers/html_helper.rst +++ b/user_guide_src/source/helpers/html_helper.rst @@ -5,7 +5,12 @@ HTML Helper The HTML Helper file contains functions that assist in working with HTML. -.. contents:: Page Contents +.. contents:: + :local: + +.. raw:: html + + <div class="custom-index container"></div> Loading this Helper =================== @@ -14,94 +19,95 @@ This helper is loaded using the following code:: $this->load->helper('html'); +Available Functions +=================== + The following functions are available: -br() -==== -.. php:function:: br($count = 1) +.. function:: br([$count = 1]) :param int $count: Number of times to repeat the tag - :returns: string + :returns: HTML line break tag + :rtype: string -Generates line break tags (<br />) based on the number you submit. -Example:: + Generates line break tags (<br />) based on the number you submit. + Example:: - echo br(3); + echo br(3); -The above would produce: <br /><br /><br /> + The above would produce: -heading() -========= + .. code-block:: html -.. php:function:: heading($data = '', $h = '1', $attributes = '') + <br /><br /><br /> + +.. function:: heading([$data = ''[, $h = '1'[, $attributes = '']]]) :param string $data: Content :param string $h: Heading level :param array $attributes: HTML attributes - :returns: string + :returns: HTML heading tag + :rtype: string + + Lets you create HTML heading tags. The first parameter will contain the + data, the second the size of the heading. Example:: -Lets you create HTML heading tags. The first parameter will contain the -data, the second the size of the heading. Example:: + echo heading('Welcome!', 3); - echo heading('Welcome!', 3); + The above would produce: <h3>Welcome!</h3> -The above would produce: <h3>Welcome!</h3> + Additionally, in order to add attributes to the heading tag such as HTML + classes, ids or inline styles, a third parameter is available:: -Additionally, in order to add attributes to the heading tag such as HTML -classes, ids or inline styles, a third parameter is available:: + echo heading('Welcome!', 3, 'class="pink"') - echo heading('Welcome!', 3, 'class="pink"') + The above code produces: -The above code produces: <h3 class="pink">Welcome!<<h3> + .. code-block:: html -img() -===== + <h3 class="pink">Welcome!<h3> -.. php:function:: img($src = '', $index_page = FALSE, $attributes = '') +.. function:: img([$src = ''[, $index_page = FALSE[, $attributes = '']]]) :param string $src: Image source data :param bool $index_page: Whether to treat $src as a routed URI string :param array $attributes: HTML attributes - :returns: string - -Lets you create HTML <img /> tags. The first parameter contains the -image source. Example:: + :returns: HTML image tag + :rtype: string - echo img('images/picture.jpg'); // gives <img src="http://site.com/images/picture.jpg" /> + Lets you create HTML <img /> tags. The first parameter contains the + image source. Example:: -There is an optional second parameter that is a TRUE/FALSE value that -specifics if the *src* should have the page specified by -``$config['index_page']`` added to the address it creates. -Presumably, this would be if you were using a media controller:: + echo img('images/picture.jpg'); // gives <img src="http://site.com/images/picture.jpg" /> - echo img('images/picture.jpg', TRUE); // gives <img src="http://site.com/index.php/images/picture.jpg" alt="" /> + There is an optional second parameter that is a TRUE/FALSE value that + specifics if the *src* should have the page specified by + ``$config['index_page']`` added to the address it creates. + Presumably, this would be if you were using a media controller:: + echo img('images/picture.jpg', TRUE); // gives <img src="http://site.com/index.php/images/picture.jpg" alt="" /> -Additionally, an associative array can be passed to the ``img()`` function -for complete control over all attributes and values. If an *alt* attribute -is not provided, CodeIgniter will generate an empty string. + Additionally, an associative array can be passed to the ``img()`` function + for complete control over all attributes and values. If an *alt* attribute + is not provided, CodeIgniter will generate an empty string. -Example:: + Example:: - $image_properties = array( - 'src' => 'images/picture.jpg', - 'alt' => 'Me, demonstrating how to eat 4 slices of pizza at one time', - 'class' => 'post_images', - 'width' => '200', - 'height'=> '200', - 'title' => 'That was quite a night', - 'rel' => 'lightbox' - ); + $image_properties = array( + 'src' => 'images/picture.jpg', + 'alt' => 'Me, demonstrating how to eat 4 slices of pizza at one time', + 'class' => 'post_images', + 'width' => '200', + 'height'=> '200', + 'title' => 'That was quite a night', + 'rel' => 'lightbox' + ); - img($image_properties); - // <img src="http://site.com/index.php/images/picture.jpg" alt="Me, demonstrating how to eat 4 slices of pizza at one time" class="post_images" width="200" height="200" title="That was quite a night" rel="lightbox" /> + img($image_properties); + // <img src="http://site.com/index.php/images/picture.jpg" alt="Me, demonstrating how to eat 4 slices of pizza at one time" class="post_images" width="200" height="200" title="That was quite a night" rel="lightbox" /> - -link_tag() -========== - -.. php:function:: ling_tag($href = '', $rel = 'stylesheet', $type = 'text/css', $title = '', $media = '', $index_page = FALSE) +.. function:: link_tag([$href = ''[, $rel = 'stylesheet'[, $type = 'text/css'[, $title = ''[, $media = ''[, $index_page = FALSE]]]]]]) :param string $href: What are we linking to :param string $rel: Relation type @@ -109,300 +115,284 @@ link_tag() :param string $title: Link title :param string $media: Media type :param bool $index_page: Whether to treat $src as a routed URI string - :returns: string - -Lets you create HTML <link /> tags. This is useful for stylesheet links, -as well as other links. The parameters are *href*, with optional *rel*, -*type*, *title*, *media* and *index_page*. + :returns: HTML link tag + :rtype: string -*index_page* is a boolean value that specifies if the *href* should have -the page specified by ``$config['index_page']`` added to the address it creates. + Lets you create HTML <link /> tags. This is useful for stylesheet links, + as well as other links. The parameters are *href*, with optional *rel*, + *type*, *title*, *media* and *index_page*. -Example:: + *index_page* is a boolean value that specifies if the *href* should have + the page specified by ``$config['index_page']`` added to the address it creates. - echo link_tag('css/mystyles.css'); - // gives <link href="http://site.com/css/mystyles.css" rel="stylesheet" type="text/css" /> + Example:: + echo link_tag('css/mystyles.css'); + // gives <link href="http://site.com/css/mystyles.css" rel="stylesheet" type="text/css" /> -Further examples:: + Further examples:: - echo link_tag('favicon.ico', 'shortcut icon', 'image/ico'); - // <link href="http://site.com/favicon.ico" rel="shortcut icon" type="image/ico" /> + echo link_tag('favicon.ico', 'shortcut icon', 'image/ico'); + // <link href="http://site.com/favicon.ico" rel="shortcut icon" type="image/ico" /> - echo link_tag('feed', 'alternate', 'application/rss+xml', 'My RSS Feed'); - // <link href="http://site.com/feed" rel="alternate" type="application/rss+xml" title="My RSS Feed" /> + echo link_tag('feed', 'alternate', 'application/rss+xml', 'My RSS Feed'); + // <link href="http://site.com/feed" rel="alternate" type="application/rss+xml" title="My RSS Feed" /> -Additionally, an associative array can be passed to the ``link()`` function -for complete control over all attributes and values:: + Additionally, an associative array can be passed to the ``link()`` function + for complete control over all attributes and values:: - $link = array( - 'href' => 'css/printer.css', - 'rel' => 'stylesheet', - 'type' => 'text/css', - 'media' => 'print' - ); + $link = array( + 'href' => 'css/printer.css', + 'rel' => 'stylesheet', + 'type' => 'text/css', + 'media' => 'print' + ); - echo link_tag($link); - // <link href="http://site.com/css/printer.css" rel="stylesheet" type="text/css" media="print" /> + echo link_tag($link); + // <link href="http://site.com/css/printer.css" rel="stylesheet" type="text/css" media="print" /> -nbs() -===== - -.. php:function:: nbs($num = 1) +.. function:: nbs([$num = 1]) :param int $num: Number of space entities to produce - :returns: string + :returns: A sequence of non-breaking space HTML entities + :rtype: string + + Generates non-breaking spaces ( ) based on the number you submit. + Example:: -Generates non-breaking spaces ( ) based on the number you submit. -Example:: + echo nbs(3); - echo nbs(3); + The above would produce: -The above would produce:: + .. code-block:: html - + -ul() and ol() -============= -.. php:function:: ul($list, $attributes = '') +.. function:: ul($list[, $attributes = '']) :param array $list: List entries :param array $attributes: HTML attributes - :returns: string - -Permits you to generate ordered or unordered HTML lists from simple or -multi-dimensional arrays. Example:: + :returns: HTML-formatted unordered list + :rtype: string - $list = array( - 'red', - 'blue', - 'green', - 'yellow' - ); + Permits you to generate ordered or unordered HTML lists from simple or + multi-dimensional arrays. Example:: - $attributes = array( - 'class' => 'boldlist', - 'id' => 'mylist' - ); - - echo ul($list, $attributes); - -The above code will produce this:: - - <ul class="boldlist" id="mylist"> - <li>red</li> - <li>blue</li> - <li>green</li> - <li>yellow</li> - </ul> - -Here is a more complex example, using a multi-dimensional array:: - - $attributes = array( - 'class' => 'boldlist', - 'id' => 'mylist' - ); - - $list = array( - 'colors' => array( + $list = array( 'red', 'blue', - 'green' - ), - 'shapes' => array( - 'round', - 'square', - 'circles' => array( - 'ellipse', - 'oval', - 'sphere' - ) - ), - 'moods' => array( - 'happy', - 'upset' => array( - 'defeated' => array( - 'dejected', - 'disheartened', - 'depressed' - ), - 'annoyed', - 'cross', - 'angry' + 'green', + 'yellow' + ); + + $attributes = array( + 'class' => 'boldlist', + 'id' => 'mylist' + ); + + echo ul($list, $attributes); + + The above code will produce this: + + .. code-block:: html + + <ul class="boldlist" id="mylist"> + <li>red</li> + <li>blue</li> + <li>green</li> + <li>yellow</li> + </ul> + + Here is a more complex example, using a multi-dimensional array:: + + $attributes = array( + 'class' => 'boldlist', + 'id' => 'mylist' + ); + + $list = array( + 'colors' => array( + 'red', + 'blue', + 'green' + ), + 'shapes' => array( + 'round', + 'square', + 'circles' => array( + 'ellipse', + 'oval', + 'sphere' + ) + ), + 'moods' => array( + 'happy', + 'upset' => array( + 'defeated' => array( + 'dejected', + 'disheartened', + 'depressed' + ), + 'annoyed', + 'cross', + 'angry' + ) ) - ) - ); - - echo ul($list, $attributes); - -The above code will produce this:: - - <ul class="boldlist" id="mylist"> - <li>colors - <ul> - <li>red</li> - <li>blue</li> - <li>green</li> - </ul> - </li> - <li>shapes - <ul> - <li>round</li> - <li>suare</li> - <li>circles - <ul> - <li>elipse</li> - <li>oval</li> - <li>sphere</li> - </ul> - </li> - </ul> - </li> - <li>moods - <ul> - <li>happy</li> - <li>upset - <ul> - <li>defeated - <ul> - <li>dejected</li> - <li>disheartened</li> - <li>depressed</li> - </ul> - </li> - <li>annoyed</li> - <li>cross</li> - <li>angry</li> - </ul> - </li> - </ul> - </li> - </ul> - -.. php:function:: ol($list, $attributes = '') + ); + + echo ul($list, $attributes); + + The above code will produce this: + + .. code-block:: html + + <ul class="boldlist" id="mylist"> + <li>colors + <ul> + <li>red</li> + <li>blue</li> + <li>green</li> + </ul> + </li> + <li>shapes + <ul> + <li>round</li> + <li>suare</li> + <li>circles + <ul> + <li>elipse</li> + <li>oval</li> + <li>sphere</li> + </ul> + </li> + </ul> + </li> + <li>moods + <ul> + <li>happy</li> + <li>upset + <ul> + <li>defeated + <ul> + <li>dejected</li> + <li>disheartened</li> + <li>depressed</li> + </ul> + </li> + <li>annoyed</li> + <li>cross</li> + <li>angry</li> + </ul> + </li> + </ul> + </li> + </ul> + +.. function:: ol($list, $attributes = '') :param array $list: List entries :param array $attributes: HTML attributes - :returns: string + :returns: HTML-formatted ordered list + :rtype: string -Identical to :php:func:`ul()`, only it produces the <ol> tag for -ordered lists instead of <ul>. + Identical to :func:`ul()`, only it produces the <ol> tag for + ordered lists instead of <ul>. -meta() -====== - -.. php:function:: meta($name = '', $content = '', $type = 'name', $newline = "\n") +.. function:: meta([$name = ''[, $content = ''[, $type = 'name'[, $newline = "\n"]]]]) :param string $name: Meta name :param string $content: Meta content :param string $type: Meta type :param string $newline: Newline character - :returns: string - -Helps you generate meta tags. You can pass strings to the function, or -simple arrays, or multidimensional ones. - -Examples:: - - echo meta('description', 'My Great site'); - // Generates: <meta name="description" content="My Great Site" /> - - echo meta('Content-type', 'text/html; charset=utf-8', 'equiv'); - // Note the third parameter. Can be "equiv" or "name" - // Generates: <meta http-equiv="Content-type" content="text/html; charset=utf-8" /> - - echo meta(array('name' => 'robots', 'content' => 'no-cache')); - // Generates: <meta name="robots" content="no-cache" /> - - $meta = array( - array( - 'name' => 'robots', - 'content' => 'no-cache' - ), - array( - 'name' => 'description', - 'content' => 'My Great Site' - ), - array( - 'name' => 'keywords', - 'content' => 'love, passion, intrigue, deception' - ), - array( - 'name' => 'robots', - 'content' => 'no-cache' - ), - array( - 'name' => 'Content-type', - 'content' => 'text/html; charset=utf-8', 'type' => 'equiv' - ) - ); - - echo meta($meta); - // Generates: - // <meta name="robots" content="no-cache" /> - // <meta name="description" content="My Great Site" /> - // <meta name="keywords" content="love, passion, intrigue, deception" /> - // <meta name="robots" content="no-cache" /> - // <meta http-equiv="Content-type" content="text/html; charset=utf-8" /> - -doctype() -========= - -.. php:function:: doctype($type = 'xhtml1-strict') + :returns: HTML meta tag + :rtype: string + + Helps you generate meta tags. You can pass strings to the function, or + simple arrays, or multidimensional ones. + + Examples:: + + echo meta('description', 'My Great site'); + // Generates: <meta name="description" content="My Great Site" /> + + echo meta('Content-type', 'text/html; charset=utf-8', 'equiv'); + // Note the third parameter. Can be "equiv" or "name" + // Generates: <meta http-equiv="Content-type" content="text/html; charset=utf-8" /> + + echo meta(array('name' => 'robots', 'content' => 'no-cache')); + // Generates: <meta name="robots" content="no-cache" /> + + $meta = array( + array( + 'name' => 'robots', + 'content' => 'no-cache' + ), + array( + 'name' => 'description', + 'content' => 'My Great Site' + ), + array( + 'name' => 'keywords', + 'content' => 'love, passion, intrigue, deception' + ), + array( + 'name' => 'robots', + 'content' => 'no-cache' + ), + array( + 'name' => 'Content-type', + 'content' => 'text/html; charset=utf-8', 'type' => 'equiv' + ) + ); - :param string $type: Doctype name + echo meta($meta); + // Generates: + // <meta name="robots" content="no-cache" /> + // <meta name="description" content="My Great Site" /> + // <meta name="keywords" content="love, passion, intrigue, deception" /> + // <meta name="robots" content="no-cache" /> + // <meta http-equiv="Content-type" content="text/html; charset=utf-8" /> -Helps you generate document type declarations, or DTD's. XHTML 1.0 -Strict is used by default, but many doctypes are available. - -Example:: - - echo doctype(); // <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd"> - - echo doctype('html4-trans'); // <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" "http://www.w3.org/TR/html4/strict.dtd"> - -The following is a list of doctype choices. These are configurable, and -pulled from application/config/doctypes.php - -+-------------------------------+------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------+ -| Doctype | Option | Result | -+===============================+==============================+==================================================================================================================================================+ -| XHTML 1.1 | doctype('xhtml11') | <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN" "http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd"> | -+-------------------------------+------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------+ -| XHTML 1.0 Strict | doctype('xhtml1-strict') | <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd"> | -+-------------------------------+------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------+ -| XHTML 1.0 Transitional | doctype('xhtml1-trans') | <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> | -+-------------------------------+------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------+ -| XHTML 1.0 Frameset | doctype('xhtml1-frame') | <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Frameset//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-frameset.dtd"> | -+-------------------------------+------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------+ -| XHTML Basic 1.1 | doctype('xhtml-basic11') | <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML Basic 1.1//EN" "http://www.w3.org/TR/xhtml-basic/xhtml-basic11.dtd"> | -+-------------------------------+------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------+ -| HTML 5 | doctype('html5') | <!DOCTYPE html> | -+-------------------------------+------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------+ -| HTML 4 Strict | doctype('html4-strict') | <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" "http://www.w3.org/TR/html4/strict.dtd"> | -+-------------------------------+------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------+ -| HTML 4 Transitional | doctype('html4-trans') | <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd"> | -+-------------------------------+------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------+ -| HTML 4 Frameset | doctype('html4-frame') | <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Frameset//EN" "http://www.w3.org/TR/html4/frameset.dtd"> | -+-------------------------------+------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------+ -| MathML 1.01 | doctype('mathml1') | <!DOCTYPE math SYSTEM "http://www.w3.org/Math/DTD/mathml1/mathml.dtd"> | -+-------------------------------+------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------+ -| MathML 2.0 | doctype('mathml2') | <!DOCTYPE math PUBLIC "-//W3C//DTD MathML 2.0//EN" "http://www.w3.org/Math/DTD/mathml2/mathml2.dtd"> | -+-------------------------------+------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------+ -| SVG 1.0 | doctype('svg10') | <!DOCTYPE svg PUBLIC "-//W3C//DTD SVG 1.0//EN" "http://www.w3.org/TR/2001/REC-SVG-20010904/DTD/svg10.dtd"> | -+-------------------------------+------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------+ -| SVG 1.1 Full | doctype('svg11') | <!DOCTYPE svg PUBLIC "-//W3C//DTD SVG 1.1//EN" "http://www.w3.org/Graphics/SVG/1.1/DTD/svg11.dtd"> | -+-------------------------------+------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------+ -| SVG 1.1 Basic | doctype('svg11-basic') | <!DOCTYPE svg PUBLIC "-//W3C//DTD SVG 1.1 Basic//EN" "http://www.w3.org/Graphics/SVG/1.1/DTD/svg11-basic.dtd"> | -+-------------------------------+------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------+ -| SVG 1.1 Tiny | doctype('svg11-tiny') | <!DOCTYPE svg PUBLIC "-//W3C//DTD SVG 1.1 Tiny//EN" "http://www.w3.org/Graphics/SVG/1.1/DTD/svg11-tiny.dtd"> | -+-------------------------------+------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------+ -| XHTML+MathML+SVG (XHTML host) | doctype('xhtml-math-svg-xh') | <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1 plus MathML 2.0 plus SVG 1.1//EN" "http://www.w3.org/2002/04/xhtml-math-svg/xhtml-math-svg.dtd"> | -+-------------------------------+------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------+ -| XHTML+MathML+SVG (SVG host) | doctype('xhtml-math-svg-sh') | <!DOCTYPE svg:svg PUBLIC "-//W3C//DTD XHTML 1.1 plus MathML 2.0 plus SVG 1.1//EN" "http://www.w3.org/2002/04/xhtml-math-svg/xhtml-math-svg.dtd"> | -+-------------------------------+------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------+ -| XHTML+RDFa 1.0 | doctype('xhtml-rdfa-1') | <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML+RDFa 1.0//EN" "http://www.w3.org/MarkUp/DTD/xhtml-rdfa-1.dtd"> | -+-------------------------------+------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------+ -| XHTML+RDFa 1.1 | doctype('xhtml-rdfa-2') | <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML+RDFa 1.1//EN" "http://www.w3.org/MarkUp/DTD/xhtml-rdfa-2.dtd"> | -+-------------------------------+------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------+
\ No newline at end of file + +.. function:: doctype([$type = 'xhtml1-strict']) + + :param string $type: Doctype name + :returns: HTML DocType tag + :rtype: string + + Helps you generate document type declarations, or DTD's. XHTML 1.0 + Strict is used by default, but many doctypes are available. + + Example:: + + echo doctype(); // <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd"> + + echo doctype('html4-trans'); // <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" "http://www.w3.org/TR/html4/strict.dtd"> + + The following is a list of doctype choices. These are configurable, and + pulled from application/config/doctypes.php + + =============================== =================== ================================================================================================================================================== + Document type Option Result + =============================== =================== ================================================================================================================================================== + XHTML 1.1 xhtml11 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN" "http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd"> + XHTML 1.0 Strict xhtml1-strict <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd"> + XHTML 1.0 Transitional xhtml1-trans <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> + XHTML 1.0 Frameset xhtml1-frame <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Frameset//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-frameset.dtd"> + XHTML Basic 1.1 xhtml-basic11 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML Basic 1.1//EN" "http://www.w3.org/TR/xhtml-basic/xhtml-basic11.dtd"> + HTML 5 html5 <!DOCTYPE html> + HTML 4 Strict html4-strict <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" "http://www.w3.org/TR/html4/strict.dtd"> + HTML 4 Transitional html4-trans <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd"> + HTML 4 Frameset html4-frame <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Frameset//EN" "http://www.w3.org/TR/html4/frameset.dtd"> + MathML 1.01 mathml1 <!DOCTYPE math SYSTEM "http://www.w3.org/Math/DTD/mathml1/mathml.dtd"> + MathML 2.0 mathml2 <!DOCTYPE math PUBLIC "-//W3C//DTD MathML 2.0//EN" "http://www.w3.org/Math/DTD/mathml2/mathml2.dtd"> + SVG 1.0 svg10 <!DOCTYPE svg PUBLIC "-//W3C//DTD SVG 1.0//EN" "http://www.w3.org/TR/2001/REC-SVG-20010904/DTD/svg10.dtd"> + SVG 1.1 Full svg11 <!DOCTYPE svg PUBLIC "-//W3C//DTD SVG 1.1//EN" "http://www.w3.org/Graphics/SVG/1.1/DTD/svg11.dtd"> + SVG 1.1 Basic svg11-basic <!DOCTYPE svg PUBLIC "-//W3C//DTD SVG 1.1 Basic//EN" "http://www.w3.org/Graphics/SVG/1.1/DTD/svg11-basic.dtd"> + SVG 1.1 Tiny svg11-tiny <!DOCTYPE svg PUBLIC "-//W3C//DTD SVG 1.1 Tiny//EN" "http://www.w3.org/Graphics/SVG/1.1/DTD/svg11-tiny.dtd"> + XHTML+MathML+SVG (XHTML host) xhtml-math-svg-xh <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1 plus MathML 2.0 plus SVG 1.1//EN" "http://www.w3.org/2002/04/xhtml-math-svg/xhtml-math-svg.dtd"> + XHTML+MathML+SVG (SVG host) xhtml-math-svg-sh <!DOCTYPE svg:svg PUBLIC "-//W3C//DTD XHTML 1.1 plus MathML 2.0 plus SVG 1.1//EN" "http://www.w3.org/2002/04/xhtml-math-svg/xhtml-math-svg.dtd"> + XHTML+RDFa 1.0 xhtml-rdfa-1 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML+RDFa 1.0//EN" "http://www.w3.org/MarkUp/DTD/xhtml-rdfa-1.dtd"> + XHTML+RDFa 1.1 xhtml-rdfa-2 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML+RDFa 1.1//EN" "http://www.w3.org/MarkUp/DTD/xhtml-rdfa-2.dtd"> + =============================== =================== ==================================================================================================================================================
\ No newline at end of file diff --git a/user_guide_src/source/helpers/inflector_helper.rst b/user_guide_src/source/helpers/inflector_helper.rst index 1f54b76c0..d0cb17c18 100644 --- a/user_guide_src/source/helpers/inflector_helper.rst +++ b/user_guide_src/source/helpers/inflector_helper.rst @@ -5,7 +5,12 @@ Inflector Helper The Inflector Helper file contains functions that permits you to change words to plural, singular, camel case, etc. -.. contents:: Page Contents +.. contents:: + :local: + +.. raw:: html + + <div class="custom-index container"></div> Loading this Helper =================== @@ -14,86 +19,78 @@ This helper is loaded using the following code:: $this->load->helper('inflector'); +Available Functions +=================== + The following functions are available: -singular() -========== -.. php:function:: singular($str) +.. function:: singular($str) :param string $str: Input string - :returns: string - -Changes a plural word to singular. Example:: + :returns: A singular word + :rtype: string - echo singular('dogs'); // Prints 'dog' + Changes a plural word to singular. Example:: -plural() -======== + echo singular('dogs'); // Prints 'dog' -.. php:function:: plural($str) +.. function:: plural($str) :param string $str: Input string - :returns: string + :returns: A plular word + :rtype: string -Changes a singular word to plural. Example:: + Changes a singular word to plural. Example:: - echo plural('dog'); // Prints 'dogs' + echo plural('dog'); // Prints 'dogs' -camelize() -========== - -.. php:function:: camelize($str) +.. function:: camelize($str) :param string $str: Input string - :returns: string - -Changes a string of words separated by spaces or underscores to camel -case. Example:: + :returns: Camelized string + :rtype: string - echo camelize('my_dog_spot'); // Prints 'myDogSpot' + Changes a string of words separated by spaces or underscores to camel + case. Example:: -underscore() -============ + echo camelize('my_dog_spot'); // Prints 'myDogSpot' -.. php:function:: camelize($str) +.. function:: underscore($str) :param string $str: Input string - :returns: string + :returns: String containing underscores instead of spaces + :rtype: string -Takes multiple words separated by spaces and underscores them. -Example:: + Takes multiple words separated by spaces and underscores them. + Example:: - echo underscore('my dog spot'); // Prints 'my_dog_spot' + echo underscore('my dog spot'); // Prints 'my_dog_spot' -humanize() -========== - -.. php:function:: camelize($str) +.. function:: humanize($str[, $separator = '_']) :param string $str: Input string :param string $separator: Input separator - :returns: string - -Takes multiple words separated by underscores and adds spaces between -them. Each word is capitalized. + :returns: Humanized string + :rtype: string -Example:: + Takes multiple words separated by underscores and adds spaces between + them. Each word is capitalized. - echo humanize('my_dog_spot'); // Prints 'My Dog Spot' + Example:: -To use dashes instead of underscores:: + echo humanize('my_dog_spot'); // Prints 'My Dog Spot' - echo humanize('my-dog-spot', '-'); // Prints 'My Dog Spot' + To use dashes instead of underscores:: -is_countable() -============== + echo humanize('my-dog-spot', '-'); // Prints 'My Dog Spot' -.. php:function:: is_countable($word) +.. function:: is_countable($word) :param string $word: Input string - :returns: bool + :returns: TRUE if the word is countable or FALSE if not + :rtype: bool -Checks if the given word has a plural version. Example:: + Checks if the given word has a plural version. Example:: - is_countable('equipment'); // Returns FALSE
\ No newline at end of file + is_countable('equipment'); // Returns FALSE
\ No newline at end of file diff --git a/user_guide_src/source/helpers/language_helper.rst b/user_guide_src/source/helpers/language_helper.rst index 1911e3bfd..e4d093725 100644 --- a/user_guide_src/source/helpers/language_helper.rst +++ b/user_guide_src/source/helpers/language_helper.rst @@ -5,7 +5,12 @@ Language Helper The Language Helper file contains functions that assist in working with language files. -.. contents:: Page Contents +.. contents:: + :local: + +.. raw:: html + + <div class="custom-index container"></div> Loading this Helper =================== @@ -14,23 +19,25 @@ This helper is loaded using the following code:: $this->load->helper('language'); +Available Functions +=================== + The following functions are available: -lang() -====== -.. php:function:: lang($line, $for = '', $attributes = array()) +.. function:: lang($line[, $for = ''[, $attributes = array()]]) - :param string $line: Language line key - :param string $for: HTML "for" attribute (ID of the element we're creating a label for) - :param array $attributes: Any additional HTML attributes - :returns: string + :param string $line: Language line key + :param string $for: HTML "for" attribute (ID of the element we're creating a label for) + :param array $attributes: Any additional HTML attributes + :returns: HTML-formatted language line label + :rtype: string -This function returns a line of text from a loaded language file with -simplified syntax that may be more desirable for view files than -``CI_Lang::line()``. + This function returns a line of text from a loaded language file with + simplified syntax that may be more desirable for view files than + ``CI_Lang::line()``. -Example:: + Example:: - echo lang('language_key', 'form_item_id', array('class' => 'myClass'); - // Outputs: <label for="form_item_id" class="myClass">Language line</label>
\ No newline at end of file + echo lang('language_key', 'form_item_id', array('class' => 'myClass')); + // Outputs: <label for="form_item_id" class="myClass">Language line</label>
\ No newline at end of file diff --git a/user_guide_src/source/helpers/number_helper.rst b/user_guide_src/source/helpers/number_helper.rst index 8e0ebda5e..2de4457d9 100644 --- a/user_guide_src/source/helpers/number_helper.rst +++ b/user_guide_src/source/helpers/number_helper.rst @@ -5,7 +5,12 @@ Number Helper The Number Helper file contains functions that help you work with numeric data. -.. contents:: Page Contents +.. contents:: + :local: + +.. raw:: html + + <div class="custom-index container"></div> Loading this Helper =================== @@ -14,32 +19,34 @@ This helper is loaded using the following code:: $this->load->helper('number'); +Available Functions +=================== + The following functions are available: -byte_format() -============= -.. php:function:: byte_format($num, $precision = 1) +.. function:: byte_format($num[, $precision = 1]) :param mixed $num: Number of bytes :param int $precision: Floating point precision - :returns: string - -Formats numbers as bytes, based on size, and adds the appropriate -suffix. Examples:: - - echo byte_format(456); // Returns 456 Bytes - echo byte_format(4567); // Returns 4.5 KB - echo byte_format(45678); // Returns 44.6 KB - echo byte_format(456789); // Returns 447.8 KB - echo byte_format(3456789); // Returns 3.3 MB - echo byte_format(12345678912345); // Returns 1.8 GB - echo byte_format(123456789123456789); // Returns 11,228.3 TB - -An optional second parameter allows you to set the precision of the -result:: - - echo byte_format(45678, 2); // Returns 44.61 KB - -.. note:: The text generated by this function is found in the following - language file: `language/<your_lang>/number_lang.php`
\ No newline at end of file + :returns: Formatted data size string + :rtype: string + + Formats numbers as bytes, based on size, and adds the appropriate + suffix. Examples:: + + echo byte_format(456); // Returns 456 Bytes + echo byte_format(4567); // Returns 4.5 KB + echo byte_format(45678); // Returns 44.6 KB + echo byte_format(456789); // Returns 447.8 KB + echo byte_format(3456789); // Returns 3.3 MB + echo byte_format(12345678912345); // Returns 1.8 GB + echo byte_format(123456789123456789); // Returns 11,228.3 TB + + An optional second parameter allows you to set the precision of the + result:: + + echo byte_format(45678, 2); // Returns 44.61 KB + + .. note:: The text generated by this function is found in the following + language file: *language/<your_lang>/number_lang.php*
\ No newline at end of file diff --git a/user_guide_src/source/helpers/path_helper.rst b/user_guide_src/source/helpers/path_helper.rst index 3a271b28f..705ca23b9 100644 --- a/user_guide_src/source/helpers/path_helper.rst +++ b/user_guide_src/source/helpers/path_helper.rst @@ -5,7 +5,12 @@ Path Helper The Path Helper file contains functions that permits you to work with file paths on the server. -.. contents:: Page Contents +.. contents:: + :local: + +.. raw:: html + + <div class="custom-index container"></div> Loading this Helper =================== @@ -14,33 +19,35 @@ This helper is loaded using the following code:: $this->load->helper('path'); +Available Functions +=================== + The following functions are available: -set_realpath() -============== -.. php:function:: set_realpath($path, $check_existance = FALSE) +.. function:: set_realpath($path[, $check_existance = FALSE]) :param string $path: Path :param bool $check_existance: Whether to check if the path actually exists - :returns: string + :returns: An absolute path + :rtype: string + + This function will return a server path without symbolic links or + relative directory structures. An optional second argument will + cause an error to be triggered if the path cannot be resolved. -This function will return a server path without symbolic links or -relative directory structures. An optional second argument will -cause an error to be triggered if the path cannot be resolved. + Examples:: -Examples:: + $file = '/etc/php5/apache2/php.ini'; + echo set_realpath($file); // Prints '/etc/php5/apache2/php.ini' - $file = '/etc/php5/apache2/php.ini'; - echo set_realpath($file); // Prints '/etc/php5/apache2/php.ini' + $non_existent_file = '/path/to/non-exist-file.txt'; + echo set_realpath($non_existent_file, TRUE); // Shows an error, as the path cannot be resolved + echo set_realpath($non_existent_file, FALSE); // Prints '/path/to/non-exist-file.txt' - $non_existent_file = '/path/to/non-exist-file.txt'; - echo set_realpath($non_existent_file, TRUE); // Shows an error, as the path cannot be resolved - echo set_realpath($non_existent_file, FALSE); // Prints '/path/to/non-exist-file.txt' + $directory = '/etc/php5'; + echo set_realpath($directory); // Prints '/etc/php5/' - $directory = '/etc/php5'; - echo set_realpath($directory); // Prints '/etc/php5/' - - $non_existent_directory = '/path/to/nowhere'; - echo set_realpath($non_existent_directory, TRUE); // Shows an error, as the path cannot be resolved - echo set_realpath($non_existent_directory, FALSE); // Prints '/path/to/nowhere'
\ No newline at end of file + $non_existent_directory = '/path/to/nowhere'; + echo set_realpath($non_existent_directory, TRUE); // Shows an error, as the path cannot be resolved + echo set_realpath($non_existent_directory, FALSE); // Prints '/path/to/nowhere'
\ No newline at end of file diff --git a/user_guide_src/source/helpers/security_helper.rst b/user_guide_src/source/helpers/security_helper.rst index 21bf53490..2e26890b0 100644 --- a/user_guide_src/source/helpers/security_helper.rst +++ b/user_guide_src/source/helpers/security_helper.rst @@ -4,7 +4,12 @@ Security Helper The Security Helper file contains security related functions. -.. contents:: Page Contents +.. contents:: + :local: + +.. raw:: html + + <div class="custom-index container"></div> Loading this Helper =================== @@ -13,92 +18,89 @@ This helper is loaded using the following code:: $this->load->helper('security'); +Available Functions +=================== + The following functions are available: -xss_clean() -=========== -.. php:function:: xss_clean($str, $is_image = FALSE) +.. function:: xss_clean($str[, $is_image = FALSE]) :param string $str: Input data :param bool $is_image: Whether we're dealing with an image - :returns: string + :returns: XSS-clean string + :rtype: string -Provides Cross Site Script Hack filtering. + Provides Cross Site Script Hack filtering. -This function is an alias for ``CI_Input::xss_clean()``. For more info, -please see the :doc:`Input Library <../libraries/input>` documentation. + This function is an alias for ``CI_Input::xss_clean()``. For more info, + please see the :doc:`Input Library <../libraries/input>` documentation. -sanitize_filename() -=================== - -.. php:function:: sanitize_filename($filename) +.. function:: sanitize_filename($filename) :param string $filename: Filename - :returns: string + :returns: Sanitized file name + :rtype: string -Provides protection against directory traversal. + Provides protection against directory traversal. -This function is an alias for ``CI_Security::sanitize_filename()``. -For more info, please see the :doc:`Security Library <../libraries/security>` -documentation. + This function is an alias for ``CI_Security::sanitize_filename()``. + For more info, please see the :doc:`Security Library <../libraries/security>` + documentation. -do_hash() -========= -.. php:function:: do_hash($str, $type = 'sha1') +.. function:: do_hash($str[, $type = 'sha1']) :param string $str: Input :param string $type: Algorithm - :returns: string + :returns: Hex-formatted hash + :rtype: string -Permits you to create one way hashes suitable for encrypting -passwords. Will use SHA1 by default. + Permits you to create one way hashes suitable for encrypting + passwords. Will use SHA1 by default. -See `hash_algos() <http://php.net/function.hash_algos>`_ -for a full list of supported algorithms. + See `hash_algos() <http://php.net/function.hash_algos>`_ + for a full list of supported algorithms. -Examples:: + Examples:: - $str = do_hash($str); // SHA1 - $str = do_hash($str, 'md5'); // MD5 + $str = do_hash($str); // SHA1 + $str = do_hash($str, 'md5'); // MD5 -.. note:: This function was formerly named ``dohash()``, which has been - removed in favor of ``do_hash()``. + .. note:: This function was formerly named ``dohash()``, which has been + removed in favor of ``do_hash()``. -.. note:: This function is DEPRECATED. Use the native ``hash()`` instead. + .. note:: This function is DEPRECATED. Use the native ``hash()`` instead. -strip_image_tags() -================== -.. php:function:: strip_image_tags($str) +.. function:: strip_image_tags($str) - :param string $str: Input - :returns: string + :param string $str: Input string + :returns: The input string with no image tags + :rtype: string -This is a security function that will strip image tags from a string. -It leaves the image URL as plain text. + This is a security function that will strip image tags from a string. + It leaves the image URL as plain text. -Example:: + Example:: - $string = strip_image_tags($string); + $string = strip_image_tags($string); -This function is an alias for ``CI_Security::strip_image_tags()``. For -more info, please see the :doc:`Security Library <../libraries/security>` -documentation. + This function is an alias for ``CI_Security::strip_image_tags()``. For + more info, please see the :doc:`Security Library <../libraries/security>` + documentation. -encode_php_tags() -================= -.. php:function:: encode_php_tags($str) +.. function:: encode_php_tags($str) - :param string $str: Input - :returns: string + :param string $str: Input string + :returns: Safely formatted string + :rtype: string -This is a security function that converts PHP tags to entities. + This is a security function that converts PHP tags to entities. -.. note: :php:func:`xss_clean()` does this automatically, if you use it. + .. note:: :func:`xss_clean()` does this automatically, if you use it. -Example:: + Example:: - $string = encode_php_tags($string);
\ No newline at end of file + $string = encode_php_tags($string);
\ No newline at end of file diff --git a/user_guide_src/source/helpers/smiley_helper.rst b/user_guide_src/source/helpers/smiley_helper.rst index cfd52ffbc..b98084089 100644 --- a/user_guide_src/source/helpers/smiley_helper.rst +++ b/user_guide_src/source/helpers/smiley_helper.rst @@ -5,7 +5,12 @@ Smiley Helper The Smiley Helper file contains functions that let you manage smileys (emoticons). -.. contents:: Page Contents +.. contents:: + :local: + +.. raw:: html + + <div class="custom-index container"></div> Loading this Helper =================== @@ -46,7 +51,7 @@ The Controller In your **application/controllers/** directory, create a file called Smileys.php and place the code below in it. -.. important:: Change the URL in the :php:func:`get_clickable_smileys()` +.. important:: Change the URL in the :func:`get_clickable_smileys()` function below so that it points to your smiley folder. You'll notice that in addition to the smiley helper, we are also using @@ -100,65 +105,62 @@ links a generic name that will be tied to a specific id in your view. $image_array = get_smiley_links("http://example.com/images/smileys/", "comment_textarea_alias"); To map the alias to the field id, pass them both into the -:php:func:`smiley_js()` function:: +:func:`smiley_js()` function:: $image_array = smiley_js("comment_textarea_alias", "comments"); -get_clickable_smileys() -======================= +Available Functions +=================== -.. php:function:: get_clickable_smileys($image_url, $alias = '', $smileys = NULL) +.. function:: get_clickable_smileys($image_url[, $alias = ''[, $smileys = NULL]]) :param string $image_url: URL path to the smileys directory :param string $alias: Field alias - :returns: array + :returns: An array of ready to use smileys + :rtype: array -Returns an array containing your smiley images wrapped in a clickable -link. You must supply the URL to your smiley folder and a field id or -field alias. + Returns an array containing your smiley images wrapped in a clickable + link. You must supply the URL to your smiley folder and a field id or + field alias. -Example:: + Example:: - $image_array = get_smiley_links("http://example.com/images/smileys/", "comment"); + $image_array = get_clickable_smileys('http://example.com/images/smileys/', 'comment'); -smiley_js() -=========== - -.. php:function:: smiley_js($alias = '', $field_id = '', $inline = TRUE) +.. function:: smiley_js([$alias = ''[, $field_id = ''[, $inline = TRUE]]]) :param string $alias: Field alias :param string $field_id: Field ID :param bool $inline: Whether we're inserting an inline smiley + :returns: Smiley-enabling JavaScript code + :rtype: string -Generates the JavaScript that allows the images to be clicked and -inserted into a form field. If you supplied an alias instead of an id -when generating your smiley links, you need to pass the alias and -corresponding form id into the function. This function is designed to be -placed into the <head> area of your web page. - -Example:: + Generates the JavaScript that allows the images to be clicked and + inserted into a form field. If you supplied an alias instead of an id + when generating your smiley links, you need to pass the alias and + corresponding form id into the function. This function is designed to be + placed into the <head> area of your web page. - <?php echo smiley_js(); ?> + Example:: -parse_smileys() -=============== + <?php echo smiley_js(); ?> -.. php:function:: parse_smileys($str = '', $image_url = '', $smileys = NULL) +.. function:: parse_smileys([$str = ''[, $image_url = ''[, $smileys = NULL]]]) :param string $str: Text containing smiley codes :param string $image_url: URL path to the smileys directory :param array $smileys: An array of smileys - :returns: string - -Takes a string of text as input and replaces any contained plain text -smileys into the image equivalent. The first parameter must contain your -string, the second must contain the URL to your smiley folder + :returns: Parsed smileys + :rtype: string -Example:: + Takes a string of text as input and replaces any contained plain text + smileys into the image equivalent. The first parameter must contain your + string, the second must contain the URL to your smiley folder - $str = 'Here are some smileys: :-) ;-)'; - $str = parse_smileys($str, "http://example.com/images/smileys/"); - echo $str; + Example:: + $str = 'Here are some smileys: :-) ;-)'; + $str = parse_smileys($str, 'http://example.com/images/smileys/'); + echo $str; .. |smile!| image:: ../images/smile.gif
\ No newline at end of file diff --git a/user_guide_src/source/helpers/string_helper.rst b/user_guide_src/source/helpers/string_helper.rst index d0d302476..922bc6b8d 100644 --- a/user_guide_src/source/helpers/string_helper.rst +++ b/user_guide_src/source/helpers/string_helper.rst @@ -5,7 +5,12 @@ String Helper The String Helper file contains functions that assist in working with strings. -.. contents:: Page Contents +.. contents:: + :local: + +.. raw:: html + + <div class="custom-index container"></div> Loading this Helper =================== @@ -14,214 +19,202 @@ This helper is loaded using the following code:: $this->load->helper('string'); +Available Functions +=================== + The following functions are available: -random_string() -=============== -.. php:function:: random_string($type = 'alnum', $len = 8) +.. function:: random_string([$type = 'alnum'[, $len = 8]]) :param string $type: Randomization type :param int $len: Output string length - :returns: string - -Generates a random string based on the type and length you specify. -Useful for creating passwords or generating random hashes. + :returns: A random string + :rtype: string -The first parameter specifies the type of string, the second parameter -specifies the length. The following choices are available: + Generates a random string based on the type and length you specify. + Useful for creating passwords or generating random hashes. -- **alpha**: A string with lower and uppercase letters only. -- **alnum**: Alpha-numeric string with lower and uppercase characters. -- **basic**: A random number based on ``mt_rand()``. -- **numeric**: Numeric string. -- **nozero**: Numeric string with no zeros. -- **md5**: An encrypted random number based on ``md5()`` (fixed length of 32). -- **sha1**: An encrypted random number based on ``sha1()`` (fixed length of 40). + The first parameter specifies the type of string, the second parameter + specifies the length. The following choices are available: -Usage example:: + - **alpha**: A string with lower and uppercase letters only. + - **alnum**: Alpha-numeric string with lower and uppercase characters. + - **basic**: A random number based on ``mt_rand()``. + - **numeric**: Numeric string. + - **nozero**: Numeric string with no zeros. + - **md5**: An encrypted random number based on ``md5()`` (fixed length of 32). + - **sha1**: An encrypted random number based on ``sha1()`` (fixed length of 40). - echo random_string('alnum', 16); + Usage example:: -.. note:: Usage of the *unique* and *encrypt* types is DEPRECATED. They - are just aliases for *md5* and *sha1* respectively. + echo random_string('alnum', 16); -increment_string() -================== + .. note:: Usage of the *unique* and *encrypt* types is DEPRECATED. They + are just aliases for *md5* and *sha1* respectively. -.. php:function:: increment_string($str, $separator = '_', $first = 1) +.. function:: increment_string($str[, $separator = '_'[, $first = 1]]) :param string $str: Input string :param string $separator: Separator to append a duplicate number with :param int $first: Starting number - :returns: string + :returns: An incremented string + :rtype: string -Increments a string by appending a number to it or increasing the -number. Useful for creating "copies" or a file or duplicating database -content which has unique titles or slugs. + Increments a string by appending a number to it or increasing the + number. Useful for creating "copies" or a file or duplicating database + content which has unique titles or slugs. -Usage example:: + Usage example:: - echo increment_string('file', '_'); // "file_1" - echo increment_string('file', '-', 2); // "file-2" - echo increment_string('file_4'); // "file_5" + echo increment_string('file', '_'); // "file_1" + echo increment_string('file', '-', 2); // "file-2" + echo increment_string('file_4'); // "file_5" -alternator() -============ -.. php:function:: alternator($args) +.. function:: alternator($args) :param mixed $args: A variable number of arguments - :returns: mixed + :returns: Alternated string(s) + :rtype: mixed -Allows two or more items to be alternated between, when cycling through -a loop. Example:: + Allows two or more items to be alternated between, when cycling through + a loop. Example:: - for ($i = 0; $i < 10; $i++) - { - echo alternator('string one', 'string two'); - } + for ($i = 0; $i < 10; $i++) + { + echo alternator('string one', 'string two'); + } -You can add as many parameters as you want, and with each iteration of -your loop the next item will be returned. + You can add as many parameters as you want, and with each iteration of + your loop the next item will be returned. -:: + :: - for ($i = 0; $i < 10; $i++) - { - echo alternator('one', 'two', 'three', 'four', 'five'); - } + for ($i = 0; $i < 10; $i++) + { + echo alternator('one', 'two', 'three', 'four', 'five'); + } -.. note:: To use multiple separate calls to this function simply call the - function with no arguments to re-initialize. + .. note:: To use multiple separate calls to this function simply call the + function with no arguments to re-initialize. -repeater() -========== - -.. php:function:: repeater($data, $num = 1) +.. function:: repeater($data[, $num = 1]) :param string $data: Input :param int $num: Number of times to repeat - :returns: string + :returns: Repeated string + :rtype: string -Generates repeating copies of the data you submit. Example:: + Generates repeating copies of the data you submit. Example:: - $string = "\n"; - echo repeater($string, 30); + $string = "\n"; + echo repeater($string, 30); -The above would generate 30 newlines. + The above would generate 30 newlines. -.. note:: This function is DEPRECATED. Use the native ``str_repeat()`` - instead. + .. note:: This function is DEPRECATED. Use the native ``str_repeat()`` + instead. -reduce_double_slashes() -======================= -.. php:function:: reduce_double_slashes($str) +.. function:: reduce_double_slashes($str) :param string $str: Input string - :returns: string + :returns: A string with normalized slashes + :rtype: string -Converts double slashes in a string to a single slash, except those -found in URL protocol prefixes (e.g. http://). + Converts double slashes in a string to a single slash, except those + found in URL protocol prefixes (e.g. http://). -Example:: + Example:: - $string = "http://example.com//index.php"; - echo reduce_double_slashes($string); // results in "http://example.com/index.php" + $string = "http://example.com//index.php"; + echo reduce_double_slashes($string); // results in "http://example.com/index.php" -strip_slashes() -=============== -.. php:function:: strip_slashes($data) +.. function:: strip_slashes($data) - :param array $data: Input - :returns: array + :param mixed $data: Input string or an array of strings + :returns: String(s) with stripped slashes + :rtype: mixed -Removes any slashes from an array of strings. + Removes any slashes from an array of strings. -Example:: - - $str = array( - 'question' => 'Is your name O\'reilly?', - 'answer' => 'No, my name is O\'connor.' - ); - - $str = strip_slashes($str); - -The above will return the following array:: + Example:: - array( - 'question' => "Is your name O'reilly?", - 'answer' => "No, my name is O'connor." - ); + $str = array( + 'question' => 'Is your name O\'reilly?', + 'answer' => 'No, my name is O\'connor.' + ); -.. note:: For historical reasons, this function will also accept - and handle string inputs. This however makes it just an - alias for ``stripslashes()``. + $str = strip_slashes($str); -trim_slashes() -============== + The above will return the following array:: -.. php:function:: trim_slashes($str) + array( + 'question' => "Is your name O'reilly?", + 'answer' => "No, my name is O'connor." + ); - :param string $str: Input string - :returns: string + .. note:: For historical reasons, this function will also accept + and handle string inputs. This however makes it just an + alias for ``stripslashes()``. -Removes any leading/trailing slashes from a string. Example:: +.. function:: trim_slashes($str) - $string = "/this/that/theother/"; - echo trim_slashes($string); // results in this/that/theother + :param string $str: Input string + :returns: Slash-trimmed string + :rtype: string -.. note:: This function is DEPRECATED. Use the native ``trim()`` instead: - | - | trim($str, '/'); + Removes any leading/trailing slashes from a string. Example:: -reduce_multiples() -================== + $string = "/this/that/theother/"; + echo trim_slashes($string); // results in this/that/theother -.. php:function:: reduce_multiples($str, $character = '', $trim = FALSE) + .. note:: This function is DEPRECATED. Use the native ``trim()`` instead: + | + | trim($str, '/'); + +.. function:: reduce_multiples($str[, $character = ''[, $trim = FALSE]]) :param string $str: Text to search in :param string $character: Character to reduce :param bool $trim: Whether to also trim the specified character - :returns: string - -Reduces multiple instances of a particular character occuring directly -after each other. Example:: + :returns: Reduced string + :rtype: string - $string = "Fred, Bill,, Joe, Jimmy"; - $string = reduce_multiples($string,","); //results in "Fred, Bill, Joe, Jimmy" + Reduces multiple instances of a particular character occuring directly + after each other. Example:: -If the third parameter is set to TRUE it will remove occurences of the -character at the beginning and the end of the string. Example:: + $string = "Fred, Bill,, Joe, Jimmy"; + $string = reduce_multiples($string,","); //results in "Fred, Bill, Joe, Jimmy" - $string = ",Fred, Bill,, Joe, Jimmy,"; - $string = reduce_multiples($string, ", ", TRUE); //results in "Fred, Bill, Joe, Jimmy" + If the third parameter is set to TRUE it will remove occurrences of the + character at the beginning and the end of the string. Example:: -quotes_to_entities() -==================== + $string = ",Fred, Bill,, Joe, Jimmy,"; + $string = reduce_multiples($string, ", ", TRUE); //results in "Fred, Bill, Joe, Jimmy" -.. php:function:: quotes_to_entities($str) +.. function:: quotes_to_entities($str) :param string $str: Input string - :returns: string + :returns: String with quotes converted to HTML entities + :rtype: string -Converts single and double quotes in a string to the corresponding HTML -entities. Example:: + Converts single and double quotes in a string to the corresponding HTML + entities. Example:: - $string = "Joe's \"dinner\""; - $string = quotes_to_entities($string); //results in "Joe's "dinner"" + $string = "Joe's \"dinner\""; + $string = quotes_to_entities($string); //results in "Joe's "dinner"" -strip_quotes() -============== -.. php:function:: strip_quotes($str) +.. function:: strip_quotes($str) :param string $str: Input string - :returns: string + :returns: String with quotes stripped + :rtype: string -Removes single and double quotes from a string. Example:: + Removes single and double quotes from a string. Example:: - $string = "Joe's \"dinner\""; - $string = strip_quotes($string); //results in "Joes dinner"
\ No newline at end of file + $string = "Joe's \"dinner\""; + $string = strip_quotes($string); //results in "Joes dinner"
\ No newline at end of file diff --git a/user_guide_src/source/helpers/text_helper.rst b/user_guide_src/source/helpers/text_helper.rst index aec36c9a7..88a6d0658 100644 --- a/user_guide_src/source/helpers/text_helper.rst +++ b/user_guide_src/source/helpers/text_helper.rst @@ -5,7 +5,12 @@ Text Helper The Text Helper file contains functions that assist in working with text. -.. contents:: Page Contents +.. contents:: + :local: + +.. raw:: html + + <div class="custom-index container"></div> Loading this Helper =================== @@ -14,216 +19,208 @@ This helper is loaded using the following code:: $this->load->helper('text'); -The following functions are available: +Available Functions +=================== -word_limiter() -============== +The following functions are available: -.. php:function:: word_limiter($str, $limit = 100, $end_char = '…') +.. function:: word_limiter($str[, $limit = 100[, $end_char = '…']]) :param string $str: Input string :param int $limit: Limit :param string $end_char: End character (usually an ellipsis) - :returns: string + :returns: Word-limited string + :rtype: string -Truncates a string to the number of *words* specified. Example:: + Truncates a string to the number of *words* specified. Example:: - $string = "Here is a nice text string consisting of eleven words."; - $string = word_limiter($string, 4); - // Returns: Here is a nice… + $string = "Here is a nice text string consisting of eleven words."; + $string = word_limiter($string, 4); + // Returns: Here is a nice -The third parameter is an optional suffix added to the string. By -default it adds an ellipsis. + The third parameter is an optional suffix added to the string. By + default it adds an ellipsis. -character_limiter() -=================== -.. php:function:: character_limiter($str, $n = 500, $end_char = '…') +.. function:: character_limiter($str[, $n = 500[, $end_char = '…']]) :param string $str: Input string :param int $n: Number of characters :param string $end_char: End character (usually an ellipsis) - :returns: string + :returns: Character-limited string + :rtype: string -Truncates a string to the number of *characters* specified. It -maintains the integrity of words so the character count may be slightly -more or less then what you specify. + Truncates a string to the number of *characters* specified. It + maintains the integrity of words so the character count may be slightly + more or less than what you specify. -Example:: + Example:: - $string = "Here is a nice text string consisting of eleven words."; - $string = character_limiter($string, 20); - // Returns: Here is a nice text string… + $string = "Here is a nice text string consisting of eleven words."; + $string = character_limiter($string, 20); + // Returns: Here is a nice text string -The third parameter is an optional suffix added to the string, if -undeclared this helper uses an ellipsis. + The third parameter is an optional suffix added to the string, if + undeclared this helper uses an ellipsis. -.. note:: If you need to truncate to an exact number of characters please - see the :ref:`ellipsize()` function below. - -ascii_to_entities() -=================== + .. note:: If you need to truncate to an exact number of characters please + see the :func:`ellipsize()` function below. -.. php:function:: ascii_to_entities($str) +.. function:: ascii_to_entities($str) :param string $str: Input string - :returns: string + :returns: A string with ASCII values converted to entities + :rtype: string -Converts ASCII values to character entities, including high ASCII and MS -Word characters that can cause problems when used in a web page, so that -they can be shown consistently regardless of browser settings or stored -reliably in a database. There is some dependence on your server's -supported character sets, so it may not be 100% reliable in all cases, -but for the most part it should correctly identify characters outside -the normal range (like accented characters). + Converts ASCII values to character entities, including high ASCII and MS + Word characters that can cause problems when used in a web page, so that + they can be shown consistently regardless of browser settings or stored + reliably in a database. There is some dependence on your server's + supported character sets, so it may not be 100% reliable in all cases, + but for the most part it should correctly identify characters outside + the normal range (like accented characters). -Example:: + Example:: - $string = ascii_to_entities($string); + $string = ascii_to_entities($string); -entities_to_ascii() -=================== - -.. php:function::entities_to_ascii($str, $all = TRUE) +.. function::entities_to_ascii($str[, $all = TRUE]) :param string $str: Input string :param bool $all: Whether to convert unsafe entities as well - :returns: string + :returns: A string with HTML entities converted to ASCII characters + :rtype: string -This function does the opposite of :php:func:`ascii_to_entities()`. -It turns character entities back into ASCII. + This function does the opposite of :func:`ascii_to_entities()`. + It turns character entities back into ASCII. -convert_accented_characters() -============================= - -.. php:function:: convert_accented_characters($str) +.. function:: convert_accented_characters($str) :param string $str: Input string - :returns: string - -Transliterates high ASCII characters to low ASCII equivalents. Useful -when non-English characters need to be used where only standard ASCII -characters are safely used, for instance, in URLs. + :returns: A string with accented characters converted + :rtype: string -Example:: + Transliterates high ASCII characters to low ASCII equivalents. Useful + when non-English characters need to be used where only standard ASCII + characters are safely used, for instance, in URLs. - $string = convert_accented_characters($string); + Example:: -.. note:: This function uses a companion config file - `application/config/foreign_chars.php` to define the to and - from array for transliteration. + $string = convert_accented_characters($string); -word_censor() -============= + .. note:: This function uses a companion config file + `application/config/foreign_chars.php` to define the to and + from array for transliteration. -.. php:function:: word_censor($str, $censored, $replacement = '') +.. function:: word_censor($str, $censored[, $replacement = '']) :param string $str: Input string :param array $censored: List of bad words to censor :param string $replacement: What to replace bad words with - :returns: string + :returns: Censored string + :rtype: string -Enables you to censor words within a text string. The first parameter -will contain the original string. The second will contain an array of -words which you disallow. The third (optional) parameter can contain -a replacement value for the words. If not specified they are replaced -with pound signs: ####. + Enables you to censor words within a text string. The first parameter + will contain the original string. The second will contain an array of + words which you disallow. The third (optional) parameter can contain + a replacement value for the words. If not specified they are replaced + with pound signs: ####. -Example:: + Example:: - $disallowed = array('darn', 'shucks', 'golly', 'phooey'); - $string = word_censor($string, $disallowed, 'Beep!'); + $disallowed = array('darn', 'shucks', 'golly', 'phooey'); + $string = word_censor($string, $disallowed, 'Beep!'); -highlight_code() -================ - -.. php:function:: highlight_code($str) +.. function:: highlight_code($str) :param string $str: Input string - :returns: string + :returns: String with code highlighted via HTML + :rtype: string -Colorizes a string of code (PHP, HTML, etc.). Example:: + Colorizes a string of code (PHP, HTML, etc.). Example:: - $string = highlight_code($string); + $string = highlight_code($string); -The function uses PHP's ``highlight_string()`` function, so the -colors used are the ones specified in your php.ini file. + The function uses PHP's ``highlight_string()`` function, so the + colors used are the ones specified in your php.ini file. -highlight_phrase() -================== -.. php:function:: highlight_phrase($str, $phrase, $tag_open = '<strong>', $tag_close = '</strong>') +.. function:: highlight_phrase($str, $phrase[, $tag_open = '<mark>'[, $tag_close = '</mark>']]) :param string $str: Input string :param string $phrase: Phrase to highlight :param string $tag_open: Opening tag used for the highlight :param string $tag_close: Closing tag for the highlight - :returns: string + :returns: String with a phrase highlighted via HTML + :rtype: string + + Will highlight a phrase within a text string. The first parameter will + contain the original string, the second will contain the phrase you wish + to highlight. The third and fourth parameters will contain the + opening/closing HTML tags you would like the phrase wrapped in. -Will highlight a phrase within a text string. The first parameter will -contain the original string, the second will contain the phrase you wish -to highlight. The third and fourth parameters will contain the -opening/closing HTML tags you would like the phrase wrapped in. + Example:: -Example:: + $string = "Here is a nice text string about nothing in particular."; + echo highlight_phrase($string, "nice text", '<span style="color:#990000;">', '</span>'); - $string = "Here is a nice text string about nothing in particular."; - echo highlight_phrase($string, "nice text", '<span style="color:#990000;">', '</span>'); + The above code prints:: -The above code prints:: + Here is a <span style="color:#990000;">nice text</span> string about nothing in particular. - Here is a <span style="color:#990000;">nice text</span> string about nothing in particular. + .. note:: This function used to use the ``<strong>`` tag by default. Older browsers + might not support the new HTML5 mark tag, so it is recommended that you + insert the following CSS code into your stylesheet if you need to support + such browsers:: -word_wrap() -=========== + mark { + background: #ff0; + color: #000; + }; -.. php:function:: word_wrap($str, $charlim = 76) +.. function:: word_wrap($str[, $charlim = 76]) :param string $str: Input string :param int $charlim: Character limit - :returns: string - -Wraps text at the specified *character* count while maintaining -complete words. - -Example:: + :returns: Word-wrapped string + :rtype: string - $string = "Here is a simple string of text that will help us demonstrate this function."; - echo word_wrap($string, 25); + Wraps text at the specified *character* count while maintaining + complete words. - // Would produce: Here is a simple string of text that will help us demonstrate this function + Example:: -.. _ellipsize(): + $string = "Here is a simple string of text that will help us demonstrate this function."; + echo word_wrap($string, 25); -ellipsize() -=========== + // Would produce: Here is a simple string of text that will help us demonstrate this function -.. php:function:: ellipsize($str, $max_length, $position = 1, $ellipsis = '…') +.. function:: ellipsize($str, $max_length[, $position = 1[, $ellipsis = '…']]) :param string $str: Input string :param int $max_length: String length limit - :param mixed $position: Position to split at - (int or float) + :param mixed $position: Position to split at (int or float) :param string $ellipsis: What to use as the ellipsis character - :returns: string + :returns: Ellipsized string + :rtype: string -This function will strip tags from a string, split it at a defined -maximum length, and insert an ellipsis. + This function will strip tags from a string, split it at a defined + maximum length, and insert an ellipsis. -The first parameter is the string to ellipsize, the second is the number -of characters in the final string. The third parameter is where in the -string the ellipsis should appear from 0 - 1, left to right. For -example. a value of 1 will place the ellipsis at the right of the -string, .5 in the middle, and 0 at the left. + The first parameter is the string to ellipsize, the second is the number + of characters in the final string. The third parameter is where in the + string the ellipsis should appear from 0 - 1, left to right. For + example. a value of 1 will place the ellipsis at the right of the + string, .5 in the middle, and 0 at the left. -An optional forth parameter is the kind of ellipsis. By default, -… will be inserted. + An optional forth parameter is the kind of ellipsis. By default, + … will be inserted. -Example:: + Example:: - $str = 'this_string_is_entirely_too_long_and_might_break_my_design.jpg'; - echo ellipsize($str, 32, .5); + $str = 'this_string_is_entirely_too_long_and_might_break_my_design.jpg'; + echo ellipsize($str, 32, .5); -Produces:: + Produces:: - this_string_is_e…ak_my_design.jpg
\ No newline at end of file + this_string_is_e…ak_my_design.jpg
\ No newline at end of file diff --git a/user_guide_src/source/helpers/typography_helper.rst b/user_guide_src/source/helpers/typography_helper.rst index 3c81687ac..deb3d164e 100644 --- a/user_guide_src/source/helpers/typography_helper.rst +++ b/user_guide_src/source/helpers/typography_helper.rst @@ -5,7 +5,12 @@ Typography Helper The Typography Helper file contains functions that help your format text in semantically relevant ways. -.. contents:: Page Contents +.. contents:: + :local: + +.. raw:: html + + <div class="custom-index container"></div> Loading this Helper =================== @@ -14,58 +19,57 @@ This helper is loaded using the following code:: $this->load->helper('typography'); +Available Functions +=================== + The following functions are available: -auto_typography() -================= -.. php:function:: auto_typography($str, $reduce_linebreaks = FALSE) +.. function:: auto_typography($str[, $reduce_linebreaks = FALSE]) :param string $str: Input string :param bool $reduce_linebreaks: Whether to reduce multiple instances of double newlines to two - :returns: string + :returns: HTML-formatted typography-safe string + :rtype: string -Formats text so that it is semantically and typographically correct -HTML. + Formats text so that it is semantically and typographically correct + HTML. -This function is an alias for ``CI_Typography::auto_typography``. -For more info, please see the :doc:`Typography Library -<../libraries/typography>` documentation. + This function is an alias for ``CI_Typography::auto_typography``. + For more info, please see the :doc:`Typography Library + <../libraries/typography>` documentation. -Usage example:: + Usage example:: - $string = auto_typography($string); + $string = auto_typography($string); -.. note:: Typographic formatting can be processor intensive, particularly if - you have a lot of content being formatted. If you choose to use this - function you may want to consider `caching <../general/caching>` your - pages. + .. note:: Typographic formatting can be processor intensive, particularly if + you have a lot of content being formatted. If you choose to use this + function you may want to consider `caching <../general/caching>` your + pages. -nl2br_except_pre() -================== -.. php:function:: nl2br_except_pre($str) +.. function:: nl2br_except_pre($str) :param string $str: Input string - :returns: string - -Converts newlines to <br /> tags unless they appear within <pre> tags. -This function is identical to the native PHP ``nl2br()`` function, -except that it ignores <pre> tags. + :returns: String with HTML-formatted line breaks + :rtype: string -Usage example:: + Converts newlines to <br /> tags unless they appear within <pre> tags. + This function is identical to the native PHP ``nl2br()`` function, + except that it ignores <pre> tags. - $string = nl2br_except_pre($string); + Usage example:: -entity_decode() -=============== + $string = nl2br_except_pre($string); -.. php:function:: entity_decode($str, $charset = NULL) +.. function:: entity_decode($str, $charset = NULL) :param string $str: Input string :param string $charset: Character set - :returns: string + :returns: String with decoded HTML entities + :rtype: string -This function is an alias for ``CI_Security::entity_decode()``. -Fore more info, please see the :doc:`Security Library -<../libraries/security>` documentation.
\ No newline at end of file + This function is an alias for ``CI_Security::entity_decode()``. + Fore more info, please see the :doc:`Security Library + <../libraries/security>` documentation.
\ No newline at end of file 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 diff --git a/user_guide_src/source/helpers/xml_helper.rst b/user_guide_src/source/helpers/xml_helper.rst index be848bcd1..a40ea9ad3 100644 --- a/user_guide_src/source/helpers/xml_helper.rst +++ b/user_guide_src/source/helpers/xml_helper.rst @@ -5,7 +5,12 @@ XML Helper The XML Helper file contains functions that assist in working with XML data. -.. contents:: Page Contents +.. contents:: + :local: + +.. raw:: html + + <div class="custom-index container"></div> Loading this Helper =================== @@ -16,23 +21,35 @@ This helper is loaded using the following code $this->load->helper('xml'); +Available Functions +=================== + The following functions are available: -xml_convert() -===================== +.. function:: xml_convert($str[, $protect_all = FALSE]) -Takes a string as input and converts the following reserved XML -characters to entities: + :param string $str: the text string to convert + :param bool $protect_all: Whether to protect all content that looks like a potential entity instead of just numbered entities, e.g. &foo; + :returns: XML-converted string + :rtype: string -- Ampersands: & -- Less then and greater than characters: < > -- Single and double quotes: ' " -- Dashes: - + Takes a string as input and converts the following reserved XML + characters to entities: -This function ignores ampersands if they are part of existing character -entities. Example + - Ampersands: & + - Less than and greater than characters: < > + - Single and double quotes: ' " + - Dashes: - -:: + This function ignores ampersands if they are part of existing numbered + character entities, e.g. {. Example:: + + $string = '<p>Here is a paragraph & an entity ({).</p>'; + $string = xml_convert($string); + echo $string; + + outputs: - $string = xml_convert($string); + .. code-block:: html + <p>Here is a paragraph & an entity ({).</p>
\ No newline at end of file |