From c9bf303220f90b0e71acd54d150fafc87df3df81 Mon Sep 17 00:00:00 2001 From: Derek Jones Date: Wed, 24 Jul 2013 18:01:27 -0700 Subject: Update Upload lib docs --- user_guide_src/source/libraries/file_uploading.rst | 165 ++++++++++----------- 1 file changed, 82 insertions(+), 83 deletions(-) (limited to 'user_guide_src/source/libraries/file_uploading.rst') diff --git a/user_guide_src/source/libraries/file_uploading.rst b/user_guide_src/source/libraries/file_uploading.rst index a92d3af34..695998d73 100644 --- a/user_guide_src/source/libraries/file_uploading.rst +++ b/user_guide_src/source/libraries/file_uploading.rst @@ -5,6 +5,13 @@ File Uploading Class CodeIgniter's File Uploading Class permits files to be uploaded. You can set various preferences, restricting the type and size of the files. +.. contents:: + :local: + +.. raw:: html + +
+ *********** The Process *********** @@ -240,105 +247,97 @@ preferences in a config file. Class Reference *************** -The following methods are available: +.. class:: CI_Upload -$this->upload->do_upload() -========================== + .. method:: do_upload([$field = 'userfile']) -Performs the upload based on the preferences you've set. + :param string $field: name of the form field + :returns: bool -.. note:: By default the upload routine expects the file to come from - a form field called userfile, and the form must be of type - "multipart". + Performs the upload based on the preferences you've set. -:: + .. note:: By default the upload routine expects the file to come from + a form field called userfile, and the form must be of type + "multipart". -
+ :: -If you would like to set your own field name simply pass its value to -the ``do_upload()`` method:: + - $field_name = "some_field_name"; - $this->upload->do_upload($field_name); + If you would like to set your own field name simply pass its value to + the ``do_upload()`` method:: -$this->upload->display_errors() -=============================== + $field_name = "some_field_name"; + $this->upload->do_upload($field_name); -Retrieves any error messages if the ``do_upload()`` method returned -false. The method does not echo automatically, it returns the data so -you can assign it however you need. -Formatting Errors -***************** + .. method:: display_errors([$open = '

'[, $close = '

']]) -By default the above method wraps any errors within

tags. You can -set your own delimiters like this:: + :param string $open: Opening markup + :param string $close: Closing markup + :returns: string - $this->upload->display_errors('

', '

'); + Retrieves any error messages if the ``do_upload()`` method returned + false. The method does not echo automatically, it returns the data so + you can assign it however you need. -$this->upload->data() -===================== + **Formatting Errors** -This is a helper method that returns an array containing all of the -data related to the file you uploaded. Here is the array prototype:: + By default the above method wraps any errors within

tags. You can + set your own delimiters like this:: - Array - ( - [file_name] => mypic.jpg - [file_type] => image/jpeg - [file_path] => /path/to/your/upload/ - [full_path] => /path/to/your/upload/jpg.jpg - [raw_name] => mypic - [orig_name] => mypic.jpg - [client_name] => mypic.jpg - [file_ext] => .jpg - [file_size] => 22.2 - [is_image] => 1 - [image_width] => 800 - [image_height] => 600 - [image_type] => jpeg - [image_size_str] => width="800" height="200" - ) + $this->upload->display_errors('

', '

'); -To return one element from the array:: - $this->upload->data('file_name'); // Returns: mypic.jpg + .. method:: data([$index = NULL]) -Explanation -*********** + :param string $data: element to return instead of the full array + :returns: mixed + + This is a helper method that returns an array containing all of the + data related to the file you uploaded. Here is the array prototype:: + + Array + ( + [file_name] => mypic.jpg + [file_type] => image/jpeg + [file_path] => /path/to/your/upload/ + [full_path] => /path/to/your/upload/jpg.jpg + [raw_name] => mypic + [orig_name] => mypic.jpg + [client_name] => mypic.jpg + [file_ext] => .jpg + [file_size] => 22.2 + [is_image] => 1 + [image_width] => 800 + [image_height] => 600 + [image_type] => jpeg + [image_size_str] => width="800" height="200" + ) + + To return one element from the array:: + + $this->upload->data('file_name'); // Returns: mypic.jpg + + **Explanation** + + Here is an explanation of the above array items. -Here is an explanation of the above array items. - -Item -Description -**file_name** -The name of the file that was uploaded including the file extension. -**file_type** -The file's Mime type -**file_path** -The absolute server path to the file -**full_path** -The absolute server path including the file name -**raw_name** -The file name without the extension -**orig_name** -The original file name. This is only useful if you use the encrypted -name option. -**client_name** -The file name as supplied by the client user agent, prior to any file -name preparation or incrementing. -**file_ext** -The file extension with period -**file_size** -The file size in kilobytes -**is_image** -Whether the file is an image or not. 1 = image. 0 = not. -**image_width** -Image width. -**image_height** -Image height -**image_type** -Image type. Typically the file extension without the period. -**image_size_str** -A string containing the width and height. Useful to put into an image -tag. \ No newline at end of file + ================ ================================================ + Item Description + ================ ================================================ + file_name The name of the file that was uploaded including the file extension. + file_type The file's Mime type + file_path The absolute server path to the file + full_path The absolute server path including the file name + raw_name The file name without the extension + orig_name The original file name. This is only useful if you use the encrypted name option. + client_name The file name as supplied by the client user agent, prior to any file name preparation or incrementing. + file_ext The file extension with period + file_size The file size in kilobytes + is_image Whether the file is an image or not. 1 = image. 0 = not. + image_width Image width. + image_height Image height + image_type Image type. Typically the file extension without the period. + image_size_str A string containing the width and height. Useful to put into an image tag. + ================ ================================================ \ No newline at end of file -- cgit v1.2.3-24-g4f1b From 28c2c975b118016d07212ed8e7c22ff280309f82 Mon Sep 17 00:00:00 2001 From: Andrey Andreev Date: Sat, 8 Feb 2014 04:27:48 +0200 Subject: [ci skip] Add return types to library docs --- user_guide_src/source/libraries/file_uploading.rst | 60 +++++++++++----------- 1 file changed, 30 insertions(+), 30 deletions(-) (limited to 'user_guide_src/source/libraries/file_uploading.rst') diff --git a/user_guide_src/source/libraries/file_uploading.rst b/user_guide_src/source/libraries/file_uploading.rst index d679d8aa2..d7ba3a6c1 100644 --- a/user_guide_src/source/libraries/file_uploading.rst +++ b/user_guide_src/source/libraries/file_uploading.rst @@ -256,8 +256,9 @@ Class Reference .. method:: do_upload([$field = 'userfile']) - :param string $field: name of the form field - :returns: bool + :param string $field: Name of the form field + :returns: TRUE on success, FALSE on failure + :rtype: bool Performs the upload based on the preferences you've set. @@ -275,12 +276,12 @@ Class Reference $field_name = "some_field_name"; $this->upload->do_upload($field_name); - .. method:: display_errors([$open = '

'[, $close = '

']]) - :param string $open: Opening markup - :param string $close: Closing markup - :returns: string + :param string $open: Opening markup + :param string $close: Closing markup + :returns: Formatted error message(s) + :rtype: string Retrieves any error messages if the ``do_upload()`` method returned false. The method does not echo automatically, it returns the data so @@ -296,8 +297,9 @@ Class Reference .. method:: data([$index = NULL]) - :param string $data: element to return instead of the full array - :returns: mixed + :param string $data: Element to return instead of the full array + :returns: Information about the uploaded file + :rtype: mixed This is a helper method that returns an array containing all of the data related to the file you uploaded. Here is the array prototype:: @@ -324,25 +326,23 @@ Class Reference $this->upload->data('file_name'); // Returns: mypic.jpg - **Explanation** - - Here is an explanation of the above array items. - - ================ ================================================ - Item Description - ================ ================================================ - file_name The name of the file that was uploaded including the file extension. - file_type The file's Mime type - file_path The absolute server path to the file - full_path The absolute server path including the file name - raw_name The file name without the extension - orig_name The original file name. This is only useful if you use the encrypted name option. - client_name The file name as supplied by the client user agent, prior to any file name preparation or incrementing. - file_ext The file extension with period - file_size The file size in kilobytes - is_image Whether the file is an image or not. 1 = image. 0 = not. - image_width Image width. - image_height Image height - image_type Image type. Typically the file extension without the period. - image_size_str A string containing the width and height. Useful to put into an image tag. - ================ ================================================ + Here's a table explaining the above-displayed array items: + + ================ ==================================================================================================== + Item Description + ================ ==================================================================================================== + file_name Name of the file that was uploaded, including the filename extension + file_type File MIME type identifier + file_path Absolute server path to the file + full_path Absolute server path, including the file name + raw_name File name, without the extension + orig_name Original file name. This is only useful if you use the encrypted name option. + client_name File name as supplied by the client user agent, prior to any file name preparation or incrementing + file_ext Filename extension, period included + file_size File size in kilobytes + is_image Whether the file is an image or not. 1 = image. 0 = not. + image_width Image width + image_height Image height + image_type Image type (usually the file name extension without the period) + image_size_str A string containing the width and height (useful to put into an image tag) + ================ ==================================================================================================== \ No newline at end of file -- cgit v1.2.3-24-g4f1b