From 1345403a7c593c9423d3fb2cb3d9611926dc0ace Mon Sep 17 00:00:00 2001 From: defacer Date: Tue, 25 Jan 2005 02:57:30 +0000 Subject: [PATCH] Renaming 4 internal-use-only class methods by prefixing an underscore. I want to make a point that people should NOT be calling them. --- blocks/HOWTO.html | 291 +++++++++++++++++++++++++++-------- blocks/moodleblock.class.php | 14 +- lib/blocklib.php | 8 +- 3 files changed, 238 insertions(+), 75 deletions(-) diff --git a/blocks/HOWTO.html b/blocks/HOWTO.html index c45b09274a..b6aca316d6 100644 --- a/blocks/HOWTO.html +++ b/blocks/HOWTO.html @@ -6,7 +6,7 @@ background-color: #ffeece; font-family: Verdana, Arial, serif; font-size: 90%; - padding: 10px 20px; + padding: 10px 30px; } h2 { border: 1px black solid; @@ -20,13 +20,20 @@ pre { font-family: Lucida Console, courier; } + .footer { + border: 1px black solid; + background-color: #FFD991; + padding: 5px; + margin: 4em; + -moz-border-radius: 25px; + } .header { border: 1px black solid; background-color: #fff; padding: 10px; -moz-border-radius: 25px; } - .header h1 { + .header h1, .footer h1 { text-align: center; font-size: 2em; } @@ -73,6 +80,7 @@ } a.function_title, a.variable_title, a.named_constant { cursor: help; + border: none !important; } a, a:visited, a:active { text-decoration: none; @@ -86,6 +94,23 @@ border: 1px #999 dotted; background-color: #FFD991; } + ul#methods_reference, ul#variables_reference, ul#constants_reference { + list-style-type: decimal; + } + ul#methods_reference ul, ul#variables_reference, ul#constants_reference { + border-left: 10px rgb(245, 180, 90) solid; + list-style-type: none; + margin: 0px; + margin-bottom: 3em; + padding: 0px 20px; + } + ul#methods_reference h3 { + margin-top: 2em; + } + ul#methods_reference ul li .function_title, ul#variables_reference .variable_title, ul#constants_reference .named_constant { + margin: 2em 0px 1em 0px; + border-bottom: 2px #666 dotted; + } @@ -175,7 +200,7 @@ -

Configure That Out

@@ -329,7 +354,7 @@ function instance_allow_multiple() {

The Effects of Globalization

@@ -542,13 +567,13 @@ function get_content() {

Appendix A: Reference

This Appendix will discuss the base class block_base from which all other block classes derive, and present each and every method that can be overridden by block developers in detail. Methods that should NOT be overridden are explicitly referred to as such. After reading this Appendix, you will have a clear understanding of every method which you should or could override to implement functionality for your block.

This Appendix will discuss the base class block_base from which all other block classes derive, and present each and every method that can be overridden by block developers in detail. Methods that should not be overridden are explicitly referred to as such. After reading this Appendix, you will have a clear understanding of every method which you should or could override to implement functionality for your block.

The methods are divided into three categories: those you may use and override in your block, those that you may NOT override but might want to use, and those that should NEITHER be used NOR overridden. In each category, methods are presented in alphabetical order.

The methods are divided into three categories: those you may use and override in your block, those that you may not override but might want to use, and those internal methods that should neither be used nor overridden. In each category, methods are presented in alphabetical order.

Methods you can freely use and override: +
Methods you can freely use and override:
- @@ -586,11 +613,11 @@ function config_print() { return true; } -
  This method allows you to choose how to display the global configuration screen for your block. Override it if you need something much more complex than the default implementation allows you to do. However, keep these points in mind:
  +
  This method allows you to choose how to display the global configuration screen for your block. This is the screen that the administrator is presented with when he chooses "Settings..." for a specific block. Override it if you need something much more complex than the default implementation allows you to do. However, keep these points in mind:
  1. If you save your configuration options in $CFG, you will probably need to use global $CFG; before including any HTML configuration screens.
  2. Whatever you do output from config_print, it will be enclosed in a HTML form automatically. You only need to provide a way to submit that form.
  3. The HTML <input> elements that you include in your method's output will be automatically enclosed in a <form> element. You do not need to worry about where and how that form is submitted; however, you must provide a way to submit it (i.e., an <input type="submit" />.
  You should return a boolean value denoting the success or failure of your method's actions.
  @@ -613,7 +640,7 @@ function config_save($data) {
  This method allows you to override the storage mechanism for your global configuration data. The received argument is an associative array, with the keys being setting names and the values being setting values. The default implementation saves everything as Moodle $CFG variables.
  -
  Note that what you receive as an argument will NOT be all of the POST data; Moodle will automatically strip out some bits it added itself (such as "sesskey"), so it's quite safe to save everything you receive.
  +
  Note that $data does not hold all of the submitted POST data because Moodle adds some hidden fields to the form in order to be able to process it. However, before calling this method it strips the hidden fields from the received data and so when this method is called only the "real" configuration data remain.
  
  You should return a boolean value denoting the success or failure of your method's actions.
  @@ -631,13 +658,15 @@ function get_content() {
  This method should, when called, populate the $this->content variable of your block. Populating the variable means: -
  EITHER
  defining $this->content->text and $this->content->footer if your block is of type BLOCK_TYPE_TEXT. Both of these should be strings which can contain arbitrary HTML.
  +
  EITHER
  defining $this->content->text and $this->content->footer if your block is of type BLOCK_TYPE_TEXT. Both of these should be strings, and can contain arbitrary HTML.
  -
  OR
  defining $this->content->items, $this->content->icons and $this->content->footer if your block is of type BLOCK_TYPE_LIST. The first two should be numerically indexed arrays with the same number of elements. $this->content->items can contain arbitrary HTML while $this->content->icons should only contain fully-qualified HTML img tags. $this->content->footer is a string, as above.
  +
  OR
  defining $this->content->items, $this->content->icons and $this->content->footer if your block is of type BLOCK_TYPE_LIST. The first two should be numerically indexed arrays having the exact same number of elements. $this->content->items is an array of strings that can contain arbitrary HTML while $this->content->icons also contains should strings, but those must be fully-qualified HTML <img> tags and nothing else. $this->content->footer is a string, as above.
  -
  If you set ALL of these variables to their default "empty" values (empty arrays for the arrays and empty strings for the strings), the block will NOT be displayed at all except to editing users. This is a good way of having your block NOT displayed if there is no reason for it.
  +
  If you set all of these variables to their default "empty" values (empty arrays for the arrays and empty strings for the strings), the block will not be displayed at all except to editing users. This is a good way of having your block hide itself to unclutter the screen if there is no reason to have it displayed.
  -
  Your function should return the fully constructed $this->content variable. You should also include a check that, if this variable is not exactly equal to NULL, returns the existing value instead of calculating it once more. If you fail to do this, Moodle will suffer a performance hit.
  +
  Before starting to populate $this->content, you should also include a simple caching check. If $this->content is exactly equal to NULL then proceed as normally, while if it is not, return the existing value instead of calculating it once more. If you fail to do this, Moodle will suffer a performance hit.
  + +
  In any case, your method should return the fully constructed $this->content variable.
- @@ -664,7 +694,7 @@ function hide_header() { return false; } -
  This method should return a boolean value that denotes whether your block wants to hide its title part. Thus, if you override it to return true, your block will not display a title unless the current user is in editing mode.
  +
  This method should return a boolean value that denotes whether your block wants to hide its header (or title). Thus, if you override it to return true, your block will not display a title unless the current user is in editing mode.
-
Methods which you should NOT override but may want to use: +
Methods which you should not override but may want to use:
- get_content_type
  +
```
+function get_content_type() {
+    return $this->content_type;
+}
```
  + +
  This method returns the value of $this->content_type, and is the preferred way of accessing that variable. It is guaranteed to always work, now and forever. Directly accessing the variable is not recommended; future library changes may break compatibility with code that does so.
  +
- get_title
  +
```
+function get_title() {
+    return $this->title;
+}
```
  + +
  This method returns the value of $this->title, and is the preferred way of accessing that variable. It is guaranteed to always work, now and forever. Directly accessing the variable is not recommended; future library changes may break compatibility with code that does so.
  +
- get_version
  +
```
+function get_version() {
+    return $this->version;
+}
```
  + +
  This method returns the value of $this->version, and is the preferred way of accessing that variable. It is guaranteed to always work, now and forever. Directly accessing the variable is not recommended; future library changes may break compatibility with code that does so.
  +
- name
  +
```
+function name() {
+    static $myname;
+    if ($myname === NULL) {
+        $myname = strtolower(get_class($this));
+        $myname = substr($myname, strpos($myname, '_') + 1);
+    }
+    return $myname;
+}
```
  + +
  This method returns the internal name of your block inside Moodle, without the block_ prefix. Obtaining the name of a block object is sometimes useful because it can be used to write code that is agnostic to the actual block's name (and thus more generic and reusable). For an example of this technique, see the config_print method.
Methods which you should NOT override and NOT use at all: +
Methods which you should not override and not use at all:
- _self_test
  +
  This is a private method; no description is given.
- -
  add_edit_controls
  +
- +
  _add_edit_controls
  +
  This is a private method; no description is given.
- -
  load_instance
  +
- +
  _load_instance
  +
  This is a private method; no description is given.
- -
  print_block
  +
- +
  _print_block
  +
  This is a private method; no description is given.
- -
  print_shadow
  +
- +
  _print_shadow
  +
  This is a private method; no description is given.

The class block_base also has a few standard member variables which its methods manipulate. These variables and their uses are explained hereafter:

The class block_base also has a few standard member variables which its methods manipulate. These variables, the purpose of each and the type of data they are expected to hold is explained in the next section of this Appendix.

Class variables:

+ +
$this->config
+ +
This variable holds all the specialized instance configuration data that have been provided for this specific block instance (object). It is an object of type stdClass, with member variables directly corresponding to the HTML <input> elements in the block's config_instance.html file.
+ +
The variable is initialized just after the block object is constructed, immediately before specialization is called for the object. It is possible that the block has no instance configuration, in which case the variable will be NULL.
+ +
It is obvious that there is a direct relationship between this variable and the configdata field in the mdl_block_instance table. However, it is strongly advised that you refrain from acessing the configdata field yourself. If you absolutely must update its value at any time, it is recommended that you call the method instance_config_save to do the actual work.
-
- -
  $this->title
  -
  This variable should be a string that contains the human-readable name of the block. It is used to refer to blocks of that type everywhere, for example in the administrator's block configuration screen. The variable is expected to have a valid value after the framework calls the init method for each block.
  -
  In the case of blocks which may want to configure their title dynamically through instance configuration, it is still essential to provide a valid title inside init. This title may then be overridden when the specialization method is called by the framework.
- +
  $this->content_type
  -
  This variable instructs Moodle on what type of content it should assume the block provides. It is essential that it has a meaningful value, as Moodle depends on this for correctly displaying the block on screen. Consequently, this variable is closely tied with the varaible $this->content. The variable is expected to have a valid value after the framework calls the init method for each block.
  + +
  This variable instructs Moodle on what type of content it should assume the block has. It is essential that it has a meaningful value, as Moodle depends on this for correctly displaying the block on screen. Consequently, this variable is closely tied with the varaible $this->content. The variable is expected to have a valid value after the framework calls the init method for each block.
  +
  The only valid values for this variable are the two named constants BLOCK_TYPE_TEXT and BLOCK_TYPE_LIST.
- +
  $this->content
  -
  !!!UNFINISHED!!! This variable instructs Moodle on what type of content it should assume the block provides. It is essential that it has a meaningful value, as Moodle depends on this for correctly displaying the block on screen. Consequently, this variable is closely tied with the varaible $this->content. The variable is expected to have a valid value after the framework calls the init method for each block.
  -
  The only valid values for this variable are the two named constants BLOCK_TYPE_TEXT and BLOCK_TYPE_LIST.
  + +
  This variable holds all the actual content that is displayed inside each block. Valid values for it are either NULL or an object of class stdClass, which must have specific member variables set as explained below. Normally, it begins life with a value of NULL and it becomes fully constructed (i.e., an object) when the get_content is called.
  + +
  After it is fully constructed, this object is expected to have certain properties, depending on the value of $this->content_type. Specifically: + +
  - + If $this->content_type is BLOCK_TYPE_TEXT, then $this->content is expected to have the following member variables: + +
    - text
      This is a string of arbitrary length and content. It is displayed inside the main area of the block, and can contain HTML.
    - footer
      This is a string of arbitrary length and contents. It is displayed below the text, using a smaller font size. It can also contain HTML.
    +
  - If $this->content_type is BLOCK_TYPE_LIST, then $this->content is expected to have the following member variables: +
    - items
      This is a numerically indexed array of strings which holds the title for each item in the list that will be displayed in the block's area. Since usually such lists function like menus, the title for each item is normally a fully qualified HTML <a> tag.
    - icons
      This is a numerically indexed array of strings which represent the images displayed before each item of the list. It therefore follows that it should have the exact number of elements as the items member variable. Each item in this array should be a fully qualified HTML <img> tag.
    - footer
      This is a string of arbitrary length and contents. It is displayed below the text, using a smaller font size. It can also contain HTML.
    +
  +
  + +
- + +
  $this->instance
  + +
  This member variable holds all the specific information that differentiates one block instance (i.e., the PHP object that embodies it) from another. It is an object of type stdClass retrieved by calling get_record on the table mdl_block_instance. Its member variables, then, directly correspond to the fields of that table. It is initialized immediately after the block object itself is constructed.
  + +
- + +
  $this->title
  + +
  This variable is a string that contains the human-readable name of the block. It is used to refer to blocks of that type throughout Moodle, for example in the administrator's block configuration screen and in the editing teacher's add block menu. It is also the title that is printed when the block is displayed on screen, although blocks can specifically change this title to something else if they wish (see below). The variable is expected to have a valid value after the framework calls the init method for each object.
  + +
  In the case of blocks which may want to configure their title dynamically through instance configuration, it is still essential to provide a valid title inside init. This title may then be overridden when the specialization method is called by the framework:
  + +
```
+function specialization() {
+    // At this point, $this->instance and $this->config are available
+    // for use. We can now change the title to whatever we want.
+    $this->title = $this->config->variable_holding_the_title;
+}
```
  +
- +
  $this->version
  -
  This variable should hold each block's version number in the form YYYYMMDDXX, as per the convention throughout Moodle. The version number is used by Moodle to detect when a block has been upgraded and it consequently needs to run the block's upgrade code to bring the "old" version of the block's data up to date. The variable is expected to have a valid value after the framework calls the init method for each block.
  -
  Most blocks do not keep complex data of their own in the database the way that modules do, so in most cases nothing actually happens during a block version upgrade. However, the version number is displayed in the administration interface for blocks. It is good practice therefore to change your block's version number when it gains new functionality or receives important bug fixes, to enable site administrators to easily see if they have the latest version or they need to upgrade.
  -
- -
  $this->config
  -
  UNFINISHED!!!
  + +
  This variable should hold each block's version number in the form YYYYMMDDXX, as per the convention throughout Moodle. The version number is used by Moodle to detect when a block has been upgraded and it consequently needs to run the block's upgrade code to bring the "old" version of the block's data up to date. The variable is expected to have a valid value after the framework calls the init method for each block.
  + +
  Most blocks do not keep complex data of their own in the database the way that modules do, so in most cases nothing actually happens during a block version upgrade. However, the version number is displayed in the administration interface for blocks. It is good practice therefore to change your block's version number when it gains new functionality or receives important bug fixes, to enable site administrators to easily identify the exact version of the block they are working with.
  +
Appearing throughout the code related to the Blocks API, there is a number of predefined constants that are utilized to avoid the use of "magic numbers" in the code. These constants are:
-

Configure That Out

The Effects of Globalization

Appendix A: Reference

Methods you can freely use and override:

Methods which you should not override but may want to use:

Methods which you should not override and not use at all:

Class variables:

Named constants:

Class naming conventions changed

The End