Search moodle.org's
Developer Documentation

See Release Notes
Long Term Support Release

  • Bug fixes for general core bugs in 4.1.x will end 13 November 2023 (12 months).
  • Bug fixes for security issues in 4.1.x will end 10 November 2025 (36 months).
  • PHP version: minimum PHP 7.4.0 Note: minimum PHP version has increased since Moodle 4.0. PHP 8.0.x is supported too.
/lib/ -> tablelib.php (source)

Differences Between: [Versions 310 and 401] [Versions 311 and 401] [Versions 39 and 401] [Versions 400 and 401] [Versions 401 and 402] [Versions 401 and 403]

(no description)

Copyright: 1999 onwards Martin Dougiamas {@link http://moodle.com}
License: http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
File Size: 2391 lines (81 kb)
Included or required:0 times
Referenced: 2 times
Includes or requires: 0 files

Defines 5 classes

flexible_table:: (94 methods):
  __construct()
  is_downloading()
  export_class_instance()
  is_downloadable()
  is_persistent()
  show_download_buttons_at()
  sortable()
  text_sorting()
  no_sorting()
  is_sortable()
  collapsible()
  pageable()
  initialbars()
  pagesize()
  set_control_variables()
  set_attribute()
  column_suppress()
  column_class()
  column_style()
  set_columnsattributes()
  column_style_all()
  define_baseurl()
  define_columns()
  define_headers()
  define_header_column()
  define_help_for_headers()
  mark_table_to_reset()
  is_resetting_preferences()
  setup()
  get_sort_for_table()
  construct_order_by()
  get_sql_sort()
  contains_fullname_columns()
  get_sort_columns()
  get_page_start()
  get_page_size()
  get_sql_where()
  add_data_keyed()
  format_and_add_array_of_rows()
  add_separator()
  add_data()
  finish_output()
  wrap_html_start()
  wrap_html_finish()
  format_row()
  col_fullname()
  other_cols()
  format_text()
  print_html()
  get_initial_first()
  get_initial_last()
  print_one_initials_bar()
  print_initials_bar()
  print_nothing_to_display()
  get_row_from_keyed()
  download_buttons()
  start_output()
  print_row()
  get_row_html()
  get_row_cells_html()
  finish_html()
  show_hide_link()
  print_headers()
  set_sorting_preferences()
  set_initials_preferences()
  set_hide_show_preferences()
  set_hidden_columns()
  initialise_table_preferences()
  save_preferences()
  set_sortdata()
  get_default_per_page()
  set_default_per_page()
  set_first_initial()
  set_last_initial()
  set_page_number()
  sort_icon()
  sort_order_name()
  sort_link()
  get_primary_sort_order()
  get_sort_order()
  get_component()
  get_handler()
  get_dynamic_table_html_start()
  get_dynamic_table_html_end()
  start_html()
  set_caption()
  render_caption()
  make_styles_string()
  render_reset_button()
  can_be_reset()
  get_context()
  set_filterset()
  get_filterset()
  guess_base_url()

table_sql:: (8 methods):
  __construct()
  build_table()
  close_recordset()
  get_row_class()
  set_count_sql()
  set_sql()
  query_db()
  out()

table_default_export_format_parent:: (2 methods):
  __construct()
  table_default_export_format_parent()

name:: (6 methods):
  set_table()
  add_data()
  add_seperator()
  document_started()
  format_text()
  format_data()

table_dataformat_export_format:: (8 methods):
  __construct()
  supports_html()
  start_document()
  start_table()
  output_headers()
  add_data()
  finish_table()
  finish_document()


Class: flexible_table  - X-Ref


__construct($uniqueid)   X-Ref
Constructor

param: string $uniqueid all tables have to have a unique id, this is used

is_downloading($download = null, $filename='', $sheettitle='')   X-Ref
Call this to pass the download type. Use :
$download = optional_param('download', '', PARAM_ALPHA);
To get the download type. We assume that if you call this function with
params that this table's data is downloadable, so we call is_downloadable
for you (even if the param is '', which means no download this time.
Also you can call this method with no params to get the current set
download type.

param: string $download dataformat type. One of csv, xhtml, ods, etc
param: string $filename filename for downloads without file extension.
param: string $sheettitle title for downloaded data.
return: string download dataformat type. One of csv, xhtml, ods, etc

export_class_instance($exportclass = null)   X-Ref
Get, and optionally set, the export class.

param: $exportclass (optional) if passed, set the table to use this export class.
return: table_default_export_format_parent the export class in use (after any set).

is_downloadable($downloadable = null)   X-Ref
Probably don't need to call this directly. Calling is_downloading with a
param automatically sets table as downloadable.

param: bool $downloadable optional param to set whether data from
return: bool whether table data is set to be downloadable.

is_persistent($persistent = null)   X-Ref
Call with boolean true to store table layout changes in the user_preferences table.
Note: user_preferences.value has a maximum length of 1333 characters.
Call with no parameter to get current state of table persistence.

param: bool $persistent Optional parameter to set table layout persistence.
return: bool Whether or not the table layout preferences will persist.

show_download_buttons_at($showat)   X-Ref
Where to show download buttons.

param: array $showat array of postions in which to show download buttons.

sortable($bool, $defaultcolumn = NULL, $defaultorder = SORT_ASC)   X-Ref
Sets the is_sortable variable to the given boolean, sort_default_column to
the given string, and the sort_default_order to the given integer.

param: bool $bool
param: string $defaultcolumn
param: int $defaultorder
return: void

text_sorting($column)   X-Ref
Use text sorting functions for this column (required for text columns with Oracle).
Be warned that you cannot use this with column aliases. You can only do this
with real columns. See MDL-40481 for an example.

param: string column name

no_sorting($column)   X-Ref
Do not sort using this column

param: string column name

is_sortable($column = null)   X-Ref
Is the column sortable?

param: string column name, null means table
return: bool

collapsible($bool)   X-Ref
Sets the is_collapsible variable to the given boolean.

param: bool $bool
return: void

pageable($bool)   X-Ref
Sets the use_pages variable to the given boolean.

param: bool $bool
return: void

initialbars($bool)   X-Ref
Sets the use_initials variable to the given boolean.

param: bool $bool
return: void

pagesize($perpage, $total)   X-Ref
Sets the pagesize variable to the given integer, the totalrows variable
to the given integer, and the use_pages variable to true.

param: int $perpage
param: int $total
return: void

set_control_variables($variables)   X-Ref
Assigns each given variable in the array to the corresponding index
in the request class variable.

param: array $variables
return: void

set_attribute($attribute, $value)   X-Ref
Gives the given $value to the $attribute index of $this->attributes.

param: string $attribute
param: mixed $value
return: void

column_suppress($column)   X-Ref
What this method does is set the column so that if the same data appears in
consecutive rows, then it is not repeated.

For example, in the quiz overview report, the fullname column is set to be suppressed, so
that when one student has made multiple attempts, their name is only printed in the row
for their first attempt.
param: int $column the index of a column.

column_class($column, $classname)   X-Ref
Sets the given $column index to the given $classname in $this->column_class.

param: int $column
param: string $classname
return: void

column_style($column, $property, $value)   X-Ref
Sets the given $column index and $property index to the given $value in $this->column_style.

param: int $column
param: string $property
param: mixed $value
return: void

set_columnsattributes(array $attributes)   X-Ref
Sets the given $attributes to $this->columnsattributes.
Column attributes will be added to every cell in the column.

param: array[] $attributes e.g. ['c0_firstname' => ['data-foo' => 'bar']]

column_style_all($property, $value)   X-Ref
Sets all columns' $propertys to the given $value in $this->column_style.

param: int $property
param: string $value
return: void

define_baseurl($url)   X-Ref
Sets $this->baseurl.

param: moodle_url|string $url the url with params needed to call up this page

define_columns($columns)   X-Ref

param: array $columns an array of identifying names for columns. If

define_headers($headers)   X-Ref

param: array $headers numerical keyed array of displayed string titles

define_header_column(string $column)   X-Ref
Mark a specific column as being a table header using the column name defined in define_columns.

Note: Only one column can be a header, and it will be rendered using a th tag.

param: string  $column

define_help_for_headers($helpicons)   X-Ref
Defines a help icon for the header

Always use this function if you need to create header with sorting and help icon.

param: renderable[] $helpicons An array of renderable objects to be used as help icons

mark_table_to_reset()   X-Ref
Mark the table preferences to be reset.


is_resetting_preferences()   X-Ref
Is the table marked for reset preferences?

return: bool True if the table is marked to reset, false otherwise.

setup()   X-Ref
Must be called after table is defined. Use methods above first. Cannot
use functions below till after calling this method.

return: type?

get_sort_for_table($uniqueid)   X-Ref
Get the order by clause from the session or user preferences, for the table with id $uniqueid.

param: string $uniqueid the identifier for a table.
return: SQL fragment that can be used in an ORDER BY clause.

construct_order_by($cols, $textsortcols=array()   X-Ref
Prepare an an order by clause from the list of columns to be sorted.

param: array $cols column name => SORT_ASC or SORT_DESC
return: SQL fragment that can be used in an ORDER BY clause.

get_sql_sort()   X-Ref

return: SQL fragment that can be used in an ORDER BY clause.

contains_fullname_columns()   X-Ref
Whether the current table contains any fullname columns

return: bool

get_sort_columns()   X-Ref
Get the columns to sort by, in the form required by {@link construct_order_by()}.

return: array column name => SORT_... constant.

get_page_start()   X-Ref

return: int the offset for LIMIT clause of SQL

get_page_size()   X-Ref

return: int the pagesize for LIMIT clause of SQL

get_sql_where()   X-Ref

return: string sql to add to where statement.

add_data_keyed($rowwithkeys, $classname = '')   X-Ref
Add a row of data to the table. This function takes an array or object with
column names as keys or property names.

It ignores any elements with keys that are not defined as columns. It
puts in empty strings into the row when there is no element in the passed
array corresponding to a column in the table. It puts the row elements in
the proper order (internally row table data is stored by in arrays with
a numerical index corresponding to the column number).

param: object|array $rowwithkeys array keys or object property names are column names,
param: string $classname CSS class name to add to this row's tr tag.

format_and_add_array_of_rows($rowstoadd, $finish = true)   X-Ref
Add a number of rows to the table at once. And optionally finish output after they have been added.

param: (object|array|null)[] $rowstoadd Array of rows to add to table, a null value in array adds a separator row. Or a
param: bool     $finish

add_separator()   X-Ref
Add a seperator line to table.


add_data($row, $classname = '')   X-Ref
This method actually directly echoes the row passed to it now or adds it
to the download. If this is the first row and start_output has not
already been called this method also calls start_output to open the table
or send headers for the downloaded.
Can be used as before. print_html now calls finish_html to close table.

param: array $row a numerically keyed row of data to add to the table.
param: string $classname CSS class name to add to this row's tr tag.
return: bool success.

finish_output($closeexportclassdoc = true)   X-Ref
You should call this to finish outputting the table data after adding
data to the table with add_data or add_data_keyed.


wrap_html_start()   X-Ref
Hook that can be overridden in child classes to wrap a table in a form
for example. Called only when there is data to display and not
downloading.


wrap_html_finish()   X-Ref
Hook that can be overridden in child classes to wrap a table in a form
for example. Called only when there is data to display and not
downloading.


format_row($row)   X-Ref
Call appropriate methods on this table class to perform any processing on values before displaying in table.
Takes raw data from the database and process it into human readable format, perhaps also adding html linking when
displaying table as html, adding a div wrap, etc.

See for example col_fullname below which will be called for a column whose name is 'fullname'.

param: array|object $row row of data from db used to make one row of the table.
return: array one row for the table, added using add_data_keyed method.

col_fullname($row)   X-Ref
Fullname is treated as a special columname in tablelib and should always
be treated the same as the fullname of a user.

param: object $row the data from the db containing all fields from the
return: string contents of cell in column 'fullname', for this row.

other_cols($column, $row)   X-Ref
You can override this method in a child class. See the description of
build_table which calls this method.


format_text($text, $format=FORMAT_MOODLE, $options=NULL, $courseid=NULL)   X-Ref
Used from col_* functions when text is to be displayed. Does the
right thing - either converts text to html or strips any html tags
depending on if we are downloading and what is the download type. Params
are the same as format_text function in weblib.php but some default
options are changed.


print_html()   X-Ref
This method is deprecated although the old api is still supported.


get_initial_first()   X-Ref
This function is not part of the public api.

return: string initial of first name we are currently filtering by

get_initial_last()   X-Ref
This function is not part of the public api.

return: string initial of last name we are currently filtering by

print_one_initials_bar($alpha, $current, $class, $title, $urlvar)   X-Ref
Helper function, used by {@link print_initials_bar()} to output one initial bar.

param: array $alpha of letters in the alphabet.
param: string $current the currently selected letter.
param: string $class class name to add to this initial bar.
param: string $title the name to put in front of this initial bar.
param: string $urlvar URL parameter name for this initial.

print_initials_bar()   X-Ref
This function is not part of the public api.


print_nothing_to_display()   X-Ref
This function is not part of the public api.


get_row_from_keyed($rowwithkeys)   X-Ref
This function is not part of the public api.


download_buttons()   X-Ref
Get the html for the download buttons

Usually only use internally

start_output()   X-Ref
This function is not part of the public api.
You don't normally need to call this. It is called automatically when
needed when you start adding data to the table.


print_row($row, $classname = '')   X-Ref
This function is not part of the public api.


get_row_html($row, $classname = '')   X-Ref
Generate html code for the passed row.

param: array $row Row data.
param: string $classname classes to add.
return: string $html html code for the row passed.

get_row_cells_html(string $rowid, array $row, ?array $suppresslastrow)   X-Ref
Generate html code for the row cells.

param: string $rowid
param: array $row
param: array|null $suppresslastrow
return: string

finish_html()   X-Ref
This function is not part of the public api.


show_hide_link($column, $index)   X-Ref
Generate the HTML for the collapse/uncollapse icon. This is a helper method
used by {@link print_headers()}.

param: string $column the column name, index into various names.
param: int $index numerical index of the column.
return: string HTML fragment.

print_headers()   X-Ref
This function is not part of the public api.


set_sorting_preferences()   X-Ref
Calculate the preferences for sort order based on user-supplied values and get params.


set_initials_preferences()   X-Ref
Fill in the preferences for the initials bar.


set_hide_show_preferences()   X-Ref
Set hide and show preferences.


set_hidden_columns(array $columns)   X-Ref
Set the list of hidden columns.

param: array $columns The list of hidden columns.

initialise_table_preferences()   X-Ref
Initialise table preferences.


save_preferences($oldprefs)   X-Ref
Save preferences.

param: array $oldprefs Old preferences to compare against.

set_sortdata(array $sortdata)   X-Ref
Set the preferred table sorting attributes.

param: string $sortby The field to sort by.
param: int $sortorder The sort order.

get_default_per_page()   X-Ref
Get the default per page.

return: int

set_default_per_page(int $defaultperpage)   X-Ref
Set the default per page.

param: int $defaultperpage

set_first_initial(string $initial)   X-Ref
Set the preferred first name initial in an initials bar.

param: string $initial The character to set

set_last_initial(string $initial)   X-Ref
Set the preferred last name initial in an initials bar.

param: string $initial The character to set

set_page_number(int $pagenumber)   X-Ref
Set the page number.

param: int $pagenumber The page number.

sort_icon($isprimary, $order)   X-Ref
Generate the HTML for the sort icon. This is a helper method used by {@link sort_link()}.

param: bool $isprimary whether an icon is needed (it is only needed for the primary sort column.)
param: int $order SORT_ASC or SORT_DESC
return: string HTML fragment.

sort_order_name($isprimary, $order)   X-Ref
Generate the correct tool tip for changing the sort order. This is a
helper method used by {@link sort_link()}.

param: bool $isprimary whether the is column is the current primary sort column.
param: int $order SORT_ASC or SORT_DESC
return: string the correct title.

sort_link($text, $column, $isprimary, $order)   X-Ref
Generate the HTML for the sort link. This is a helper method used by {@link print_headers()}.

param: string $text the text for the link.
param: string $column the column name, may be a fake column like 'firstname' or a real one.
param: bool $isprimary whether the is column is the current primary sort column.
param: int $order SORT_ASC or SORT_DESC
return: string HTML fragment.

get_primary_sort_order()   X-Ref
Return primary sorting column/order, either the first preferred "sortby" value or defaults defined for the table

return: array

get_sort_order()   X-Ref
Return sorting attributes values.

return: array

get_component()   X-Ref
Get dynamic class component.

return: string

get_handler()   X-Ref
Get dynamic class handler.

return: string

get_dynamic_table_html_start()   X-Ref
Get the dynamic table start wrapper.
If this is not a dynamic table, then an empty string is returned making this safe to blindly call.

return: string

get_dynamic_table_html_end()   X-Ref
Get the dynamic table end wrapper.
If this is not a dynamic table, then an empty string is returned making this safe to blindly call.

return: string

start_html()   X-Ref
This function is not part of the public api.


set_caption(string $caption, ?array $captionattributes)   X-Ref
This function set caption for table.

param: string $caption Caption of table.
param: array|null $captionattributes Caption attributes of table.

render_caption()   X-Ref
This function renders a table caption.

return: string $output Caption of table.

make_styles_string($styles)   X-Ref
This function is not part of the public api.

param: array $styles CSS-property => value
return: string values suitably to go in a style="" attribute in HTML.

render_reset_button()   X-Ref
Generate the HTML for the table preferences reset button.

return: string HTML fragment, empty string if no need to reset

can_be_reset()   X-Ref
Are there some table preferences that can be reset?

If true, then the "reset table preferences" widget should be displayed.

return: bool

get_context()   X-Ref
Get the context for the table.

Note: This function _must_ be overridden by dynamic tables to ensure that the context is correctly determined
from the filterset parameters.

return: context

set_filterset(filterset $filterset)   X-Ref
Set the filterset in the table class.

The use of filtersets is a requirement for dynamic tables, but can be used by other tables too if desired.

param: filterset $filterset The filterset object to get filters and table parameters from

get_filterset()   X-Ref
Get the currently defined filterset.

return: filterset

guess_base_url()   X-Ref
Attempt to guess the base URL.


Class: table_sql  - X-Ref


__construct($uniqueid)   X-Ref

param: string $uniqueid a string identifying this table.Used as a key in

build_table()   X-Ref
Take the data returned from the db_query and go through all the rows
processing each col using either col_{columnname} method or other_cols
method or if other_cols returns NULL then put the data straight into the
table.

After calling this function, don't forget to call close_recordset.

close_recordset()   X-Ref
Closes recordset (for use after building the table).


get_row_class($row)   X-Ref
Get any extra classes names to add to this row in the HTML.

param: $row array the data for this row.
return: string added to the class="" attribute of the tr.

set_count_sql($sql, array $params = NULL)   X-Ref
This is only needed if you want to use different sql to count rows.
Used for example when perhaps all db JOINS are not needed when counting
records. You don't need to call this function the count_sql
will be generated automatically.

We need to count rows returned by the db seperately to the query itself
as we need to know how many pages of data we have to display.

set_sql($fields, $from, $where, array $params = array()   X-Ref
Set the sql to query the db. Query will be :
SELECT $fields FROM $from WHERE $where
Of course you can use sub-queries, JOINS etc. by putting them in the
appropriate clause of the query.


query_db($pagesize, $useinitialsbar=true)   X-Ref
Query the db. Store results in the table object for use by build_table.

param: int $pagesize size of page for paginated displayed table.
param: bool $useinitialsbar do you want to use the initials bar. Bar

out($pagesize, $useinitialsbar, $downloadhelpbutton='')   X-Ref
Convenience method to call a number of methods for you to display the
table.


Class: table_default_export_format_parent  - X-Ref


__construct(&$table)   X-Ref
Constructor

param: flexible_table $table

table_default_export_format_parent(&$table)   X-Ref
Old syntax of class constructor. Deprecated in PHP7.


Class: name  - X-Ref

set_table(&$table)   X-Ref
No description

add_data($row)   X-Ref
No description

add_seperator()   X-Ref
No description

document_started()   X-Ref
No description

format_text($text, $format=FORMAT_MOODLE, $options=NULL, $courseid=NULL)   X-Ref
Given text in a variety of format codings, this function returns
the text as safe HTML or as plain text dependent on what is appropriate
for the download format. The default removes all tags.


format_data(array $row)   X-Ref
Format a row of data, removing HTML tags and entities from each of the cells

param: array $row
return: array

Class: table_dataformat_export_format  - X-Ref

Dataformat exporter

__construct(&$table, $dataformat)   X-Ref
Constructor

param: string $table An sql table
param: string $dataformat type of dataformat for export

supports_html()   X-Ref
Whether the current dataformat supports export of HTML

return: bool

start_document($filename, $sheettitle)   X-Ref
Start document

param: string $filename
param: string $sheettitle

start_table($sheettitle)   X-Ref
Start export

param: string $sheettitle optional spreadsheet worksheet title

output_headers($headers)   X-Ref
Output headers

param: array $headers

add_data($row)   X-Ref
Add a row of data

param: array $row One record of data

finish_table()   X-Ref
Finish export


finish_document()   X-Ref
Finish download