Output functions - Revision history

Devdocsbot: Protected "Output functions": Developer Docs Migration ([Edit=Allow only administrators] (indefinite))

2022-06-14T03:18:23Z

Protected "Output functions": Developer Docs Migration ([Edit=Allow only administrators] (indefinite))

← Older revision		Revision as of 03:18, 14 June 2022
(No difference)

Devdocsbot: Update migration status and path

2022-06-14T03:16:46Z

Update migration status and path

← Older revision		Revision as of 03:16, 14 June 2022
Line 1:		Line 1:
			{{Template:Migrated\|newDocId=/docs/apis/subsystems/output#output-functions}}
	This page tries to explain a bit how dynamic data should be sent from Moodle to the browser in an organised and standard way. Obviously it's possible to have your own output methods but, thinking that you are going to share your code (yep, this is an OpenSource project!) and in the collaborative way we try to build and maintain the system every day, it would be really better to follow the basic guidelines explained below.		This page tries to explain a bit how dynamic data should be sent from Moodle to the browser in an organised and standard way. Obviously it's possible to have your own output methods but, thinking that you are going to share your code (yep, this is an OpenSource project!) and in the collaborative way we try to build and maintain the system every day, it would be really better to follow the basic guidelines explained below.

Michael-milette at 06:46, 18 December 2021

2021-12-18T06:46:52Z

Michael-milette at 20:39, 27 April 2020

2020-04-27T20:39:15Z

← Older revision		Revision as of 20:39, 27 April 2020
Line 35:		Line 35:

	* print '''any html/plain/markdown/moodle text''', needing any of the features below. Mainly used for long strings like posts, answers, glossary items...		* print '''any html/plain/markdown/moodle text''', needing any of the features below. Mainly used for long strings like posts, answers, glossary items...
	* filter content through Moodle or 3rd party language filters for multi-language support. Not to be confused with [https://docs.moodle.org/dev/String_API#get_string.28.29 get_string] which is used to access localized strings in Moodle and its language packs.		* filter content through Moodle or 3rd party language filters for multi-language support. Not to be confused with [https://docs.moodle.org/dev/String_API#get_string.28.29 get_string] which is used to access localized strings in Moodle and its language packs. Together, these functions enable Moodle multi-language support .

	Note that this function is really '''heavy''' because it supports '''cleaning''' of dangerous contents, delegates processing to enabled '''content filter'''s, supports different '''formats''' of text (HTML, PLAIN, MARKDOWN, MOODLE) and performs a lot of '''automatic conversions''' like adding smilies, build links. Also, it includes a strong '''cache mechanism''' (DB based) that will alleviate the server from a lot of work processing the same texts time and again.		Note that this function is really '''heavy''' because it supports '''cleaning''' of dangerous contents, delegates processing to enabled '''content filter'''s, supports different '''formats''' of text (HTML, PLAIN, MARKDOWN, MOODLE) and performs a lot of '''automatic conversions''' like adding smilies, build links. Also, it includes a strong '''cache mechanism''' (DB based) that will alleviate the server from a lot of work processing the same texts time and again.
Line 63:		Line 63:

	* print '''short strings (non html) that need filter processing''' (activity titles, post subjects, glossary concepts...).		* print '''short strings (non html) that need filter processing''' (activity titles, post subjects, glossary concepts...).
	* filter content through Moodle or 3rd party language filters for multi-language support. Not to be confused with [https://docs.moodle.org/dev/String_API#get_string.28.29 get_string] which is used to access localized strings in Moodle and its language packs.		* filter content through Moodle or 3rd party language filters for multi-language support. Not to be confused with [https://docs.moodle.org/dev/String_API#get_string.28.29 get_string] which is used to access localized strings in Moodle and its language packs. Together, these functions enable Moodle multi-language support .

	All enabled '''heading filters''' will be applied to the string.		All enabled '''heading filters''' will be applied to the string.

Michael-milette at 20:33, 27 April 2020

2020-04-27T20:33:53Z

← Older revision		Revision as of 20:33, 27 April 2020
Line 35:		Line 35:

	* print '''any html/plain/markdown/moodle text''', needing any of the features below. Mainly used for long strings like posts, answers, glossary items...		* print '''any html/plain/markdown/moodle text''', needing any of the features below. Mainly used for long strings like posts, answers, glossary items...
			* filter content through Moodle or 3rd party language filters for multi-language support. Not to be confused with [https://docs.moodle.org/dev/String_API#get_string.28.29 get_string] which is used to access localized strings in Moodle and its language packs.

	Note that this function is really '''heavy''' because it supports '''cleaning''' of dangerous contents, delegates processing to enabled '''content filter'''s, supports different '''formats''' of text (HTML, PLAIN, MARKDOWN, MOODLE) and performs a lot of '''automatic conversions''' like adding smilies, build links. Also, it includes a strong '''cache mechanism''' (DB based) that will alleviate the server from a lot of work processing the same texts time and again.		Note that this function is really '''heavy''' because it supports '''cleaning''' of dangerous contents, delegates processing to enabled '''content filter'''s, supports different '''formats''' of text (HTML, PLAIN, MARKDOWN, MOODLE) and performs a lot of '''automatic conversions''' like adding smilies, build links. Also, it includes a strong '''cache mechanism''' (DB based) that will alleviate the server from a lot of work processing the same texts time and again.
Line 62:		Line 63:

	* print '''short strings (non html) that need filter processing''' (activity titles, post subjects, glossary concepts...).		* print '''short strings (non html) that need filter processing''' (activity titles, post subjects, glossary concepts...).
			* filter content through Moodle or 3rd party language filters for multi-language support. Not to be confused with [https://docs.moodle.org/dev/String_API#get_string.28.29 get_string] which is used to access localized strings in Moodle and its language packs.

	All enabled '''heading filters''' will be applied to the string.		All enabled '''heading filters''' will be applied to the string.
Line 74:		Line 76:
	**'''options->escape''': To decide if you want to escape HTML entities. True by default.		**'''options->escape''': To decide if you want to escape HTML entities. True by default.
	**'''options->filter''': To decide if you want to allow filters to process the text (defaults to true). This is ignored by FORMAT_PLAIN for which filters are never applied.		**'''options->filter''': To decide if you want to allow filters to process the text (defaults to true). This is ignored by FORMAT_PLAIN for which filters are never applied.



	Note: in earlier versions of Moodle the third argument was integer $courseid. It is still supported for legacy - if the third argument is an integer instead of array or object it is considered to be course id and is this course's context is passed to the filters being applied.		Note: in earlier versions of Moodle the third argument was integer $courseid. It is still supported for legacy - if the third argument is an integer instead of array or object it is considered to be course id and is this course's context is passed to the filters being applied.

Finns: /* format_string() */

2018-02-05T19:54:13Z

format_string()

← Older revision		Revision as of 19:54, 5 February 2018
Line 71:		Line 71:
	* '''striplinks''': To decide if, after the text has been processed by filters, we must delete any link from the result text. Used when we want to show the text inside menus, page titles... (defaults to true).		* '''striplinks''': To decide if, after the text has been processed by filters, we must delete any link from the result text. Used when we want to show the text inside menus, page titles... (defaults to true).
	* '''options'''		* '''options'''
	**'''options->context''': Context (id or object) for applying filters. If context is not specified it will be taken from $PAGE->context and may potentially result in displaying the same text differently on different pages. For example all module-related information should have module context even when it appears in course-level reports, all course-related ~~informatin~~ such as name and description should have course context even when they are displayed on front page or system pages.		**'''options->context''': Context (id or object) for applying filters. If context is not specified it will be taken from $PAGE->context and may potentially result in displaying the same text differently on different pages. For example all module-related information should have module context even when it appears in course-level reports, all course-related information such as name and description should have course context even when they are displayed on front page or system pages.
	**'''options->escape''': To decide if you want to escape HTML entities. True by default.		**'''options->escape''': To decide if you want to escape HTML entities. True by default.
	**'''options->filter''': To decide if you want to allow filters to process the text (defaults to true). This is ignored by FORMAT_PLAIN for which filters are never applied.		**'''options->filter''': To decide if you want to allow filters to process the text (defaults to true). This is ignored by FORMAT_PLAIN for which filters are never applied.

Damyon: print_textarea has been deprecated since Moodle 2.0. Remove it from the docs.

2016-12-20T01:42:15Z

print_textarea has been deprecated since Moodle 2.0. Remove it from the docs.

← Older revision		Revision as of 01:42, 20 December 2016
Line 78:		Line 78:

	Note: in earlier versions of Moodle the third argument was integer $courseid. It is still supported for legacy - if the third argument is an integer instead of array or object it is considered to be course id and is this course's context is passed to the filters being applied.		Note: in earlier versions of Moodle the third argument was integer $courseid. It is still supported for legacy - if the third argument is an integer instead of array or object it is considered to be course id and is this course's context is passed to the filters being applied.

	~~=== print_textarea() ===~~

	~~function print_textarea($usehtmleditor, $rows, $cols, $width,~~
	~~$height, $name, $value=<nowiki>''</nowiki>, $courseid=0, $return=false)~~

	~~This function should be used to:~~

	* display <nowiki><textarea></nowiki> fields when we want to allow users (based in their preferences and browser capabilities) '''to use the visual HTML editor''' instead of one standard 'plain' area.

	~~Some interesting parameters for this function are:~~

	* '''usehtmleditor''': to decide if the HTML editor must be showed. The value of this parameter must be calculated by the can_use_html_editor() function.
	* '''rows, cols''': to be applied if the standard textarea is showed.
	* '''width, height''': to be applied if the HTML editor is used.
	* '''name''': the name of the field that will contain the text once the form is submitted.
	* '''value''': the initial value of the textarea.
	* '''courseid''': This parameter should be passed always to help the editor to know where it is working. This parameter will become less and less important Moodle was 100% of the current course using some session or global variable (it's one work in progress just now) but, for now, it's recommended to set it always in the function call.
	* '''return''': to decide if the generated html code must be returned to the caller (true) or printed directly (false). Defaults to false.

Cameron1729 at 08:33, 28 November 2016

2016-11-28T08:33:30Z

← Older revision		Revision as of 08:33, 28 November 2016
Line 52:		Line 52:
	**'''options->overflowdiv ''': If set to true the formatted text will be encased in a div with the class no-overflow before being returned. Default false.		**'''options->overflowdiv ''': If set to true the formatted text will be encased in a div with the class no-overflow before being returned. Default false.
	**'''options->allowid''' : If true then id attributes will not be removed, even when using htmlpurifier. Default false.		**'''options->allowid''' : If true then id attributes will not be removed, even when using htmlpurifier. Default false.
			**'''options->blanktarget''' : If true all <a> tags will have target="_blank" added unless target is explicitly specified. Default false.
	* '''courseid_do_not_use''': This parameter was earlier used to help applying filters but now is replaced with more precise $options->context, see above		* '''courseid_do_not_use''': This parameter was earlier used to help applying filters but now is replaced with more precise $options->context, see above

Cameron1729: Add new options element.

2016-11-28T08:28:56Z

Add new options element.

← Older revision		Revision as of 08:28, 28 November 2016
Line 71:		Line 71:
	* '''options'''		* '''options'''
	**'''options->context''': Context (id or object) for applying filters. If context is not specified it will be taken from $PAGE->context and may potentially result in displaying the same text differently on different pages. For example all module-related information should have module context even when it appears in course-level reports, all course-related informatin such as name and description should have course context even when they are displayed on front page or system pages.		**'''options->context''': Context (id or object) for applying filters. If context is not specified it will be taken from $PAGE->context and may potentially result in displaying the same text differently on different pages. For example all module-related information should have module context even when it appears in course-level reports, all course-related informatin such as name and description should have course context even when they are displayed on front page or system pages.
			**'''options->escape''': To decide if you want to escape HTML entities. True by default.
	**'''options->filter''': To decide if you want to allow filters to process the text (defaults to true). This is ignored by FORMAT_PLAIN for which filters are never applied.		**'''options->filter''': To decide if you want to allow filters to process the text (defaults to true). This is ignored by FORMAT_PLAIN for which filters are never applied.

Cameron1729: /* format_string() */

2016-07-06T09:24:10Z

format_string()

← Older revision		Revision as of 09:24, 6 July 2016
Line 71:		Line 71:
	* '''options'''		* '''options'''
	**'''options->context''': Context (id or object) for applying filters. If context is not specified it will be taken from $PAGE->context and may potentially result in displaying the same text differently on different pages. For example all module-related information should have module context even when it appears in course-level reports, all course-related informatin such as name and description should have course context even when they are displayed on front page or system pages.		**'''options->context''': Context (id or object) for applying filters. If context is not specified it will be taken from $PAGE->context and may potentially result in displaying the same text differently on different pages. For example all module-related information should have module context even when it appears in course-level reports, all course-related informatin such as name and description should have course context even when they are displayed on front page or system pages.
	**''options->filter'': To decide if you want to allow filters to process the text (defaults to true). This is ignored by FORMAT_PLAIN for which filters are never applied.		**'''options->filter''': To decide if you want to allow filters to process the text (defaults to true). This is ignored by FORMAT_PLAIN for which filters are never applied.

← Older revision		Revision as of 06:46, 18 December 2021
Line 6:		Line 6:

	For each of the functions below we'll try to explain when they should be used, explaining the most important parameters supported and their meaning. Let's review them!		For each of the functions below we'll try to explain when they should be used, explaining the most important parameters supported and their meaning. Let's review them!

	=== p() and s() ===		=== p() and s() ===

	function s($var, $strip=false)		function s($var, $strip=false)
	function p($var, $strip=false)		function p($var, $strip=false)

	These functions share the same code so they will be explained together. The only difference is that s() returns the string while p() prints it directly.		These functions share the same code so they will be explained together. The only difference is that s() returns the string while p() prints it directly.

	These functions should be used to:		These functions should be used to:

	* print all the '''values of form fields''' like <nowiki><input></nowiki> or <nowiki><textarea></nowiki> tags.		* print all the '''values of form fields''' like <nowiki><input></nowiki> or <nowiki><textarea></nowiki> tags.
	* to '''show plain (non html) text''' that has been introduced by the user (search string, quiz responses...).		* to '''show plain (non html) text''' that has been introduced by the user (search string, quiz responses...).
	* in general, all the '''dynamic data, not being html''', that doesn't need to be cleaned nor processed by filters		* in general, all the '''dynamic data, not being html''', that doesn't need to be cleaned nor processed by filters

	It is important not to use these functions for strings that contain html markup.		It is important not to use these functions for strings that contain html markup.

Line 25:		Line 20:

	The key parameter for this function is:		The key parameter for this function is:

	* '''strip''': it decides if we want to strip slashes from the string or no. By default it's 'false' so no strip will be performed. We should set such parameter to 'true' only when data to be processed isn't coming from database but from http requests (forms, links...).		* '''strip''': it decides if we want to strip slashes from the string or no. By default it's 'false' so no strip will be performed. We should set such parameter to 'true' only when data to be processed isn't coming from database but from http requests (forms, links...).

	=== format_text() ===		=== format_text() ===

	function format_text($text, $format = FORMAT_MOODLE, $options = null, $courseid_do_not_use = null)		function format_text($text, $format = FORMAT_MOODLE, $options = null, $courseid_do_not_use = null)

	This function should be used to:		This function should be used to:

	* print '''any html/plain/markdown/moodle text''', needing any of the features below. Mainly used for long strings like posts, answers, glossary items...		* print '''any html/plain/markdown/moodle text''', needing any of the features below. Mainly used for long strings like posts, answers, glossary items...
	* filter content through Moodle or 3rd party language filters for multi-language support. Not to be confused with [https://docs.moodle.org/dev/String_API#get_string.28.29 get_string] which is used to access localized strings in Moodle and its language packs. Together, these functions enable Moodle multi-language support .		* filter content through Moodle or 3rd party language filters for multi-language support. Not to be confused with [https://docs.moodle.org/dev/String_API#get_string.28.29 get_string] which is used to access localized strings in Moodle and its language packs. Together, these functions enable Moodle multi-language support .

	Note that this function is really '''heavy''' because it supports '''cleaning''' of dangerous contents, delegates processing to enabled '''content filter'''s, supports different '''formats''' of text (HTML, PLAIN, MARKDOWN, MOODLE) and performs a lot of '''automatic conversions''' like adding smilies, build links. Also, it includes a strong '''cache mechanism''' (DB based) that will alleviate the server from a lot of work processing the same texts time and again.		Note that this function is really '''heavy''' because it supports '''cleaning''' of dangerous contents, delegates processing to enabled '''content filter'''s, supports different '''formats''' of text (HTML, PLAIN, MARKDOWN, MOODLE) and performs a lot of '''automatic conversions''' like adding smilies, build links. Also, it includes a strong '''cache mechanism''' (DB based) that will alleviate the server from a lot of work processing the same texts time and again.

	Some interesting parameters for this function are:		Some interesting parameters for this function are:

	* '''format''': To tell the function about how the data has been entered. It defaults to FORMAT_MOODLE that is a cool format to process plain text because it features automatic link conversion, smilies and good conversion to html output. Other formats are FORMAT_HTML, FORMAT_PLAIN, FORMAT_MARKDOWN. See [[Formatting options]].		* '''format''': To tell the function about how the data has been entered. It defaults to FORMAT_MOODLE that is a cool format to process plain text because it features automatic link conversion, smilies and good conversion to html output. Other formats are FORMAT_HTML, FORMAT_PLAIN, FORMAT_MARKDOWN. See [[Formatting options]].

Line 55:		Line 43:
	**'''options->blanktarget''' : If true all <a> tags will have target="_blank" added unless target is explicitly specified. Default false.		**'''options->blanktarget''' : If true all <a> tags will have target="_blank" added unless target is explicitly specified. Default false.
	* '''courseid_do_not_use''': This parameter was earlier used to help applying filters but now is replaced with more precise $options->context, see above		* '''courseid_do_not_use''': This parameter was earlier used to help applying filters but now is replaced with more precise $options->context, see above

	=== format_string() ===		=== format_string() ===

	function format_string ($string, $striplinks = true, $options = null )		function format_string ($string, $striplinks = true, $options = null )

	This function should be used to:		This function should be used to:
			* print '''short non-html strings that need filter processing''' (activity titles, post subjects, glossary concepts...). If the string contains HTML, it will be filtered out. If you want the HTML, use format_text() instead.
	* print '''short ~~strings (~~non html) that need filter processing''' (activity titles, post subjects, glossary concepts...).
	* filter content through Moodle or 3rd party language filters for multi-language support. Not to be confused with [https://docs.moodle.org/dev/String_API#get_string.28.29 get_string] which is used to access localized strings in Moodle and its language packs. Together, these functions enable Moodle multi-language support .		* filter content through Moodle or 3rd party language filters for multi-language support. Not to be confused with [https://docs.moodle.org/dev/String_API#get_string.28.29 get_string] which is used to access localized strings in Moodle and its language packs. Together, these functions enable Moodle multi-language support .

	All enabled '''heading filters''' will be applied to the string.		All enabled '''heading filters''' will be applied to the string.

Line 70:		Line 53:

	Some interesting parameters for this function are:		Some interesting parameters for this function are:

	* '''striplinks''': To decide if, after the text has been processed by filters, we must delete any link from the result text. Used when we want to show the text inside menus, page titles... (defaults to true).		* '''striplinks''': To decide if, after the text has been processed by filters, we must delete any link from the result text. Used when we want to show the text inside menus, page titles... (defaults to true).
	* '''options'''		* '''options'''
Line 76:		Line 58:
	**'''options->escape''': To decide if you want to escape HTML entities. True by default.		**'''options->escape''': To decide if you want to escape HTML entities. True by default.
	**'''options->filter''': To decide if you want to allow filters to process the text (defaults to true). This is ignored by FORMAT_PLAIN for which filters are never applied.		**'''options->filter''': To decide if you want to allow filters to process the text (defaults to true). This is ignored by FORMAT_PLAIN for which filters are never applied.

	Note: in earlier versions of Moodle the third argument was integer $courseid. It is still supported for legacy - if the third argument is an integer instead of array or object it is considered to be course id and is this course's context is passed to the filters being applied.		Note: in earlier versions of Moodle the third argument was integer $courseid. It is still supported for legacy - if the third argument is an integer instead of array or object it is considered to be course id and is this course's context is passed to the filters being applied.