diff options
| author | dchill42 <dchill42@gmail.com> | 2012-07-23 16:53:47 +0200 |
|---|---|---|
| committer | dchill42 <dchill42@gmail.com> | 2012-07-23 16:53:47 +0200 |
| commit | c5079de78e5141330c07e990811ef15e998e95aa (patch) | |
| tree | 0f39d8c4fc7614246fc185810bfeaa7fad88a33a /user_guide_src/source/helpers | |
| parent | 00fcb545109d4e61bc14e403ec828749c34a54b3 (diff) | |
| parent | ede49ba66b127535f3430e20aac72ceed2c4611a (diff) | |
Merge branch develop of github.com:/EllisLab/CodeIgniter into session
Diffstat (limited to 'user_guide_src/source/helpers')
22 files changed, 3281 insertions, 0 deletions
diff --git a/user_guide_src/source/helpers/array_helper.rst b/user_guide_src/source/helpers/array_helper.rst new file mode 100644 index 000000000..15b5e17c4 --- /dev/null +++ b/user_guide_src/source/helpers/array_helper.rst @@ -0,0 +1,139 @@ +############ +Array Helper +############ + +The Array Helper file contains functions that assist in working with +arrays. + +.. contents:: Page Contents + +Loading this Helper +=================== + +This helper is loaded using the following code + +:: + + $this->load->helper('array'); + +The following functions are available: + +element() +========= + +.. php:method:: element($item, $array, $default = NULL) + + :param string $item: Item to fetch from the array + :param array $array: Input array + :param boolean $default: What to return if the array isn't valid + :returns: NULL on failure or the array item. + + +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 + +:: + + $array = array( + 'color' => 'red', + 'shape' => 'round', + 'size' => '' + ); + + echo element('color', $array); // returns "red" + echo element('size', $array, 'foobar'); // returns "foobar" + +elements() +========== + +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. + +.. php:method:: elements($items, $array, $default = NULL) + + :param string $item: Item to fetch from the array + :param array $array: Input array + :param boolean $default: What to return if the array isn't valid + :returns: NULL on failure or the array item. + +Example + +:: + + $array = array( + 'color' => 'red', + 'shape' => 'round', + 'radius' => '10', + 'diameter' => '20' + ); + + $my_shape = elements(array('color', 'shape', 'height'), $array); + +The above will return the following array + +:: + + array( + 'color' => 'red', + 'shape' => 'round', + 'height' => NULL + ); + +You can set the third parameter to any default value you like + +:: + + $my_shape = elements(array('color', 'shape', 'height'), $array, 'foobar'); + +The above will return the following array + +:: + + 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->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. + +random_element() +================ + +Takes an array as input and returns a random element from it. Usage +example + +.. php:method:: random_element($array) + + :param array $array: Input array + :returns: String - Random element from the array. + +:: + + $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); + diff --git a/user_guide_src/source/helpers/captcha_helper.rst b/user_guide_src/source/helpers/captcha_helper.rst new file mode 100644 index 000000000..48095a11d --- /dev/null +++ b/user_guide_src/source/helpers/captcha_helper.rst @@ -0,0 +1,156 @@ +############## +CAPTCHA Helper +############## + +The CAPTCHA Helper file contains functions that assist in creating +CAPTCHA images. + +.. contents:: Page Contents + +Loading this Helper +=================== + +This helper is loaded using the following code + +:: + + $this->load->helper('captcha'); + +The following functions are available: + +create_captcha($data) +===================== + +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. + +.. php:method:: 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) + + +:: + + [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. + +Using the CAPTCHA helper +------------------------ + +Once loaded you can generate a captcha like this + +:: + + $vals = array( + 'word' => 'Random word', + 'img_path' => './captcha/', + 'img_url' => 'http://example.com/captcha/', + 'font_path' => './path/to/fonts/texb.ttf', + 'img_width' => '150', + 'img_height' => 30, + 'expiration' => 7200 + ); + + $cap = create_captcha($vals); echo $cap['image']; + + +- The captcha function requires the GD image library. +- Only the img_path and img_url are required. +- If a "word" is not supplied, the function will generate a random + ASCII string. You might put together your own word library that you + can draw randomly from. +- If you do not specify a path to a TRUE TYPE font, the native ugly GD + font will be used. +- The "captcha" folder must be writable (666, or 777) +- The "expiration" (in seconds) signifies how long an image will remain + in the captcha folder before it will be deleted. The default is two + hours. + +Adding a Database +----------------- + +In order for the captcha function to prevent someone from submitting, +you will need to add the information returned from create_captcha() +function to your database. Then, when the data from the form is +submitted by the user you will need to verify that the data exists in +the database and has not expired. + +Here is a table prototype + +:: + + CREATE TABLE captcha ( + captcha_id bigint(13) unsigned NOT NULL auto_increment, + captcha_time int(10) unsigned NOT NULL, + ip_address varchar(16) default '0' NOT NULL, + word varchar(20) NOT NULL, + PRIMARY KEY `captcha_id` (`captcha_id`), + KEY `word` (`word`) + ); + +Here is an example of usage with a database. On the page where the +CAPTCHA will be shown you'll have something like this + +:: + + $this->load->helper('captcha'); + $vals = array( + 'img_path' => './captcha/', + 'img_url' => 'http://example.com/captcha/' + ); + + $cap = create_captcha($vals); + $data = array( + 'captcha_time' => $cap['time'], + 'ip_address' => $this->input->ip_address(), + 'word' => $cap['word'] + ); + + $query = $this->db->insert_string('captcha', $data); + $this->db->query($query); + + echo 'Submit the word you see below:'; + echo $cap['image']; + echo '<input type="text" name="captcha" value="" />'; + +Then, on the page that accepts the submission you'll have something like +this + +:: + + // First, delete old captchas + $expiration = time() - 7200; // Two hour limit + $this->db->where('captcha_time < ', $expiration) + ->delete('captcha'); + + // Then see if a captcha exists: + $sql = "SELECT COUNT(*) AS count FROM captcha WHERE word = ? AND ip_address = ? AND captcha_time > ?"; + $binds = array($_POST['captcha'], $this->input->ip_address(), $expiration); + $query = $this->db->query($sql, $binds); + $row = $query->row(); + + if ($row->count == 0) + { + echo "You must submit the word that appears in the image"; + } + diff --git a/user_guide_src/source/helpers/cookie_helper.rst b/user_guide_src/source/helpers/cookie_helper.rst new file mode 100644 index 000000000..30e601c32 --- /dev/null +++ b/user_guide_src/source/helpers/cookie_helper.rst @@ -0,0 +1,78 @@ +############# +Cookie Helper +############# + +The Cookie Helper file contains functions that assist in working with +cookies. + +.. contents:: Page Contents + +Loading this Helper +=================== + +This helper is loaded using the following code + +:: + + $this->load->helper('cookie'); + +The following functions are available: + +set_cookie() +============ + +This helper function gives you view file friendly syntax to set browser +cookies. Refer to the :doc:`Input class <../libraries/input>` for a +description of use, as this function is an alias to +`$this->input->set_cookie()`. + +.. php:method:: set_cookie($name = '', $value = '', $expire = '', $domain = '', $path = '/', $prefix = '', $secure = FALSE) + + :param string $name: the name of the cookie + :param string $value: the value of the cookie + :param string $expire: the number of seconds until expiration + :param string $domain: the cookie domain. Usually: .yourdomain.com + :param string $path: the cookie path + :param string $prefix: the cookie prefix + :param boolean $secure: secure cookie or not. + :returns: void + +get_cookie() +============ + +This helper function gives you view file friendly syntax to get browser +cookies. Refer to the :doc:`Input class <../libraries/input>` for a +description of use, as this function is an alias to `$this->input->cookie()`. + +.. php:method:: get_cookie($index = '', $xss_clean = FALSE) + + :param string $index: the name of the cookie + :param boolean $xss_clean: If the resulting value should be xss_cleaned or not + :returns: mixed + +delete_cookie() +=============== + +Lets you delete a cookie. Unless you've set a custom path or other +values, only the name of the cookie is needed + +.. php:method:: delete_cookie($name = '', $domain = '', $path = '/', $prefix = '') + + :param string $name: the name of the cookie + :param string $domain: cookie domain (ususally .example.com) + :param string $path: cookie path + :param string $prefix: cookie prefix + :returns: void + +:: + + 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 diff --git a/user_guide_src/source/helpers/date_helper.rst b/user_guide_src/source/helpers/date_helper.rst new file mode 100644 index 000000000..e332a913f --- /dev/null +++ b/user_guide_src/source/helpers/date_helper.rst @@ -0,0 +1,464 @@ +########### +Date Helper +########### + +The Date Helper file contains functions that help you work with dates. + +.. contents:: Page Contents + +Loading this Helper +=================== + +This helper is loaded using the following code + +:: + + $this->load->helper('date'); + +The following functions are available: + +now() +===== + +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 suported 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. + +.. php:method:: now($timezone = NULL) + + :param string $timezone: The timezone you want to be returned + :returns: integer + +:: + echo now("Australia/Victoria"); + +If a timezone is not provided, it will return time() based on "time_reference" setting. + +mdate() +======= + +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: %Y %m %d etc. + +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. Example + +.. php:method:: mdate($datestr = '', $time = '') + + :param string $datestr: Date String + :param integer $time: time + :returns: integer + + +:: + + $datestring = "Year: %Y Month: %m Day: %d - %h:%i %a"; + $time = time(); + echo mdate($datestring, $time); + +If a timestamp is not included in the second parameter the current time +will be used. + +standard_date() +=============== + +Lets you generate a date string in one of several standardized formats. +Example + +.. php:method:: standard_date($fmt = 'DATE_RFC822', $time = '') + + :param string $fmt: the chosen format + :param string $time: Unix timestamp + :returns: string + +:: + + $format = 'DATE_RFC822'; + $time = time(); + echo standard_date($format, $time); + +The first parameter must contain the format, the second parameter must +contain the date as a Unix timestamp. + +.. 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: + + | + | echo date(DATE_RFC822, time()); + +Supported formats: + +=============== ======================= ====================================== +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 +=============== ======================= ====================================== + +local_to_gmt() +============== + +Takes a Unix timestamp as input and returns it as GMT. + +.. php:method:: local_to_gmt($time = '') + + :param integer $time: Unix timestamp + :returns: string + +Example: + +:: + + $now = time(); + $gmt = local_to_gmt($now); + +gmt_to_local() +============== + +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. + +.. php:method:: gmt_to_local($time = '', $timezone = 'UTC', $dst = FALSE) + + :param integer $time: Unix timestamp + :param string $timezone: timezone + :param boolean $dst: whether DST is active + :returns: integer + +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() +=============== + +Takes a MySQL Timestamp as input and returns it as Unix. + +.. php:method:: mysql_to_unix($time = '') + + :param integer $time: Unix timestamp + :returns: integer + +Example + +:: + + $mysql = '20061124092345'; + $unix = mysql_to_unix($mysql); + +unix_to_human() +=============== + +Takes a Unix timestamp as input and returns it in a human readable +format with this prototype + +.. php:method:: unix_to_human($time = '', $seconds = FALSE, $fmt = 'us') + + :param integer $time: Unix timestamp + :param boolean $seconds: whether to show seconds + :param string $fmt: format: us or euro + :returns: integer + +Example + +:: + + YYYY-MM-DD HH:MM:SS AM/PM + +This can be useful if you need to display a date in a form field for +submission. + +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. Examples + +:: + + $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 + +human_to_unix() +=============== + +The opposite of the above function. Takes a "human" time as input and +returns it as Unix. This function is useful if you accept "human" +formatted dates submitted via a form. Returns FALSE (boolean) if the +date string passed to it is not formatted as indicated above. + +.. php:method:: human_to_unix($datestr = '') + + :param integer $datestr: Date String + :returns: integer + +Example: + +:: + + $now = time(); + $human = unix_to_human($now); + $unix = human_to_unix($human); + +nice_date() +=========== + +This function can take a number poorly-formed date formats and convert +them into something useful. It also accepts well-formed dates. + +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. + +.. php:method:: nice_date($bad_date = '', $format = FALSE) + + :param integer $bad_date: The terribly formatted date-like string + :param string $format: Date format to return (same as php date function) + :returns: string + +Example + +:: + + $bad_date = '199605'; + // Should Produce: 1996-05-01 + $better_date = nice_date($bad_date, 'Y-m-d'); + + $bad_date = '9-11-2001'; + // Should Produce: 2001-09-11 + $better_date = nice_date($bad_date, 'Y-m-d'); + +timespan() +========== + +Formats a unix timestamp so that is appears similar to this +:: + + 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. If +the second parameter empty, the current time will be used. The third +parameter is optional and limits the number of time units to display. +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. + +.. php:method:: timespan($seconds = 1, $time = '', $units = '') + + :param integer $seconds: a number of seconds + :param string $time: Unix timestamp + :param integer $units: a number of time units to display + :returns: string + +Example + +:: + + $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 + +days_in_month() +=============== + +Returns the number of days in a given month/year. Takes leap years into +account. + +.. php:method:: days_in_month($month = 0, $year = '') + + :param integer $month: a numeric month + :param integer $year: a numeric year + :returns: integer + +Example + +:: + + echo days_in_month(06, 2005); + +If the second parameter is empty, the current year will be used. + +timezones() +=========== + +Takes a timezone reference (for a list of valid timezones, see the +"Timezone Reference" below) and returns the number of hours offset from +UTC. + +.. php:method:: timezones($tz = '') + + :param string $tz: a numeric timezone + :returns: string + +Example + +:: + + echo timezones('UM5'); + + +This function is useful when used with `timezone_menu()`. + +timezone_menu() +=============== + +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 + +.. php:method:: timezone_menu($default = 'UTC', $class = '', $name = 'timezones', $attributes = '') + + :param string $default: timezone + :param string $class: classname + :param string $name: menu name + :param mixed $attributes: attributes + :returns: string + +Example: + +:: + + 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 +================== + +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 +=========== ===================================================================== +UM2 (UTC - 12:00) Baker/Howland Island +UM1 (UTC - 11:00) Samoa Time Zone, Niue +UM0 (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 +UM (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 +UP1 (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 new file mode 100644 index 000000000..cf88732d3 --- /dev/null +++ b/user_guide_src/source/helpers/directory_helper.rst @@ -0,0 +1,80 @@ +################ +Directory Helper +################ + +The Directory Helper file contains functions that assist in working with +directories. + +.. contents:: Page Contents + +Loading this Helper +=================== + +This helper is loaded using the following code + +:: + + $this->load->helper('directory'); + +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 + ) + diff --git a/user_guide_src/source/helpers/download_helper.rst b/user_guide_src/source/helpers/download_helper.rst new file mode 100644 index 000000000..e6094dc6b --- /dev/null +++ b/user_guide_src/source/helpers/download_helper.rst @@ -0,0 +1,42 @@ +############### +Download Helper +############### + +The Download Helper lets you download data to your desktop. + +.. contents:: Page Contents + +Loading this Helper +=================== + +This helper is loaded using the following code + +:: + + $this->load->helper('download'); + +The following functions are available: + +force_download('filename', '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. Example + +:: + + $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 +read the file into a string + +:: + + $data = file_get_contents("/path/to/photo.jpg"); // Read the file's contents + $name = 'myphoto.jpg'; + force_download($name, $data); + diff --git a/user_guide_src/source/helpers/email_helper.rst b/user_guide_src/source/helpers/email_helper.rst new file mode 100644 index 000000000..d4e94b1ed --- /dev/null +++ b/user_guide_src/source/helpers/email_helper.rst @@ -0,0 +1,49 @@ +############ +Email Helper +############ + +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 + +Loading this Helper +=================== + +This helper is loaded using the following code:: + + $this->load->helper('email'); + + +The following functions are available: + +valid_email('email') +==================== + +Checks if an email is a correctly formatted email. Note that is doesn't +actually prove the email will recieve mail, simply that it is a validly +formed address. + +It returns TRUE/FALSE + +:: + + $this->load->helper('email'); + + if (valid_email('email@somesite.com')) + { + echo 'email is valid'; + } + else + { + echo 'email is not valid'; + } + +send_email('recipient', 'subject', 'message') +============================================= + +Sends an email using PHP's native +`mail() <http://www.php.net/function.mail>`_ function. For a more robust +email solution, see CodeIgniter's :doc:`Email +Class <../libraries/email>`. diff --git a/user_guide_src/source/helpers/file_helper.rst b/user_guide_src/source/helpers/file_helper.rst new file mode 100644 index 000000000..60c5aa98c --- /dev/null +++ b/user_guide_src/source/helpers/file_helper.rst @@ -0,0 +1,138 @@ +########### +File Helper +########### + +The File Helper file contains functions that assist in working with files. + +.. contents:: Page Contents + +Loading this Helper +=================== + +This helper is loaded using the following code + +:: + + $this->load->helper('file'); + +The following functions are available: + +read_file('path') +================= + +Returns the data contained in the file specified in the path. Example + +:: + + $string = read_file('./path/to/file.php'); + +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:: This function is DEPRECATED. Use the native ``file_get_contents()`` + instead. + +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('path', $data) +========================= + +Writes data to the file specified in the path. If the file does not exist the function will create it. Example + +:: + + $data = 'Some file data'; + if ( ! write_file('./path/to/file.php', $data)) + { + echo 'Unable to write the file'; + } + else + { + echo 'File written!'; + } + +You can optionally set the write mode via the third parameter + +:: + + write_file('./path/to/file.php', $data, 'r+'); + +The default mode is wb. Please see the `PHP user guide <http://php.net/fopen>`_ for mode options. + +Note: In order for this function to write data to a file its file 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:: 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('path') +==================== + +Deletes ALL files contained in the supplied path. Example + +:: + + 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. Example + +:: + + delete_files('./path/to/directory/', TRUE); + +.. note:: The files must be writable or owned by the system in order to be deleted. + +get_filenames('path/to/directory/') +=================================== + +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. + +get_dir_file_info('path/to/directory/', $top_level_only = TRUE) +=============================================================== + +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, $top_level_only to FALSE, as this can be an intensive operation. + +get_file_info('path/to/file', $file_information) +================================================ + +Given a file and path, returns the name, path, size, date modified. Second parameter allows you to explicitly declare what information you want returned; options are: `name`, `server_path`, `size`, `date`, `readable`, `writable`, `executable`, `fileperms`. Returns FALSE if the file cannot be found. + +.. note:: The "writable" uses the PHP function is_writable() which is known + to have issues on the IIS webserver. Consider using fileperms instead, + which returns information from PHP's fileperms() function. + +get_mime_by_extension('file') +============================= + +Translates a file extension into a mime type based on config/mimes.php. Returns FALSE if it can't determine the type, or open the mime config 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 as a convenience. It should not be used for security. + +symbolic_permissions($perms) +============================ + +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($perms) +========================= + +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 + diff --git a/user_guide_src/source/helpers/form_helper.rst b/user_guide_src/source/helpers/form_helper.rst new file mode 100644 index 000000000..fa7b3dbf9 --- /dev/null +++ b/user_guide_src/source/helpers/form_helper.rst @@ -0,0 +1,549 @@ +########### +Form Helper +########### + +The Form Helper file contains functions that assist in working with +forms. + +.. contents:: Page Contents + +Loading this Helper +=================== + +This helper is loaded using the following code + +:: + + $this->load->helper('form'); + +The following functions are available: + +form_open() +=========== + +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 attribute accept-charset 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. + +Here's a simple example + +:: + + 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 + +:: + + <form method="post" accept-charset="utf-8" action="http://example.com/index.php/email/send" /> + +Adding Attributes +^^^^^^^^^^^^^^^^^ + +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); + +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" class="email" id="myform" /> + +Adding Hidden Input Fields +^^^^^^^^^^^^^^^^^^^^^^^^^^ + +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); + +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_open_multipart() +===================== + +This function is absolutely identical to the `form_open()` tag 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() +============= + +Lets you generate hidden input fields. You can either submit a +name/value string to create one field + +:: + + form_hidden('username', 'johndoe'); + // Would produce: <input type="hidden" name="username" value="johndoe" /> + +Or you can submit an associative array to create multiple fields + +:: + + $data = array( + 'name' => 'John Doe', + 'email' => 'john@example.com', + 'url' => 'http://example.com' + ); + + echo form_hidden($data); + + /* + 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" /> + */ + +Or pass an associative array to the value field. + +:: + + $data = array( + 'name' => 'John Doe', + 'email' => 'john@example.com', + 'url' => 'http://example.com' + ); + + echo form_hidden('my_array', $data); + + /* + Would produce: + <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" /> + */ + +If you want to create hidden input fields with extra attributes + +:: + + $data = array( + 'type' => 'hidden', + 'name' => 'email', + 'id' => 'hiddenemail', + 'value' => 'john@example.com', + 'class' => 'hiddenemail' + ); + + echo form_input($data); + + /* + Would produce: + + <input type="hidden" name="email" value="john@example.com" id="hiddenemail" class="hiddenemail" /> + */ + +form_input() +============ + +Lets you generate a standard text input field. You can minimally pass +the field name and value in the first and second parameter + +:: + + echo form_input('username', 'johndoe'); + +Or you can pass an associative array containing any data you wish your +form to contain + +:: + + $data = array( + 'name' => 'username', + 'id' => 'username', + 'value' => 'johndoe', + 'maxlength' => '100', + 'size' => '50', + 'style' => 'width:50%' + ); + + echo form_input($data); + + /* + Would produce: + + <input type="text" name="username" value="johndoe" id="username" maxlength="100" size="50" style="width:50%" /> + */ + +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_input('username', 'johndoe', $js); + +form_password() +=============== + +This function is identical in all respects to the `form_input()` function above except that it uses the "password" input type. + +form_upload() +============= + +This function is identical in all respects to the `form_input()` function above except that it uses the "file" input type, allowing it to be used to upload files. + +form_textarea() +=============== + +This function is identical in all respects to the `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". + +form_dropdown() +=============== + +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> + */ + + echo form_dropdown('shirts', $options, $shirts_on_sale); + + /* + Would produce: + + <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> + */ + +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 + +:: + + $js = 'id="shirts" onChange="some_function();"'; + echo form_dropdown('shirts', $options, 'large', $js); + +If the array passed as $options is a multidimensional array, +`form_dropdown()` will produce an <optgroup> with the array key as the +label. + +form_multiselect() +================== + +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 form_dropdown() above, except of course that the +name of the field will need to use POST array syntax, e.g. foo[]. + +form_fieldset() +================ + +Lets you generate fieldset/legend fields. + +:: + + echo form_fieldset('Address Information'); + echo "<p>fieldset content here</p>\n"; + echo form_fieldset_close(); + + /* + Produces: + <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. + +:: + + $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(); + + /* + Produces: + + <fieldset id="address_info" class="address_info"> + <legend>Address Information</legend> + <p>form content here</p> + </fieldset> + */ + +form_fieldset_close() +===================== + +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> + +form_checkbox() +=============== + +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" /> + +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 + +:: + + $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" /> + +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) + +form_radio() +============ + +This function is identical in all respects to the `form_checkbox()` +function above except that it uses the "radio" input type. + +form_submit() +============= + +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!" /> + +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_label() +============ + +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> + +Similar to other functions, you can submit an associative array in the +third parameter if you prefer to set additional attributes. + +:: + + $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> + + +form_reset() +============ + +Lets you generate a standard reset button. Use is identical to +`form_submit()`. + +form_button() +============= + +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> + +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' + ); + + 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: + +:: + + $js = 'onClick="some_function()"'; + echo form_button('mybutton', 'Click Me', $js); + +form_close() +============ + +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> + +form_prep() +=========== + +Allows you to safely use HTML and characters such as quotes within form +elements without breaking out of the form. Consider this example + +:: + + $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 + +:: + + <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. + +set_value() +=========== + +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 + +:: + + <input type="text" name="quantity" value="<?php echo set_value('quantity', '0'); ?>" size="50" /> + +The above form will show "0" when loaded for the first time. + +set_select() +============ + +If you use a <select> menu, this function permits you to display the +menu item that was selected. 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). + +Example + +:: + + <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> + +set_checkbox() +============== + +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). 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'); ?> /> + +set_radio() +=========== + +Permits you to display radio buttons in the state they were submitted. +This function is identical to the **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'); ?> /> + +.. 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.
\ 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 new file mode 100644 index 000000000..17c28cd2a --- /dev/null +++ b/user_guide_src/source/helpers/html_helper.rst @@ -0,0 +1,368 @@ +########### +HTML Helper +########### + +The HTML Helper file contains functions that assist in working with +HTML. + +.. contents:: Page Contents + +Loading this Helper +=================== + +This helper is loaded using the following code:: + + $this->load->helper('html'); + +The following functions are available: + +br() +==== + +Generates line break tags (<br />) based on the number you submit. +Example:: + + echo br(3); + +The above would produce: <br /><br /><br /> + +heading() +========= + +Lets you create HTML <h1> tags. The first parameter will contain the +data, the second the size of the heading. Example:: + + echo heading('Welcome!', 3); + +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. + +:: + + echo heading('Welcome!', 3, 'class="pink"') + +The above code produces: <h3 class="pink">Welcome!<<h3> + +img() +===== + +Lets you create HTML <img /> tags. The first parameter contains the +image source. Example + +:: + + echo img('images/picture.jpg'); // gives <img src="http://site.com/images/picture.jpg" /> + +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. + +:: + + $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" /> + + +link_tag() +=========== + +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. index_page is a TRUE/FALSE value +that specifics 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" /> + + +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('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. + +:: + + $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" /> + + +nbs() +===== + +Generates non-breaking spaces ( ) based on the number you submit. +Example + +:: + + echo nbs(3); + +The above would produce + +:: + + + +ol() and ul() +============= + +Permits you to generate ordered or unordered HTML lists from simple or +multi-dimensional arrays. Example + +:: + + $this->load->helper('html'); + + $list = array( + 'red', + 'blue', + 'green', + 'yellow' + ); + + $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 + +:: + + $this->load->helper('html'); + + $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> + +meta() +====== + +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() +========= + +Helps you generate document type declarations, or DTD's. XHTML 1.0 +Strict is used by default, but many doctypes are available. + +:: + + 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 diff --git a/user_guide_src/source/helpers/index.rst b/user_guide_src/source/helpers/index.rst new file mode 100644 index 000000000..f28c8e164 --- /dev/null +++ b/user_guide_src/source/helpers/index.rst @@ -0,0 +1,9 @@ +####### +Helpers +####### + +.. toctree:: + :glob: + :titlesonly: + + *
\ 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 new file mode 100644 index 000000000..cc46a1851 --- /dev/null +++ b/user_guide_src/source/helpers/inflector_helper.rst @@ -0,0 +1,85 @@ +################ +Inflector Helper +################ + +The Inflector Helper file contains functions that permits you to change +words to plural, singular, camel case, etc. + +.. contents:: Page Contents + +Loading this Helper +=================== + +This helper is loaded using the following code + +:: + + $this->load->helper('inflector'); + +The following functions are available: + +singular() +========== + +Changes a plural word to singular. Example + +:: + + $word = "dogs"; + echo singular($word); // Returns "dog" + +plural() +======== + +Changes a singular word to plural. Example + +:: + + $word = "dog"; + echo plural($word); // Returns "dogs" + +To force a word to end with "es" use a second "true" argument. + +:: + + $word = "pass"; + echo plural($word, TRUE); // Returns "passes" + +camelize() +========== + +Changes a string of words separated by spaces or underscores to camel +case. Example + +:: + + $word = "my_dog_spot"; + echo camelize($word); // Returns "myDogSpot" + +underscore() +============ + +Takes multiple words separated by spaces and underscores them. Example + +:: + + $word = "my dog spot"; + echo underscore($word); // Returns "my_dog_spot" + +humanize() +========== + +Takes multiple words separated by underscores and adds spaces between +them. Each word is capitalized. Example + +:: + + $word = "my_dog_spot"; + echo humanize($word); // Returns "My Dog Spot" + +To use dashes instead of underscores + +:: + + $word = "my-dog-spot"; + echo humanize($word, '-'); // Returns "My Dog Spot"
\ 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 new file mode 100644 index 000000000..b7b23d149 --- /dev/null +++ b/user_guide_src/source/helpers/language_helper.rst @@ -0,0 +1,33 @@ +############### +Language Helper +############### + +The Language Helper file contains functions that assist in working with +language files. + +.. contents:: Page Contents + +Loading this Helper +=================== + +This helper is loaded using the following code + +:: + + $this->load->helper('language'); + +The following functions are available: + +lang('language line', 'element id') +=================================== + +This function returns a line of text from a loaded language file with +simplified syntax that may be more desirable for view files than calling +`$this->lang->line()`. The optional second parameter will also output a +form label for you. Example + +:: + + echo lang('language_key', 'form_item_id'); + // becomes <label for="form_item_id">language_key</label> + diff --git a/user_guide_src/source/helpers/number_helper.rst b/user_guide_src/source/helpers/number_helper.rst new file mode 100644 index 000000000..af6cdad57 --- /dev/null +++ b/user_guide_src/source/helpers/number_helper.rst @@ -0,0 +1,45 @@ +############# +Number Helper +############# + +The Number Helper file contains functions that help you work with +numeric data. + +.. contents:: Page Contents + +Loading this Helper +=================== + +This helper is loaded using the following code + +:: + + $this->load->helper('number'); + +The following functions are available: + +byte_format() +============= + +Formats a 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 diff --git a/user_guide_src/source/helpers/path_helper.rst b/user_guide_src/source/helpers/path_helper.rst new file mode 100644 index 000000000..847f5a08b --- /dev/null +++ b/user_guide_src/source/helpers/path_helper.rst @@ -0,0 +1,43 @@ +########### +Path Helper +########### + +The Path Helper file contains functions that permits you to work with +file paths on the server. + +.. contents:: Page Contents + +Loading this Helper +=================== + +This helper is loaded using the following code + +:: + + $this->load->helper('path'); + +The following functions are available: + +set_realpath() +============== + +Checks to see if the path exists. 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. + +:: + + $file = '/etc/php5/apache2/php.ini'; + echo set_realpath($file); // returns "/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); // returns "/path/to/non-exist-file.txt" + + $directory = '/etc/php5'; + echo set_realpath($directory); // returns "/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); // returns "/path/to/nowhere" diff --git a/user_guide_src/source/helpers/security_helper.rst b/user_guide_src/source/helpers/security_helper.rst new file mode 100644 index 000000000..ec0be28b3 --- /dev/null +++ b/user_guide_src/source/helpers/security_helper.rst @@ -0,0 +1,70 @@ +############### +Security Helper +############### + +The Security Helper file contains security related functions. + +.. contents:: Page Contents + +Loading this Helper +=================== + +This helper is loaded using the following code + +:: + + $this->load->helper('security'); + +The following functions are available: + +xss_clean() +=========== + +Provides Cross Site Script Hack filtering. This function is an alias to +the one in the :doc:`Input class <../libraries/input>`. More info can +be found there. + +sanitize_filename() +=================== + +Provides protection against directory traversal. This function is an +alias to the one in the :doc:`Security class <../libraries/security>`. +More info can be found there. + +do_hash() +========= + +Permits you to create one way hashes suitable for encrypting +passwords. Will create SHA1 by default. See `hash_algos() <http://php.net/function.hash_algos>`_ +for a full list of supported algorithms. + +:: + + $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 is DEPRECATED. Use the native ``hash()`` instead. + +strip_image_tags() +================== + +This is a security function that will strip image tags from a string. It +leaves the image URL as plain text. + +:: + + $string = strip_image_tags($string); + +encode_php_tags() +================= + +This is a security function that converts PHP tags to entities. Note: If +you use the XSS filtering function it does this automatically. + +:: + + $string = encode_php_tags($string); + diff --git a/user_guide_src/source/helpers/smiley_helper.rst b/user_guide_src/source/helpers/smiley_helper.rst new file mode 100644 index 000000000..941ba11e3 --- /dev/null +++ b/user_guide_src/source/helpers/smiley_helper.rst @@ -0,0 +1,160 @@ +############# +Smiley Helper +############# + +The Smiley Helper file contains functions that let you manage smileys +(emoticons). + +.. contents:: Page Contents + +Loading this Helper +=================== + +This helper is loaded using the following code + +:: + + $this->load->helper('smiley'); + +Overview +======== + +The Smiley helper has a renderer that takes plain text simileys, like +:-) and turns them into a image representation, like |smile!| + +It also lets you display a set of smiley images that when clicked will +be inserted into a form field. For example, if you have a blog that +allows user commenting you can show the smileys next to the comment +form. Your users can click a desired smiley and with the help of some +JavaScript it will be placed into the form field. + +Clickable Smileys Tutorial +========================== + +Here is an example demonstrating how you might create a set of clickable +smileys next to a form field. This example requires that you first +download and install the smiley images, then create a controller and the +View as described. + +.. important:: Before you begin, please `download the smiley images <http://codeigniter.com/download_files/smileys.zip>`_ + and put them in a publicly accessible place on your server. This helper + also assumes you have the smiley replacement array located at + `application/config/smileys.php` + +The Controller +-------------- + +In your `application/controllers/` folder, create a file called +smileys.php and place the code below in it. + +.. important:: Change the URL in the `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 using the :doc:`Table Class <../libraries/table>`. + +:: + + <?php + + class Smileys extends CI_Controller { + + function index() + { + $this->load->helper('smiley'); + $this->load->library('table'); + + $image_array = get_clickable_smileys('http://example.com/images/smileys/', 'comments'); + $col_array = $this->table->make_columns($image_array, 8); + + $data['smiley_table'] = $this->table->generate($col_array); + $this->load->view('smiley_view', $data); + } + } + +In your `application/views/` folder, create a file called `smiley_view.php` +and place this code in it: + +:: + + <html> + <head> + <title>Smileys</title> + <?php echo smiley_js(); ?> + </head> + <body> + <form name="blog"> + <textarea name="comments" id="comments" cols="40" rows="4"></textarea> + </form> + <p>Click to insert a smiley!</p> + <?php echo $smiley_table; ?> </body> </html> + When you have created the above controller and view, load it by visiting http://www.example.com/index.php/smileys/ + </body> + </html> + +Field Aliases +------------- + +When making changes to a view it can be inconvenient to have the field +id in the controller. To work around this, you can give your smiley +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 `smiley_js` +function + +:: + + $image_array = smiley_js("comment_textarea_alias", "comments"); + +****************** +Function Reference +****************** + +get_clickable_smileys() +======================= + +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. + +:: + + $image_array = get_smiley_links("http://example.com/images/smileys/", "comment"); + +Note: Usage of this function without the second parameter, in +combination with `js_insert_smiley` has been deprecated. + +smiley_js() +=========== + +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(); ?> + +Note: This function replaces `js_insert_smiley`, which has been +deprecated. + +parse_smileys() +=============== + +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 simileys: :-) ;-)'; + $str = parse_smileys($str, "http://example.com/images/smileys/"); + echo $str; + + +.. |smile!| image:: ../images/smile.gif diff --git a/user_guide_src/source/helpers/string_helper.rst b/user_guide_src/source/helpers/string_helper.rst new file mode 100644 index 000000000..19500aa0d --- /dev/null +++ b/user_guide_src/source/helpers/string_helper.rst @@ -0,0 +1,196 @@ +############# +String Helper +############# + +The String Helper file contains functions that assist in working with +strings. + +.. contents:: Page Contents + +Loading this Helper +=================== + +This helper is loaded using the following code + +:: + + $this->load->helper('string'); + +The following functions are available: + +random_string() +=============== + +Generates a random string based on the type and length you specify. +Useful for creating passwords or generating random hashes. + +The first parameter specifies the type of string, the second parameter +specifies the length. The following choices are available: + +alpha, alunum, numeric, nozero, unique, md5, encrypt and sha1 + +- **alpha**: A string with lower and uppercase letters only. +- **alnum**: Alpha-numeric string with lower and uppercase characters. +- **numeric**: Numeric string. +- **nozero**: Numeric string with no zeros. +- **unique**: Encrypted with MD5 and uniqid(). Note: The length + parameter is not available for this type. Returns a fixed length 32 + character string. +- **sha1**: An encrypted random number based on ``sha1()``. + +Usage example + +:: + + echo random_string('alnum', 16); + +increment_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. + +Usage example + +:: + + echo increment_string('file', '_'); // "file_1" + echo increment_string('file', '-', 2); // "file-2" + echo increment_string('file_4'); // "file_5" + +alternator() +============ + +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'); + } + +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'); + } + +.. note:: To use multiple separate calls to this function simply call the + function with no arguments to re-initialize. + +repeater() +========== + +Generates repeating copies of the data you submit. Example + +:: + + $string = "\n"; echo repeater($string, 30); + +The above would generate 30 newlines. + +reduce_double_slashes() +======================= + +Converts double slashes in a string to a single slash, except those +found in http://. Example + +:: + + $string = "http://example.com//index.php"; + echo reduce_double_slashes($string); // results in "http://example.com/index.php" + +strip_slashes() +=============== + +Removes any slashes from a string. Example + +:: + + $str = "Is your name O\'reilly?"; + echo strip_slashes($str); // results in Is your name O'reilly? + +You can also use an array. 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: + +:: + + array( + 'question' => "Is your name O'reilly?", + 'answer' => "No, my name is O'connor." + ); + +trim_slashes() +============== + +Removes any leading/trailing slashes from a string. Example + +:: + + $string = "/this/that/theother/"; + echo trim_slashes($string); // results in this/that/theother + + +reduce_multiples() +================== + +Reduces multiple instances of a particular character occuring directly +after each other. Example:: + + $string = "Fred, Bill,, Joe, Jimmy"; + $string = reduce_multiples($string,","); //results in "Fred, Bill, Joe, Jimmy" + +The function accepts the following parameters: + +:: + + reduce_multiples(string: text to search in, string: character to reduce, boolean: whether to remove the character from the front and end of the string) + +The first parameter contains the string in which you want to reduce the +multiplies. The second parameter contains the character you want to have +reduced. The third parameter is FALSE by default; if 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, ", ", TRUE); //results in "Fred, Bill, Joe, Jimmy" + + +quotes_to_entities() +==================== + +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"" + +strip_quotes() +============== + +Removes single and double quotes from a string. Example:: + + $string = "Joe's \"dinner\""; + $string = strip_quotes($string); //results in "Joes dinner" + diff --git a/user_guide_src/source/helpers/text_helper.rst b/user_guide_src/source/helpers/text_helper.rst new file mode 100644 index 000000000..8cb2d6f96 --- /dev/null +++ b/user_guide_src/source/helpers/text_helper.rst @@ -0,0 +1,169 @@ +########### +Text Helper +########### + +The Text Helper file contains functions that assist in working with +text. + +.. contents:: Page Contents + +Loading this Helper +=================== + +This helper is loaded using the following code + +:: + + $this->load->helper('text'); + +The following functions are available: + +word_limiter() +============== + +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… + +The third parameter is an optional suffix added to the string. By +default it adds an ellipsis. + +character_limiter() +=================== + +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. Example + +:: + + $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. + +**Note:** If you need to truncate to an exact number of characters please see +the :ref:`ellipsize` function below. + +ascii_to_entities() +=================== + +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 + +:: + + $string = ascii_to_entities($string); + +entities_to_ascii() +=================== + +This function does the opposite of the previous one; it turns character +entities back into ASCII. + +convert_accented_characters() +============================= + +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); + +This function uses a companion config file +`application/config/foreign_chars.php` to define the to and from array +for transliteration. + +word_censor() +============= + +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 + +:: + + $disallowed = array('darn', 'shucks', 'golly', 'phooey'); + $string = word_censor($string, $disallowed, 'Beep!'); + +highlight_code() +================ + +Colorizes a string of code (PHP, HTML, etc.). Example:: + + $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. + +highlight_phrase() +================== + +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 + +:: + + $string = "Here is a nice text string about nothing in particular."; + $string = highlight_phrase($string, "nice text", '<span style="color:#990000">', '</span>'); + +The above text returns: + +Here is a nice text string about nothing in particular. + +word_wrap() +=========== + +Wraps text at the specified **character** count while maintaining +complete words. Example + +:: + + $string = "Here is a simple string of text that will help us demonstrate this function."; + echo word_wrap($string, 25); + + // Would produce: Here is a simple string of text that will help us demonstrate this function + +.. _ellipsize: + +ellipsize() +=========== + +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. + +An optional forth parameter is the kind of ellipsis. By default, +… will be inserted. + +:: + + $str = 'this_string_is_entirely_too_long_and_might_break_my_design.jpg'; + echo ellipsize($str, 32, .5); + +Produces: + +:: + + this_string_is_e…ak_my_design.jpg + diff --git a/user_guide_src/source/helpers/typography_helper.rst b/user_guide_src/source/helpers/typography_helper.rst new file mode 100644 index 000000000..f3202603a --- /dev/null +++ b/user_guide_src/source/helpers/typography_helper.rst @@ -0,0 +1,48 @@ +################# +Typography Helper +################# + +The Typography Helper file contains functions that help your format text +in semantically relevant ways. + +.. contents:: Page Contents + +Loading this Helper +=================== + +This helper is loaded using the following code + +:: + + $this->load->helper('typography'); + +The following functions are available: + +auto_typography() +================= + +Formats text so that it is semantically and typographically correct +HTML. Please see the :doc:`Typography Class <../libraries/typography>` +for more info. + +Usage example:: + + $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. + +nl2br_except_pre() +================== + +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. + +Usage example + +:: + + $string = nl2br_except_pre($string); + diff --git a/user_guide_src/source/helpers/url_helper.rst b/user_guide_src/source/helpers/url_helper.rst new file mode 100644 index 000000000..82db6a5b3 --- /dev/null +++ b/user_guide_src/source/helpers/url_helper.rst @@ -0,0 +1,322 @@ +########## +URL Helper +########## + +The URL Helper file contains functions that assist in working with URLs. + +.. contents:: Page Contents + +Loading this Helper +=================== + +This helper is loaded using the following code + +:: + + $this->load->helper('url'); + +The following functions are available: + +site_url() +========== + +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, and the url_suffix as set in your config file. + +You are encouraged to use this function any time you need to generate a +local URL so that your pages become more portable in the event your URL +changes. + +Segments can be optionally passed to the function as a string or an +array. Here is a string example + +:: + + echo site_url("news/local/123"); + +The above example would return something like: +http://example.com/index.php/news/local/123 + +Here is an example of segments passed as an array + +:: + + $segments = array('news', 'local', '123'); + echo site_url($segments); + +base_url() +=========== + +Returns your site base URL, as specified in your config file. Example + +:: + + echo base_url(); + +This function returns the same thing as `site_url`, without the +index_page or url_suffix being appended. + +Also like site_url, you can supply segments as a string or an array. +Here is a string example + +:: + + echo base_url("blog/post/123"); + +The above example would return something like: +http://example.com/blog/post/123 + +This is useful because unlike `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"); + +This would give you something like: +http://example.com/images/icons/edit.png + +current_url() +============= + +Returns the full URL (including segments) of the page being currently +viewed. + +uri_string() +============ + +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 + +The function would return + +:: + + /blog/comments/123 + +index_page() +============ + +Returns your site "index" page, as specified in your config file. +Example + +:: + + echo index_page(); + +anchor() +======== + +Creates a standard HTML anchor link based on your local site URL + +:: + + <a href="http://example.com">Click Here</a> + +The tag has three optional parameters + +:: + + anchor(uri segments, text, attributes) + +The first parameter can contain any segments you wish appended to the +URL. As with the 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. + +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. + +Here are some examples + +:: + + echo anchor('news/local/123', 'My News', 'title="News title"'); + +Would produce: <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!')); + +Would produce: <a href="http://example.com/index.php/news/local/123" +title="The best news!">My News</a> + +anchor_popup() +============== + +Nearly identical to the 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 + +:: + + $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); + +.. 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:: Any other attribute than the listed above will be parsed as an + HTML attribute to the anchor tag. + +mailto() +======== + +Creates a standard HTML email link. Usage example + +:: + + echo mailto('me@my-site.com', 'Click Here to Contact Me'); + +As with the anchor() tab above, you can set attributes using the third +parameter. + +safe_mailto() +============= + +Identical to the above function except it writes an obfuscated version +of the mailto tag using ordinal numbers written with JavaScript to help +prevent the email address from being harvested by spam bots. + +auto_link() +=========== + +Automatically turns URLs and email addresses contained in a string into +links. Example + +:: + + $string = auto_link($string); + +The second parameter determines whether URLs and emails are converted or +just one or the other. Default behavior is both if the parameter is not +specified. Email links are encoded as safe_mailto() as shown above. + +Converts only URLs + +:: + + $string = auto_link($string, 'url'); + +Converts only Email addresses + +:: + + $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) + +:: + + $string = auto_link($string, 'both', TRUE); + +url_title() +=========== + +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 + +The second parameter determines the word delimiter. By default dashes +are used. Options are: dash, or underscore + +:: + + $title = "What's wrong with CSS?"; + $url_title = url_title($title, 'underscore'); // Produces: Whats_wrong_with_CSS + +The third parameter determines whether or not lowercase characters are +forced. By default they are not. Options are boolean TRUE/FALSE + +:: + + $title = "What's wrong with CSS?"; + $url_title = url_title($title, 'underscore', TRUE); // Produces: whats_wrong_with_css + +prep_url() +---------- + +This function will add http:// in the event that a scheme is missing +from a URL. Pass the URL string to the function like this + +:: + + $url = "example.com"; + $url = prep_url($url); + +redirect() +========== + +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 "location" or "refresh", with location +being faster but less reliable on Windows 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:: + + if ($logged_in == FALSE) + { + redirect('/login/form/'); + } + + // 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:: For very fine grained control over headers, you should use the + `Output Library </libraries/output>` set_header() function. diff --git a/user_guide_src/source/helpers/xml_helper.rst b/user_guide_src/source/helpers/xml_helper.rst new file mode 100644 index 000000000..be848bcd1 --- /dev/null +++ b/user_guide_src/source/helpers/xml_helper.rst @@ -0,0 +1,38 @@ +########## +XML Helper +########## + +The XML Helper file contains functions that assist in working with XML +data. + +.. contents:: Page Contents + +Loading this Helper +=================== + +This helper is loaded using the following code + +:: + + $this->load->helper('xml'); + +The following functions are available: + +xml_convert() +===================== + +Takes a string as input and converts the following reserved XML +characters to entities: + +- Ampersands: & +- Less then and greater than characters: < > +- Single and double quotes: ' " +- Dashes: - + +This function ignores ampersands if they are part of existing character +entities. Example + +:: + + $string = xml_convert($string); + |