From c8f34854d6fe11f0b71aa6b1ebb30412937f062c Mon Sep 17 00:00:00 2001 From: Andrey Andreev Date: Fri, 3 Jan 2014 13:47:27 +0200 Subject: [ci skip] Update the Output library docs --- user_guide_src/source/libraries/output.rst | 224 +++++++++++++++-------------- 1 file changed, 120 insertions(+), 104 deletions(-) (limited to 'user_guide_src/source/libraries/output.rst') diff --git a/user_guide_src/source/libraries/output.rst b/user_guide_src/source/libraries/output.rst index a3d67b847..a518f853d 100644 --- a/user_guide_src/source/libraries/output.rst +++ b/user_guide_src/source/libraries/output.rst @@ -2,7 +2,7 @@ Output Class ############ -The Output class is a small class with one main function: To send the +The Output class is a core class with one main function: To send the finalized web page to the requesting browser. It is also responsible for :doc:`caching <../general/caching>` your web pages, if you use that feature. @@ -16,159 +16,175 @@ use the :doc:`Loader <../libraries/loader>` class to load a view file, it's automatically passed to the Output class, which will be called automatically by CodeIgniter at the end of system execution. It is possible, however, for you to manually intervene with the output if you -need to, using either of the two following functions: +need to. -$this->output->set_output(); -============================= +*************** +Class Reference +*************** -Permits you to manually set the final output string. Usage example:: +.. class:: CI_Output - $this->output->set_output($data); + .. attribute:: $parse_exec_vars = TRUE; -.. important:: If you do set your output manually, it must be the last - thing done in the function you call it from. For example, if you build a - page in one of your controller functions, don't set the output until the - end. + Enables/disables parsing of the {elapsed_time} and {memory_usage} pseudo-variables. -$this->output->set_content_type(); -==================================== + CodeIgniter will parse those tokens in your output by default. To disable this, set + this property to FALSE in your controller. + :: -Permits you to set the mime-type of your page so you can serve JSON -data, JPEG's, XML, etc easily. + $this->output->parse_exec_vars = FALSE; -:: + .. method:: set_output($output) - $this->output - ->set_content_type('application/json') - ->set_output(json_encode(array('foo' => 'bar'))); + :param string $output: String to set the output to + :returns: object - $this->output - ->set_content_type('jpeg') // You could also use ".jpeg" which will have the full stop removed before looking in config/mimes.php - ->set_output(file_get_contents('files/something.jpg')); + Permits you to manually set the final output string. Usage example:: -.. important:: Make sure any non-mime string you pass to this method - exists in config/mimes.php or it will have no effect. + $this->output->set_output($data); -You can also set the character set of the document, by passing a second argument:: + .. important:: If you do set your output manually, it must be the last thing done + in the function you call it from. For example, if you build a page in one + of your controller functions, don't set the output until the end. - $this->output->set_content_type('css', 'utf-8'); + .. method:: set_content_type($mime_type[, $charset = NULL]) -$this->output->get_content_type() -================================= + :param string $mime_type: MIME Type idenitifer string + :param string $charset: Character set + :returns: object -Returns the Content-Type HTTP header that's currently in use, -excluding the character set value. + Permits you to set the mime-type of your page so you can serve JSON data, JPEG's, XML, etc easily. + :: - $mime = $this->output->get_content_type(); + $this->output + ->set_content_type('application/json') + ->set_output(json_encode(array('foo' => 'bar'))); -.. note:: If not set, the default return value is 'text/html'. + $this->output + ->set_content_type('jpeg') // You could also use ".jpeg" which will have the full stop removed before looking in config/mimes.php + ->set_output(file_get_contents('files/something.jpg')); -$this->output->get_header() -=========================== + .. important:: Make sure any non-mime string you pass to this method + exists in *application/config/mimes.php* or it will have no effect. -Gets the requested HTTP header value, if set. + You can also set the character set of the document, by passing a second argument:: -If the header is not set, NULL will be returned. -If an empty value is passed to the method, it will return FALSE. + $this->output->set_content_type('css', 'utf-8'); -Example:: + .. method:: get_content_type() - $this->output->set_content_type('text/plain', 'UTF-8'); - echo $this->output->get_header('content-type'); - // Outputs: text/plain; charset=utf-8 + :returns: string -.. note:: The header name is compared in a case-insensitive manner. + Returns the Content-Type HTTP header that's currently in use, excluding the character set value. + :: -.. note:: Raw headers sent via PHP's native ``header()`` function are - also detected. + $mime = $this->output->get_content_type(); -$this->output->get_output() -=========================== + .. note:: If not set, the default return value is 'text/html'. -Permits you to manually retrieve any output that has been sent for -storage in the output class. Usage example:: + .. method:: get_header($header) - $string = $this->output->get_output(); + :param string $header: HTTP header name + :returns: string -Note that data will only be retrievable from this function if it has -been previously sent to the output class by one of the CodeIgniter -functions like $this->load->view(). + Returns the requested HTTP header value, or NULL if the requested header is not set. + Example:: -$this->output->append_output(); -================================ + $this->output->set_content_type('text/plain', 'UTF-8'); + echo $this->output->get_header('content-type'); + // Outputs: text/plain; charset=utf-8 -Appends data onto the output string. Usage example:: + .. note:: The header name is compared in a case-insensitive manner. - $this->output->append_output($data); + .. note:: Raw headers sent via PHP's native ``header()`` function are also detected. -$this->output->set_header(); -============================= + .. method:: get_output() -Permits you to manually set server headers, which the output class will -send for you when outputting the final rendered display. Example:: + :returns: string - $this->output->set_header("HTTP/1.0 200 OK"); - $this->output->set_header("HTTP/1.1 200 OK"); - $this->output->set_header('Last-Modified: '.gmdate('D, d M Y H:i:s', $last_update).' GMT'); - $this->output->set_header("Cache-Control: no-store, no-cache, must-revalidate"); - $this->output->set_header("Cache-Control: post-check=0, pre-check=0"); - $this->output->set_header("Pragma: no-cache"); + Permits you to manually retrieve any output that has been sent for + storage in the output class. Usage example:: -$this->output->set_status_header(code, 'text'); -================================================= + $string = $this->output->get_output(); -Permits you to manually set a server status header. Example:: + Note that data will only be retrievable from this function if it has + been previously sent to the output class by one of the CodeIgniter + functions like ``$this->load->view()``. - $this->output->set_status_header('401'); - // Sets the header as: Unauthorized + .. method:: append_output($output) -`See here `_ for -a full list of headers. + :param string $output: Additional output data to append + :returns: object -.. note:: This method is an alias for :doc:`Common function <../general/common_functions>` - ``set_status_header()``. + Appends data onto the output string. + :: -$this->output->enable_profiler(); -================================== + $this->output->append_output($data); -Permits you to enable/disable the -:doc:`Profiler <../general/profiling>`, which will display benchmark -and other data at the bottom of your pages for debugging and -optimization purposes. + .. method:: set_header($header[, $replace = TRUE]) -To enable the profiler place the following function anywhere within your -:doc:`Controller <../general/controllers>` functions:: + :param string $header: HTTP Header + :param bool $replace: Whether to replace the old header value, if it is already set + :returns: object - $this->output->enable_profiler(TRUE); + Permits you to manually set server headers, which the output class will + send for you when outputting the final rendered display. Example:: -When enabled a report will be generated and inserted at the bottom of -your pages. + $this->output->set_header('HTTP/1.0 200 OK'); + $this->output->set_header('HTTP/1.1 200 OK'); + $this->output->set_header('Last-Modified: '.gmdate('D, d M Y H:i:s', $last_update).' GMT'); + $this->output->set_header('Cache-Control: no-store, no-cache, must-revalidate'); + $this->output->set_header('Cache-Control: post-check=0, pre-check=0'); + $this->output->set_header('Pragma: no-cache'); -To disable the profiler you will use:: + .. method:: set_status_header([$code = 200[, $text = '']]) - $this->output->enable_profiler(FALSE); + :param int $code: HTTP status code + :param string $text: Optional message + :returns: object -$this->output->set_profiler_sections(); -========================================= + Permits you to manually set a server status header. Example:: -Permits you to enable/disable specific sections of the Profiler when -enabled. Please refer to the :doc:`Profiler <../general/profiling>` -documentation for further information. + $this->output->set_status_header('401'); + // Sets the header as: Unauthorized -$this->output->cache(); -======================= + `See here `_ for a full list of headers. -The CodeIgniter output library also controls caching. For more -information, please see the :doc:`caching -documentation <../general/caching>`. + .. note:: This method is an alias for :doc:`Common function <../general/common_functions>` + :func:`set_status_header()`. -Parsing Execution Variables -=========================== + .. method:: enable_profiler([$val = TRUE]) -CodeIgniter will parse the pseudo-variables {elapsed_time} and -{memory_usage} in your output by default. To disable this, set the -$parse_exec_vars class property to FALSE in your controller. -:: + :param bool $val: Whether to enable or disable the Profiler + :returns: object - $this->output->parse_exec_vars = FALSE; + Permits you to enable/disable the :doc:`Profiler <../general/profiling>`, which will display benchmark + and other data at the bottom of your pages for debugging and optimization purposes. + To enable the profiler place the following line anywhere within your + :doc:`Controller <../general/controllers>` methods:: + + $this->output->enable_profiler(TRUE); + + When enabled a report will be generated and inserted at the bottom of your pages. + + To disable the profiler you would use:: + + $this->output->enable_profiler(FALSE); + + .. method:: set_profiler_sections($sections) + + :param array $sections: Profiler sections + :returns: object + + Permits you to enable/disable specific sections of the Profiler when it is enabled. + Please refer to the :doc:`Profiler <../general/profiling>` documentation for further information. + + .. method:: cache($time) + + :param int $time: Cache expiration time in seconds + :returns: object + + Caches the current page for the specified amount of seconds. + + For more information, please see the :doc:`caching documentation <../general/caching>`. \ No newline at end of file -- cgit v1.2.3-24-g4f1b From cc042095bcce9856402cc04997f44310074716e0 Mon Sep 17 00:00:00 2001 From: Andrey Andreev Date: Fri, 3 Jan 2014 17:08:27 +0200 Subject: [ci skip] Some more generic user guide cleanup --- user_guide_src/source/libraries/output.rst | 7 +++++++ 1 file changed, 7 insertions(+) (limited to 'user_guide_src/source/libraries/output.rst') diff --git a/user_guide_src/source/libraries/output.rst b/user_guide_src/source/libraries/output.rst index a518f853d..76197bdc1 100644 --- a/user_guide_src/source/libraries/output.rst +++ b/user_guide_src/source/libraries/output.rst @@ -18,6 +18,13 @@ automatically by CodeIgniter at the end of system execution. It is possible, however, for you to manually intervene with the output if you need to. +.. contents:: + :local: + +.. raw:: html + +
+ *************** Class Reference *************** -- 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/output.rst | 59 ++++++++++++++++++------------ 1 file changed, 35 insertions(+), 24 deletions(-) (limited to 'user_guide_src/source/libraries/output.rst') diff --git a/user_guide_src/source/libraries/output.rst b/user_guide_src/source/libraries/output.rst index 76197bdc1..e49ea5366 100644 --- a/user_guide_src/source/libraries/output.rst +++ b/user_guide_src/source/libraries/output.rst @@ -43,8 +43,9 @@ Class Reference .. method:: set_output($output) - :param string $output: String to set the output to - :returns: object + :param string $output: String to set the output to + :returns: CI_Output instance (method chaining) + :rtype: CI_Output Permits you to manually set the final output string. Usage example:: @@ -52,13 +53,14 @@ Class Reference .. important:: If you do set your output manually, it must be the last thing done in the function you call it from. For example, if you build a page in one - of your controller functions, don't set the output until the end. + of your controller methods, don't set the output until the end. .. method:: set_content_type($mime_type[, $charset = NULL]) - :param string $mime_type: MIME Type idenitifer string - :param string $charset: Character set - :returns: object + :param string $mime_type: MIME Type idenitifer string + :param string $charset: Character set + :returns: CI_Output instance (method chaining) + :rtype: CI_Output Permits you to set the mime-type of your page so you can serve JSON data, JPEG's, XML, etc easily. :: @@ -80,7 +82,8 @@ Class Reference .. method:: get_content_type() - :returns: string + :returns: Content-Type string + :rtype: string Returns the Content-Type HTTP header that's currently in use, excluding the character set value. :: @@ -91,8 +94,9 @@ Class Reference .. method:: get_header($header) - :param string $header: HTTP header name - :returns: string + :param string $header: HTTP header name + :returns: HTTP response header or NULL if not found + :rtype: mixed Returns the requested HTTP header value, or NULL if the requested header is not set. Example:: @@ -107,7 +111,8 @@ Class Reference .. method:: get_output() - :returns: string + :returns: Output string + :rtype: string Permits you to manually retrieve any output that has been sent for storage in the output class. Usage example:: @@ -120,8 +125,9 @@ Class Reference .. method:: append_output($output) - :param string $output: Additional output data to append - :returns: object + :param string $output: Additional output data to append + :returns: CI_Output instance (method chaining) + :rtype: CI_Output Appends data onto the output string. :: @@ -130,9 +136,10 @@ Class Reference .. method:: set_header($header[, $replace = TRUE]) - :param string $header: HTTP Header - :param bool $replace: Whether to replace the old header value, if it is already set - :returns: object + :param string $header: HTTP response header + :param bool $replace: Whether to replace the old header value, if it is already set + :returns: CI_Output instance (method chaining) + :rtype: CI_Output Permits you to manually set server headers, which the output class will send for you when outputting the final rendered display. Example:: @@ -146,9 +153,10 @@ Class Reference .. method:: set_status_header([$code = 200[, $text = '']]) - :param int $code: HTTP status code - :param string $text: Optional message - :returns: object + :param int $code: HTTP status code + :param string $text: Optional message + :returns: CI_Output instance (method chaining) + :rtype: CI_Output Permits you to manually set a server status header. Example:: @@ -162,8 +170,9 @@ Class Reference .. method:: enable_profiler([$val = TRUE]) - :param bool $val: Whether to enable or disable the Profiler - :returns: object + :param bool $val: Whether to enable or disable the Profiler + :returns: CI_Output instance (method chaining) + :rtype: CI_Output Permits you to enable/disable the :doc:`Profiler <../general/profiling>`, which will display benchmark and other data at the bottom of your pages for debugging and optimization purposes. @@ -181,16 +190,18 @@ Class Reference .. method:: set_profiler_sections($sections) - :param array $sections: Profiler sections - :returns: object + :param array $sections: Profiler sections + :returns: CI_Output instance (method chaining) + :rtype: CI_Output Permits you to enable/disable specific sections of the Profiler when it is enabled. Please refer to the :doc:`Profiler <../general/profiling>` documentation for further information. .. method:: cache($time) - :param int $time: Cache expiration time in seconds - :returns: object + :param int $time: Cache expiration time in seconds + :returns: CI_Output instance (method chaining) + :rtype: CI_Output Caches the current page for the specified amount of seconds. -- cgit v1.2.3-24-g4f1b