This file describes API changes in reportbuilder,
information provided here is intended especially for developers.

=== 19.1.0 ===

* Added new get_report external API service for retrieving select reports from the site.
  The new service requires a report ID, and optionally accepts a report page number; a saved search ID; and a sort option.
  The queried report must be visible to the API user, and any saved search must be shared in order to work.
* Improved new get_report external API service.
  Added report metadata return type to show report title, abstract, description, and records per page.
  Added report pagination return type to show the total number of pages in the report, as well as the next page number.
    This calculation is expensive, and so must be specified in the input with display_report_pagination, otherwise the values will return null.
  Add default report format type for the API service that converts dates and times to epoch time for convenience.
  Add support for custom formatting for columns on the report. Four type formatters are supported: date, string, text, and textarea. See the schema for details.

=== 19.0 ===

* Changed element from main to div in templates/create_report.mustache
* Removed resultcount element from templates/report_heading.mustache
* Added new rb_config option, keep_session_open. Can be used to keep sessions open, used when embedding reportbuilder as a block
  or another custom implementation where sessions may still be required on the page.
* Report builder restore_saved_search() now returns false if the search is unavailable, previously it would trigger an error.
* Removed embeddedparams declarations from the following report sources as it is unsupported in report sources:
    * rb_source_appraisal
    * rb_source_goal_custom
    * rb_source_goal_details
    * rb_source_goal_summary
* Removed defaultsortcolumn and defaultsortoder declarations from the following report sources as they are unsupported outside of embedded reports:
    * rb_source_competency_assignment_users
    * rb_source_evidence_item
* Added rowheader to report_builder_columns table and classes. If set the cell will render with a th tag insted of td.
* Updated templates/report_heading.mustache to accept a heading_level parameter
* Updated templates/clone_report_not_allowed.mustache to use a h1
* Updated heading levels in:
  * totara_reportbuilder_renderer::edit_report_heading()
  * totara_reportbuilder_renderer::edit_restriction_header()

=== 18.0 ===
* The scheduled_reports_add_form class has been deprecated and no longer in use.
* Added optional parameter $contextid of type int to totara_reportbuilder_renderer::view_all_reports_link with a default value of null
* Added optional parameter $tenantid of type int to report_helper::create with a default value of null
* Added optional parameter $tenantid of type int to totara_reportbuilder\output\create_report::create with a default value of null
* Added optional parameter $tenant_sources_only of type bool to reportbuilder::get_source_groups with a default value of false
* Added optional parameter $tenant_id of type int to the totara_reportbuilder_create_report graphql mutation
* Added optional parameter $tenant_id of type int to the totara_reportbuilder_creation_sources graphql query
* Added optional parameter $tenant_id of type int to the totara_reportbuilder_source graphql query
* Added optional parameter $context of type 'Context' to \rb_column::display_column() which defaults to the system context.
* Added optional parameter 'context_id' of type int to totara_reportbuilder\rb\content\audience::get_cohort_select_options()
  with a default value of null

=== 17.0 ===

* Toolbar filter will now display 'Save this search' button as necessary if standard filter is not visible.
* Report sources that use \reportbuilder::post_config_visibility_where() needs to be updated to disable cache
  by using $this->cacheable = false; in their __construct method.
* Reports that make use of required_columns to make checks in post_config may consider using required_joins method
  which has been added to make rid of columns that could interfiere with aggregation in reports

=== 16.0 ===

--- Update to graphQL ---
* Updated field 'title' scalar type 'param_text' to 'String' for mutation 'totara_reportbuilder_update_report_title'

--- Update to Report Builder ---
* Added optional parameter 'validate_sesskey' of type 'bool' to \reportbuilder::export_data() with default value of 'true' to
  validate the sesskey parameter on report export form submission.

=== 14.0 ===

* rb_filter_text::setupForm() now receives a new optional parameter 'hiddenoperator' which allows change an array of comparison operators
* template_helper::get_template_groups() now by default excludes groups which only contain templates belonging
  to sources that are disabled or non-selectable. Groups containing only non-selectable sources can be included
  by specifying the new optional parameter includenonselectable.
* totara_reportbuilder/chartjs had been modified, adding resizer auto initalization code

=== 13.1 ===

* Cloning of embedded reports can be prevented by overriding \rb_base_embedded::is_cloning_allowed(), and a custom
  message explaining why it can't be cloned can be specified with \rb_base_embedded::get_cloning_not_allowed_message()

=== 13.0 ===

* totara report builder does not accept a seminar event role column with the hyphen
* rb_filter_type::get_filter() has a new optional parameter $filteringrequired
* all filters must implement \rb_filter_type::is_filtering() method
* all embedded reports need to be updated to use \totara_reportbuilder_renderer::showhide_button($report)
  instead of report id and short name parameters
* totara_reportbuilder_renderer::showhide_button() expect reportbuilder object instead of id and shortname
* removed support for deprecated counted record sets
* reportbuilder_get_embedded_report_object() has been deprecated. Please consider calling
  reportbuilder::get_embedded_report_class() and creating embedded report objects directly instead.
* rb_base_source::is_ignored() has been deprecated. Please use rb_base_source::is_source_ignored()
  static method instead.
* rb_base_embedded::is_ignored() has been deprecated. Please use rb_base_embedded::is_report_ignored()
  static method instead.
* unused renderer methods totara_reportbuilder_renderer::user_generated_reports_table() and
  totara_reportbuilder_renderer::embedded_reports_table() have been deprecated.
* Deprecated display method rb_display_deleted_status() has been removed
* Deprecated graph::reset_records() has been removed
* Deprecated rb_base_source::language_code_to_name instead use totara_core\helper::language_code_to_name
* Deprecated reportbuilder::get_counted_recordset_sql, this method was private and should not have been used outside
  of this class. The methods get_data_for_table() and get_data() replace it.
* totara_reportbuilder_renderer::save_button() has been deprecated. The save search button is now being handled via
  totara_reportbuilder_renderer::display_search().
* reportbuilder::display_saved_search_options() no longer returns the html instead calling moodleform::display for the
  display of the saved search options.
* Deprecated reportbuilder::view_saved_menu(). Use reportbuilder::display_saved_search_options()
* totara_reportbuilder_renderer::saved_searches_table() has been updated to also display the report saved search default.
* reportbuilder::get_saved_searches() first argument is no longer used. Functionality has not changed.
* reportbuilder::get_saved_searches() second argument is no longer used. Functionality has not changed.
* reportbuilder::get_columns_select() now returns an array of objects instead of strings (previously, column names).
  To extract column names, please use 'name' property of the result array.
* Removed no longer used ajax/graph.php file
* Updated default colours for report graphs
* Deprecated reportbuilder_get_export_options(), please use reportbuilder::get_all_general_export_options()
* totara_reportbuilder_renderer::result_count_info has been updated adding status role for screen readers
* The following reportbuilder/lib.php global variables have been deprecated and should no longer be used:
  * REPORT_BUILDER_PDF_FONT_SIZE_DATA
  * REPORT_BUILDER_PDF_FONT_SIZE_RECORD
  * REPORT_BUILDER_PDF_FONT_SIZE_TITLE
* Deprecated report source rb_source_competency_evidence. Please use rb_source_competency_status
* Added method rb_base_source::get_join() for accessing joins between rb traits

=== 12.0 ===

* Column and filter option 'grouping' setting is now deprecated and will be removed in Totara 13, use subqueries instead.
* rb_source_course_completion_by_org source was trimmed down due to conversion subqueries, it is recommended
  to check all reports based on this source and update them or replace them with regular completion report using custom aggregation.
* Function reportbuilder_get_embedded_report() has been deprecated, please use reportbuilder::create_embedded() instead.
* Obsolete non-functional support for report groups was removed.
* Display classes may now use repoert->displaycache array to improve performance
* Added 'selectionlimit' option to manager field filters. "{$CFG->totara_reportbuilder_filter_selected_managers_limit}"
  introduced to limit the number of selected managers in the report builder job assignment filter dialog.
  Default value is 25, to make it unlimited, set it to 0.
* rb_prog_availability_content class has been deprecated.
* Removed deprecated methods:
  * reportbuilder_get_reports()
  * sql_group_concat()
  * totara_reportbuilder_renderer::print_result_count_string()
* Added public 'deprecated' property to the rb_column_options class. Use this property to mark columns as deprecated and
  warn users if their reports contain deprecated columns that should no longer be used.
* Added rb_base_source::get_deprecated_column_options() which returns all deprecated the column options.
* The following columns have been deprecated in rb_base_source::add_user_fields_to_columns():
  * jobassignments
  * jobpositionnames
  * jobpositionidnumbers
  * joborganisationnames
  * joborganisationidnumbers
  * jobmanagernames
  * jobappraisernames
  * jobtempmanagernames
  Consider switching to the 'job_assignments' report source as an alternative.
* The following functions have been deprecated and moved into traits
  * add_course_table_to_joinlist instead use add_core_course_tables in \course\rb\source\report_trait
  * add_course_fields_to_columns instead use add_core_course_columns in \course\rb\source\report_trait
  * add_course_fields_to_filters instead use add_core_course_filters in \core_course\rb\source\report_trait
  * add_course_category_table_to_joinlist instead use add_core_course_category_tables in \core_course\rb\source\report_trait
  * add_course_category_fields_to_columns instead use add_core_course_category_columns in \core_course\rb\source\report_trait
  * add_course_category_fields_to_filters instead use add_core_course_category_filters in \core_course\rb\source\report_trait
  * add_user_table_to_joinlist instead use add_core_user_tables in \core_user\rb\source\report_trait
  * add_user_fields_to_columns instead use add_core_user_columns in \core_user\rb\source\report_trait
  * add_user_fields_to_filters instead use add_core_user_fields in \core_user\rb\source\report_trait
  * add_context_table_to_joinlist instead use add_context_tables in \totara_reportbuilder\rb\source\report_trait
  * add_program_table_to_joinlist instead use add_totara_program_tables in \totara_program\rb\source\program_trait
  * add_program_fields_to_columns instead use add_totara_program_columns in \totara_program\rb\source\program_trait
  * add_program_fields_to_filters instead use add_totara_program_filters in \totara_program\rb\source\program_trait
  * add_certification_table_to_joinlist instead use add_totara_certification_tables in \totara_certification\rb\source\certification_trait
  * add_certification_fields_to_columns instead use add_totara_certification_columns in \totara_certification\rb\source\certification_trait
  * add_certification_fields_to_filters instead use add_totara_certification_filters in \totara_certification\rb\source\certification_trait
  * add_job_assignment_table_to_joinlist instead use add_totara_job_tables in \totara_job\rb\source\report_trait
  * add_job_assignment_fields_to_columns instead use add_totara_job_columns in \totara_job\rb\source\report_trait
  * add_job_assignment_fields_to_filters instead use add_totara_job_filters in \totara_job\rb\source\report_trait
  * add_job_custom_field_joins instead use add_totara_job_custom_field_tables in \totara_job\rb\source\report_trait
  * add_job_custom_field_columns instead use add_totara_job_custom_field_columns in \totara_job\rb\source\report_trait
  * add_job_custom_field_filters instead use add_totara_job_custom_field_filters in \totara_job\rb\source\report_trait
  * add_core_tag_tables_to_joinlist instead use add_core_tag_tables in \core_tag\rb\source\report_trait
  * add_core_tag_fields_to_columns instead use add_core_tag_columns in \core_tag\rb\source\report_trait
  * add_core_tag_fields_to_filters instead use add_core_tag_filters in \core_tag\rb\source\report_trait
  * add_cohort_user_tables_to_joinlist is not supposed to be used any more
  * add_cohort_course_table_to_joinlist instead use add_totara_cohort_course_tables in \totara_cohort\rb\source\report_trait
  * add_cohort_program_tables_to_joinlist instead use add_totara_cohort_program_tables in \totara_cohort\rb\source\report_trait
  * add_cohort_user_fields_to_columns is not supposed to be used any more
  * add_cohort_course_fields_to_columns instead use add_totara_cohort_course_columns in \totara_cohort\rb\source\report_trait
  * add_cohort_program_fields_to_columns instead use add_totara_cohort_program_columns in \totara_cohort\rb\source\report_trait
  * add_cohort_user_fields_to_filters is not supposed to be used any more
  * add_cohort_course_fields_to_filters instead use add_totara_cohort_course_filters in \totara_cohort\rb\source\report_trait
  * add_cohort_program_fields_to_filters instead use add_totara_cohort_program_filters in \totara_cohort\rb\source\report_trait
* Deprecated the following report builder display functions and replaced with display classes
  * rb_base_source::create_expand_link()
  * rb_base_source::rb_display_nice_time()
  * rb_base_source::rb_display_nice_datetime_in_timezone()
  * rb_base_source::rb_display_delimitedlist_date_in_timezone()
  * rb_base_source::rb_display_delimitedlist_datetime_in_timezone()
  * rb_base_source::format_delimitedlist_datetime_in_timezone()
  * rb_base_source::rb_display_round2()
  * rb_base_source::rb_display_nice_datetime_seconds()
  * rb_base_source::rb_display_round2()
  * rb_base_source::rb_display_percent()
  * rb_base_source::rb_display_list_to_newline()
  * rb_base_source::rb_display_delimitedlist_to_newline()
  * rb_base_source::rb_display_delimitedlist_multi_to_newline()
  * rb_base_source::display_delimitedlist_url_to_newline()
  * rb_base_source::rb_display_delimitedlist_posfiles_to_newline()
  * rb_base_source::rb_display_delimitedlist_orgfiles_to_newline()
  * rb_base_source::delimitedlist_files_to_newline()
  * rb_base_source::rb_display_delimitedlist_location_to_newline()
  * rb_base_source::rb_display_list_to_newline_date()
  * rb_base_source::rb_display_orderedlist_to_newline_date()
  * rb_base_source::rb_display_delimitedlist_to_newline_date()
  * rb_base_source::rb_display_location(), please call totara_reportbuilder\rb\display\customfield_location::display() instead.
  * rb_base_source::rb_display_course_grade_percent()
  * rb_base_source::rb_display_link_user()
  * rb_base_source::rb_display_link_user_icon()
  * rb_base_source::rb_display_user_picture()
  * rb_base_source::rb_display_user()
  * rb_base_source::rb_display_course_expand()
  * rb_base_source::rb_display_program_expand(), please call totara_program\rb\display\program_expand::display() instead.
  * rb_base_source::certif_certifpath(), please call totara_certification\rb\display\certif_certifpath::display() instead.
  * rb_base_source::rb_display_link_course()
  * rb_base_source::rb_display_link_course_icon()
  * rb_base_source::rb_display_course_icon()
  * rb_base_source::rb_display_course_type_icon()
  * rb_base_source::rb_display_course_type()
  * rb_base_source::rb_display_link_course_category()
  * rb_base_source::rb_display_audience_visibility(), please call totara_cohort\rb\display\cohort_visibility::display() instead.
  * rb_base_source::rb_display_planlink(), please call totara_plan\rb\display\plan_link::display() instead.
  * rb_base_source::rb_display_plan_status(), please call totara_plan\rb\display\plan_status::display() instead.
  * rb_base_source::rb_display_plan_item_status(), please call totara_plan\rb\display\plan_item_status::display() instead.
  * rb_base_source::rb_display_yes_no()
  * rb_base_source::rb_display_delimitedlist_yes_no()
  * rb_base_source::rb_display_duration()
  * rb_base_source::rb_display_country_code()
  * rb_base_source::rb_display_nice_hierarchy_path(), please call totara_hierarchy\rb\display\hierarchy_nice_path::display() instead.
  * rb_base_source::rb_display_language_code()
  * rb_base_source::rb_display_orderedlist_to_newline_email()
  * rb_base_source::rb_display_link_program_icon(), please call totara_program\rb\display\program_icon_link::display() instead.
  * rb_base_source::rb_display_recertifydatetype(), please call totara_certification\rb\display\certif_recertify_date_type::display() instead.
  * rb_source_user::rb_display_learning_icons()
  * rb_source_user::rb_display_extension_link()
  * rb_source_user::rb_display_user_with_links()
  * rb_source_user::rb_display_count()
  * rb_base_source::rb_display_grade_string()
  * rb_source_competency_evidence::rb_display_status_history_link()
  * rb_source_competency_evidence::rb_display_link_competency()
  * rb_source_course_completion::rb_display_completion_status()
  * rb_source_course_completion::rb_display_course_progress()
  * rb_source_courses::rb_display_modicons()
  * rb_source_site_logs::rb_display_link_action()
  * rb_source_site_logs::rb_display_iplookup()
  * rb_source_upgrade_log::rb_display_backtrace()
  * rb_source_upgrade_log::rb_display_upgradelogtype()
  * rb_source_user::rb_display_extension_link()
* The following functions have been deprecated and moved into traits:
  * add_custom_fields_for instead use add_totara_customfield_component in totara_customfield\rb\source\report_trait
  * add_custom_user_fields instead use add_core_user_customfield in core_user\rb\source\report_trait
  * add_custom_evidence_fields instead use add_totara_customfield_component in totara_customfield\rb\source\report_trait
  * add_custom_course_fields instead use add_totara_customfield_component in totara_customfield\rb\source\report_trait
  * add_custom_prog_fields instead use add_totara_customfield_component in totara_customfield\rb\source\report_trait
  * add_custom_organisation_fields instead use add_totara_customfield_component in totara_customfield\rb\source\report_trait
  * add_custom_position_fields instead use add_totara_customfield_component in totara_customfield\rb\source\report_trait
  * add_custom_goal_fields instead use add_totara_customfield_component in totara_customfield\rb\source\report_trait
  * add_custom_personal_goal_fields instead use add_totara_customfield_component in totara_customfield\rb\source\report_trait
  * add_custom_competency_fields instead use add_totara_customfield_component in totara_customfield\rb\source\report_trait
* Added a new filter option 'help' which accepts array of ['string', 'component'] to override default filter help popup
  language string, note it follows rules of addHelpButton, so if you supply string named 'myhelpstring' the system
  would look for 'myhelpstring' and 'myhelpstring_help'.
* totara_reportbuilder\rb\display\formatstring has been renamed to totara_reportbuilder\rb\display\format_string, please update all uses.

=== 11.0 ===

* Triggering of "\totara_reportbuilder\event\report_updated" event for deletion of scheduled reports has been
  deprecated. Use "\totara_reportbuilder\event\scheduled_report_deleted" event instead.
* Display method rb_display_deleted_status has been deprecated and replaced by
  totara/reportbuilder/classes/rb/display/user_status.php

=== 10.0 ===

* Added add_cohort_user_* calls to the add_user_* functions in the base source.
  If add_user_* and add_cohort_user_* are both called within a custom source it will cause an SQL error.

* add_cohort_user_fields_to_columns has had its second parameter renamed to $join to better
  describe the what it is. The function is identical to before the change however the default is
  now 'ausercohort'.

* add_cohort_user_fields_to_columns and add_cohort_fields_to_filters have 2 new parameters
  $groupname and $addtypetoheading.

* add_cohort_user_tables_to_joinlist has a new parameter $alias to allow multiple instances
  of cohort tables to be added to a single report source.

* Added rb_session_roles_content class in totara/reportbuilder/classes/rb_base_content.php
  to allow Seminar report content to be restricted by an event role in
  facetoface_events, facetoface_sessions and facetoface_summary reports
* Removed unused $graphrecord and $isexport parameters from totara/reportbuilder/classes/local/graph::__construct()
* Added isexport param to rb_base_source::rb_display_link_program_icon.
* rb_display_orderedlist_to_newline() is now deprecated
* rb_display_certif_renewalstatus has been moved in to a new auto-loading style of
  display function (\totara_certification\rb\display\certif_renewalstatus) to use this
  function $this->usedcomponents[] = 'totara_certification'; must be set in the
  constructor for the report source.

* The sql_group_concat function has been deprecated, use $DB->sql_group_concat_unique function instead.

* add_tag_fields_to_columns, add_tag_fields_to_filters and add_tag_tables_to_joinlist have all been deprecated and
  replaced with add_core_fields_to_columns, add_core_tag_fields_to_filters and add_core_tag_tables_to_joinlist
  done to match the new tag collections.

* view_all_reports_link() renderer method now requires argument $embedded

* rb_base_source::rb_display_user_email() has been deprecated, use the
  totara/reportbuilder/classes/rb/display/user_email class instead.

* rb_base_source::rb_display_user_email_unobscured() has been deprecated, use the
  totara/reportbuilder/classes/rb/display/user_email_unobscured class instead.
