MoodleDocs - User contributions [en]

blocks/moodletxt/status

2012-11-01T10:32:30Z

Tanthalas: Initial commit of the documentation for the message status page.

== Message Status Page ==

The message status page gives full details on the recipients of a given message, along with the status of the text messages sent. When the page loads, the details of the message sent will appear at the top left. This includes the Moodle user from which the message was sent, the time at which it was sent, the time it was scheduled to be sent at, and the actual text of the message. Below this, the recipients of the message are listed.

For each recipient, the following information is shown:

; Recipient : This field shows the name of the recipient, whether they are a Moodle user or a contact in your address book.

; Destination Number : The phone number to which the text message was sent.

; Time of Update : The time and date at which this message's status information was last updated by the ConnectTxt system.

; Message Status : The current status of this text message. There are three icons that are used to denote the status of a message. A red icon with a cross through it means that the message has failed. The recipient will not receive the message, and it should be checked and re-sent to this recipient. A green icon with no cross or tick means that the message has been sent, and no further information has yet been received. A green icon with a tick means that the message was received by the recipient.

The listing table can be edited and re-ordered like any other Moodle data table. Once you are happy with the data currently onscreen, you can also export it to a spreadsheet or similar file using the download options at the bottom of the table. Simply select the type of export you would like from the provided drop-down list, and then click the download button.

=== Updating Message Statuses ===

If your MoodleTxt installation has been configured correctly, it will automatically update message statuses in the background, without your intervention. However, if you wish to check for updated information, simply click the "Update" button, above the status listing on the left of the page. The page will refresh (this may take a moment while the ConnectTxt system is contacted), and the most up-to-date information will be displayed.

[[Category:MoodleTxt|Status Messages]]

admin/setting/moodletxtfilters

2012-11-01T10:31:09Z

Tanthalas: Documentation for MoodleTxt's filter management page.

== Managing Inbound Filters in MoodleTxt ==

This page allows you to edit MoodleTxt's inbound message filters. These filters are used when incoming messages are received from the ConnectTxt system, to forward them to the appropriate Moodle user's inbox. This form uses a step-by-step process to edit the filters in place, and add new ones. Fields within the form that are not ready for use, or depend on user input, will be locked until they are ready, so don't worry if you can't immediately access some parts of the form.

=== Selecting a ConnectTxt Account ===

Firstly, select the ConnectTxt account within the system you wish to apply filters on from the first drop-down box in the form. You will see a loading icon appear for a short period whilst MoodleTxt loads the existing filter structure for that account.

'''Note:''' In terms of filtering, ConnectTxt accounts are independent of one another. It is quite possible to have the same keyword filter on several different accounts, routing messages to different users. Similarly, it is possible to set up one keyword across all accounts that is always filtered to the same user.

=== Selecting or Creating a Filter ===

Once the loading icon has disappeared, the two lists of existing filters will be populated and unlocked. You now have two options.

# '''To edit an existing filter''' on the system, select it from either the keyword or phone number filter list. You will see another loading message while the details of that particular filter are pulled out of the database. When this disappears, you should be able to see the filter's current recipients in the large select box underneath.
# '''To create a new filter''', click the green "add" icon to the right of either the keyword or phone number filter lists, depending on which you wish to create. The filter list will be replaced with a text box. In this box you enter the operand for your new filter – that is the keyword or phone number on which you wish to filter messages. Once you have done this, the large recipient list underneath should be unlocked.

You have now specified the filter you wish to edit. Below the two filter options on the page is a larger select box. This box holds a list of all the recipients specified for a particular filter. For a new filter, this will be blank, and for an existing filter, it will show the list of previously selected recipients for that filter.

=== Adding and Removing Filter Recipients ===

To add a new recipient to a filter, locate the textbox labelled "Add users to filter". This is an auto-completing search box. As you type in it, it searches the Moodle database for the user you are looking for and displays possible selections onscreen. You can search by either first name, last name or username. For example, typing "Pre" into our MoodleTxt test server would display "Preece, Greg J (admin)".

Once the user you are looking for is displayed, select them by either highlighting them with the arrow keys and hitting return, or by clicking on them with the mouse. You should see the user being added to the recipient list.

To remove a recipient from a filter, select them from the recipients list and click the "Remove selected users from filter" button below it. They will be immediately removed from the recipients list. You can remove multiple users at the same time by either holding CTRL to select multiple individual entries, or holding SHIFT to select a consecutive group.

Once the filter has been edited/created to your satisfaction, and the recipients list appears correct, click the "Save the filter" button at the bottom of the form, and it will be saved back to the database. If you have removed all recipients from an existing filter, then that filter will also be deleted once the recipients have been removed.

[[Category:MoodleTxt|Settings Filters]]

admin/setting/moodletxtaccountsnew

2012-11-01T10:28:29Z

Tanthalas: Initial commit of documentation for MoodleTxt's "add account" page.

== Adding a New ConnectTxt Account to MoodleTxt ==

This page allows you to register a new ConnectTxt account with the MoodleTxt block. It should be one of your first stops after installing the block, and you will be redirected to it if you attempt to access other account-related pages when no accounts have been added to MoodleTxt.

If no accounts have been added to MoodleTxt when you go to this page, then some introductory text will be displayed explaining the purpose of the block and providing useful contact information. Beneath this, you will find the form for entering a new ConnectTxt account. Enter the username and password of the ConnectTxt account you wish to add to MoodleTxt. You may also enter a short description of the account if you wish.

With this done, please select a user to use as the default inbox for incoming messages on this account. The user with the default inbox is the one that will receive any inbound text messages that do not match any user filters within the MoodleTxt installation. This is to prevent unfiltered messages being lost. It is required that you select a default inbox owner even if you do not intend to use MoodleTxt for inbound messaging. Only users with the [[Moodletxt_capabilities|"block/moodletxt:defaultinbox" capability]] can own default inboxes.

Once you are done, click “Add Account.” The page will refresh. As it does so, the account details entered will be validated with the ConnectTxt system. This ensures that all the ConnectTxt accounts you save in MoodleTxt exist on the ConnectTxt system, that the passwords are correct, and that the accounts have been enabled for use with MoodleTxt. If no errors are found, you will be taken to the [[admin/setting/moodletxtaccounts|MoodleTxt account listing page]].

[[Category:MoodleTxt|Settings Account New]]

File:moodletxt-accounts-updater.png

2012-11-01T10:26:53Z

Tanthalas: Screenshot of an account update in progress on the MoodleTxt account listing page.

Screenshot of an account update in progress on the MoodleTxt account listing page.

File:moodletxt-access-toggles.png

2012-11-01T10:26:04Z

Tanthalas: Screenshot of the account access toggles within MoodleTxt's account listing page.

Screenshot of the account access toggles within MoodleTxt's account listing page.

File:moodletxt-account-access-form.png

2012-11-01T10:25:15Z

Tanthalas: Screenshot of the account restriction form in use within the MoodleTxt control panel

Screenshot of the account restriction form in use within the MoodleTxt control panel

File:moodletxt-account-access-button.png

2012-11-01T10:24:20Z

Tanthalas: Shot of the button to click if you want to edit outbound access on a ConnectTxt account in MoodleTxt.

Shot of the button to click if you want to edit outbound access on a ConnectTxt account in MoodleTxt.

File:moodletxt-account-edit-button.png

2012-11-01T10:22:58Z

Tanthalas: uploaded a new version of "File:moodletxt-account-edit-button.png": Reverted to version as of 10:21, 1 November 2012

Shot of the button to click if you want to edit outbound access on a ConnectTxt account in MoodleTxt.

File:moodletxt-account-edit-button.png

2012-11-01T10:22:35Z

Tanthalas: uploaded a new version of "File:moodletxt-account-edit-button.png": Shot of the button to click if you want to edit outbound access on a ConnectTxt account in MoodleTxt.

Shot of the button to click if you want to edit outbound access on a ConnectTxt account in MoodleTxt.

File:moodletxt-account-edit-button.png

2012-11-01T10:21:54Z

Tanthalas: Shot of the button to click if you want to edit outbound access on a ConnectTxt account in MoodleTxt.

Shot of the button to click if you want to edit outbound access on a ConnectTxt account in MoodleTxt.

admin/setting/moodletxtaccounts

2012-11-01T10:20:52Z

Tanthalas: Completing initial documentation for the account listing page in MoodleTxt 3.0

== Moodletxt: ConnectTxt Account Listings ==

On this page, you can get an overview of all the ConnectTxt SMS messaging accounts that have been registered within MoodleTxt. When you first load the page, you will be shown a list of all currently saved ConnectTxt accounts, along with their basic details. You can use this page to edit an account's details, along with which users can access each account.

=== Adding a New Account ===

[[admin/setting/moodletxtaccountsnew|Adding new accounts]] is handled on a separate page. To add a new ConnectTxt account to the MoodleTxt system, click the "Add New Account" link in the paragraph at the top of the page. If you attempt to view the account listings page, and no ConnectTxt accounts have been added to MoodleTxt, you will be automatically redirected to this link (this only occurs at first installation).

=== Account Listing ===

The onscreen table shows all ConnectTxt accounts currently stored within the MoodleTxt block. At first glance, the following fields are displayed:

; Username : The username of the ConnectTxt account.
; Description : The description you gave the ConnectTxt account when adding it to MoodleTxt.
; Messages Sent : The total number of messages sent through this account.
; Allow Outbound : Whether outbound access (message sending) is enabled on this account. If outbound messaging is enabled, you will see an icon showing 4 outbound arrows. If outbound messaging is disabled, you will see a red cross.
; Allow Inbound : Whether inbound access (receiving messages) is enabled on this account. If inbound messaging is enabled, you will see an icon showing 4 inbound arrows. If inbound messaging is disabled, you will see a red cross.
; Credits Used : The number of credits that have been used on your ConnectTxt account. This includes all messages sent, not just those sent via MoodleTxt. This figure is updated via [[Moodletxt_cron|cron]], or manually [[#updateInfo|via the controls on this page]].
; Credits Remaining : The number of remaining credits on your ConnectTxt account. If your account is invoiced, this will show as an ∞ infinity symbol.
; Account Type : What type of account billing this ConnectTxt account has enabled. This is typically either invoiced or pre-paid.
; Last Update : The time at which this account's online details (credits used/remaining, account type) were last updated from the ConnectTxt system.

=== Changing an Account's Password or Description ===

On the far left of an account's listing, before its username, you will find the edit button.
[[Image:moodletxt-account-edit-button.png|border|none]]
Clicking this button will open a modal dialog box containing the account's description, and a field allowing you to enter a new password. Edit the description as you see fit.

'''The password field is optional, and should only be filled in if you need to change the password on the account.'''

Once the fields in the dialog box are complete, click the "Save" button. The system will contact ConnectTxt to validate the details entered, and to fetch the latest credit data for the account. If the account is successfully validated, the dialog box will close and you will be returned to the main account listing.

=== Changing Which Users can Send Messages Via an Account ===

[[Image:moodletxt-account-access-button.png|border|none]]
MoodleTxt allows you to restrict outbound access to ConnectTxt accounts to a given list of Moodle users. If you would like to restrict access to an account, click on the "edit access" icon at the front of the account's "Allow Outbound" field. A modal dialog box will open containing a form that will allow you to restrict user access.

[[Image:moodletxt-account-access-form.png|frame|center|Access restriction form]]
The list labelled "Allowed Users" is the list of Moodle users that this account will be restricted to. If this list is blank, then the account will be unrestricted. To add users to the list, begin typing their name or username in the search box at the top of the form. This is an auto-completion search box, and will automatically perform a background search for the entered name (or partial name) when you stop typing.

When the user you wish to add appears in the auto-complete list, select them using the mouse or arrow and enter keys. They will be added to the list of users allowed to access the account. To remove one or more users from the list, click on their username(s) and then click the "Remove User(s)" button below the list. Removing all users from the list will make the account unrestricted.

Once you are happy with the restrictions applied to (or removed from) the account, click the "Save" button. The account's restrictions will be updated in the database, and you will be taken back to the account listing.

=== Disabling/Enabling Inbound and Outbound Access on an Account ===

You can completely turn off inbound or outbound access for any given ConnectTxt account. This is a simple matter of toggling the switches displayed under the "Allow Outbound" and "Allow Inbound" fields for an account. If your chosen route is enabled, you will see an icon featuring 4 green arrows. If it is disabled, you will see a red cross. Clicking on an enabled route will turn it off, and vice versa. For example, in this screenshot, the account has outbound messaging enabled, but is disabled for inbound messaging:

[[Image:moodletxt-access-toggles.png|border|center]]

=== <span id="updateInfo">Updating Account Information</span> ===

If you have [[Moodletxt_cron|cron-based updates]] enabled, then credit information for all your ConnectTxt accounts will be updated at regular intervals. If not, you can manually fetch updates from the account listing page, simply by clicking the "Update Credit Info" button at the top of the page. When you click this button, a progress bar will appear, and the system will run through each account in turn, updating the information on the page as it goes. Any information that has been updated will be displayed in bold. When the progress bar reaches 100% and all accounts have been processed, it will hide itself again, and the update button will be re-enabled.

[[Image:moodletxt-accounts-updater.png|border|center]]

[[Category:MoodleTxt|Settings Account Listing]]

admin/setting/blocksettingmoodletxt

2012-11-01T10:18:57Z

Tanthalas: Removing unnecessary link

== MoodleTxt Settings ==

This page contains all the common configuration options for MoodleTxt. At the top of the page you will see two links:

; ConnectTxt Accounts : This link will take you to the ConnectTxt account admin pages, which will allow you to add, update and restrict these accounts. If you have just installed MoodleTxt, this should be your first stop.
; Inbound Message Filters : This link will take you to the inbound filter management page, which will allow you to create filters for inbound SMS messages, routing them to particular Moodle users.

=== Send/Receive Settings ===

The first 4 settings in this section relate to how MoodleTxt gets both message status updates and new inbound messages from the ConnectTxt system. By default, MoodleTxt pulls these updates on a per-request basis, whenever users visit certain pages. However, it can be configured to get these updates automatically, which improves the performance of the block and results in far fewer outbound connections. The available automatic update methods are [[Moodletxt_cron | cron]] and [[Moodletxt_push | push]]. We '''highly''' recommend taking the time to set up push functionality, as it is the fastest and most efficient method of obtaining updates.

{| class="nicetable"
|-
! Field Name
! Field Label
! Description
|-
| Get_Status_On_View
| Automatically get status updates on "View Message" page
| If this box is checked, then whenever a user views the current status of a sent message, the block will first connect to the ConnectTxt system in order to fetch updates. You should uncheck this if you have configured an automatic update option as mentioned above.
|-
| Get_Inbound_On_View
| Automatically get inbound messages on Inbox page
| If this box is checked, then whenever a user views their inbox, the block will first connect to the ConnectTxt system in order to fetch new messages. You should uncheck this if you have configured an automatic update option as mentioned above.
|-
| Push_Username
| XML Push Username
| If you have set up XML push updates (highly recommended) then this is the username you provided to ConnectTxt as part of that setup. ConnectTxt uses this username to authenticate itself with your MoodleTxt installation when connecting to it.
|-
| Push_Password
| XML Push Password
| If you have set up XML push updates (highly recommended) then this is the password you provided to ConnectTxt as part of that setup. ConnectTxt uses this password to authenticate itself with your MoodleTxt installation when connecting to it.
|}

The last two settings in this category control other parameters related to message sending via ConnectTxt.

{| class="nicetable"
|-
! Field Name
! Field Label
! Description
|-
| Protocol_Warnings_On
| Display SSL security warnings
| If you do not have SSL connections to the ConnectTxt server enabled, MoodleTxt will generally display warnings that your data is being transmitted in an unsecure manner. To disable these warnings, uncheck this box.
|-
| Event_Messaging_Account
| Event Messaging Account
| This is the ConnectTxt account that MoodleTxt will use when it is asked to send automatic messages out in response to system events. By extension, this is the ConnectTxt account that will be used to send any messages originating via the MoodleTxt Plus message processor plugin. If no account is selected, then MoodleTxt will be unable to send event-generated messages.
|}

=== Recipient Settings ===

The settings in this section relate to how MoodleTxt captures user phone/name information from the Moodle system, and how it processes that information in order to send SMS messages out. (Future versions of the block will feature improvements in international phone number handling.)

{| class="nicetable"
|-
! Field Name
! Field Label
! Description
|-
| National_Prefix
| National Prefix
| This is the default dialling prefix for phone numbers within your country. It is the digit or set of digits that all phone numbers begin with when being dialled within the country. This defaults to 0, the UK domestic dialling prefix. ('''Note:''' If the phone numbers you enter into MoodleTxt are already formatted internationally, e.g. +441234567890, then this setting is ignored.)
|-
| Default_International_Prefix
| Default International Prefix
| This is the international dialling prefix for phone numbers within your country. This usually consists of a plus '+' sign, along with two or three digits, and is used when dialling into your country from another location. This defaults to +44, the UK international dialling prefix. ('''Note:''' If the phone numbers you enter into MoodleTxt are already formatted internationally, e.g. +441234567890, then this setting is ignored.)
|-
| Phone_Number_Source
| Take phone numbers from
| This option allows you to choose the field in your user database table that MoodleTxt will search for mobile phone numbers (phone1 or phone2). This is largely redundant in modern Moodle setups, where phone2 has been standardised as the mobile phone field, and exists for long-running installations where things may be different. If mobile phone numbers are populated to the phone1 field in your system, then select it from this drop-down.
|-
| Default_Recipient_Name
| Default Recipient Name
| When Moodle cannot find a recipient's name in the database, or cannot match an incoming phone number to any known contact, this is the name/identifier it will record against that message.
|}

=== Proxy Settings ===

If connections between your MoodleTxt installation and ConnectTxt need to be routed via a proxy server, then you can enter the details of that proxy server in this section. '''Please note:''' MoodleTxt currently only supports proxy servers that use either BASIC authentication, or no authentication at all. Newer versions of Moodle have their own proxy settings within the system, and future versions of the block will migrate to use those settings for proxy support.

{| class="nicetable"
|-
! Field Name
! Field Label
! Description
|-
| Proxy_Host
| Proxy Address
| The host/IP address of your proxy server.
|-
| Proxy_Port
| Proxy Port
| The TCP/IP port your proxy server listens on for connections.
|-
| Proxy_Username
| Proxy Username
| If your proxy server requires a username for authentication, then enter it here (BASIC authentication only).
|-
| Proxy_Password
| Proxy Password
| If your proxy server requires a password for authentication, then enter it here (BASIC authentication only).
|}

=== Miscellaneous Settings ===

This section contains any other global settings for MoodleTxt that do not fall into one of the earlier categories.

{| class="nicetable"
|-
! Field Name
! Field Label
! Description
|-
| jQuery_Include_Enabled
| Include main jQuery package
| MoodleTxt uses the popular jQuery library within its user interface. Some Moodle installations already include this library within their active themes. If this is the case, then attempting to load both libraries can cause problems with the system. To turn off MoodleTxt's jQuery installation and have it use the one provided with your theme, uncheck this box. ('''Note:''' You will require at least jQuery 1.6 for this to work.)
|-
| jQuery_UI_Include_Enabled
| Include jQuery UI Library
| MoodleTxt uses the jQuery User Interface library for many common widgets/user interface components. Some Moodle installations already include this library within their active themes. If this is the case, then attempting to load both libraries can cause problems with the system. To turn off MoodleTxt's jQuery UI installation and have it use the one provided with your theme, uncheck this box. ('''Note:''' You will require at least jQuery UI 1.7 for this to work.)
|-
| Show_Inbound_Numbers
| Show source names/numbers in inbox (Default)
| In a classroom situation, such as a survey, where many people can see the messages that are coming into the system, you may wish to anonymise them by hiding the source of the messages. In current versions of MoodleTxt, inbound messages are anonymised by default. To show those message sources on inbox pages by default, then check this box. Since MoodleTxt 3.0, users can override these settings for their own inboxes, so this setting is now a default.
|-
| RSS_Update_Interval
| RSS Update Interval
| This setting controls how often MoodleTxt should check with the RSS feed on the ConnectTxt servers for new updates. (This is being retired, as Moodle 2.3 and up can find updates automatically.)
|-
| RSS_Expiry_Length
| RSS items expire after
| This setting controls how long an update notification from ConnectTxt should be displayed on the MoodleTxt admin panel. (This is being retired, as Moodle 2.3 and up can find updates automatically.)
|}

[[Category:MoodleTxt|Settings]]

admin/setting/blocksettingmoodletxt

2012-11-01T10:18:29Z

Tanthalas: Documentation for the main admin settings page in MoodleTxt

File:moodletxt-sent-user-list.png

2012-11-01T10:14:25Z

Tanthalas: Screenshot of the user selection list on the MoodleTxt sent message page.

Screenshot of the user selection list on the MoodleTxt sent message page.

File:moodletxt-sent-type-list.png

2012-11-01T10:05:58Z

Tanthalas: MoodleTxt screenshot showing the message type selector on the sent messages screen.

MoodleTxt screenshot showing the message type selector on the sent messages screen.

blocks/moodletxt/sent

2012-11-01T10:04:50Z

Tanthalas: Initial commit of the documentation for the sent message listing page.

== Sent Message Listing ==

This page lists all the messages sent out by the existing Moodle user, as well as (if you have the right permissions enabled) all messages sent out by other Moodle users. Some general statistics regarding messages sent are shown at the top left of the page. The sent message listing contains the following columns:

; User Account : The name of the Moodle user that sent this message out. Clicking on the linked username within this column will take you to that user's Moodle profile page.

; ConnectTxt Account : The ConnectTxt account through which this message was sent.

; Message Text : A shortened summary of the message sent. Clicking on this text summary will take you to [[blocks/moodletxt/status|a page detailing its current status]].

; Time Sent : The time at which this message was sent from the system, adjusted to your timezone.

; Created by : Whether the message was written by the user or [[#event_gen|generated by a system event]]. (Only displayed when you have selected to view event-generated messages alongside your own created messages.)

The listing table can be edited and re-ordered like any other Moodle data table. Once you are happy with the data currently onscreen, you can also export it to a spreadsheet or similar file using the download options at the bottom of the table. Simply select the type of export you would like from the provided drop-down list, and then click the download button.

=== <span id="event_gen">Viewing Event-Generated Messages</span> ===

As of MoodleTxt 3, messages can be generated by system events (such as those arriving via MoodleTxt Plus), as well as by the user. These messages are recorded like any other message, but are hidden on the sent message listing by default. If you wish to view any event-generated messages that have been sent out automatically from your account to another user, then you can enable them using the drop-down box at the top left of the screen.

[[Image:moodletxt-sent-type-list.png|frame|center|Allows you to show or hide event-generated messages.]]

The options in this drop-down box are pretty self-explanatory. You can opt to either hide all event-generated messages (the default option), show the event-generated messages inline with your other sent messages, or show the event-generated messages on their own. If you decide to show event-generated messages alongside your own user-created messages, then an additional column is displayed showing whether the message was written by the user or generated by an event.

=== Viewing Other User's Messages ===

If you have the correct [[Moodletxt_capabilities|user capabilities]] assigned, you can view messages sent out by other users within the system. An additional drop-down box will be displayed at the top left of the page:

[[Image:moodletxt-sent-user-list.png|border|center]]

Select the user you wish to view, and the page will reload with that user's messages listed. Alternatively, you can select "All Users" to view every message sent out via your MoodleTxt installation.

[[Category:MoodleTxt|Sent]]

File:moodletxt-compose-counters.png

2012-11-01T09:55:08Z

Tanthalas: Screenshot of the message character counters on the MoodleTxt compose page.

Screenshot of the message character counters on the MoodleTxt compose page.

File:moodletxt-compose-recipient-selectors.png

2012-11-01T09:53:21Z

Tanthalas: Recipient selector buttons on the MoodleTxt compose page.

Recipient selector buttons on the MoodleTxt compose page.

File:moodletxt-compose-recipient-lists.png

2012-11-01T09:51:30Z

Tanthalas: Screenshot of the "potential" and "selected" recipient lists on the MoodleTxt compose page.

Screenshot of the "potential" and "selected" recipient lists on the MoodleTxt compose page.

File:moodletxt-compose-nav.png

2012-11-01T09:36:12Z

Tanthalas: A screenshot of the navigation tabs in MoodleTxt's compose page.

A screenshot of the navigation tabs in MoodleTxt's compose page.

blocks/moodletxt/send

2012-10-31T23:49:07Z

Tanthalas: Documentation for the compose page in

== Sending a Message via MoodleTxt ==

This page will run you through the process of sending out a message from the MoodleTxt compose page. Given the wide number of options that MoodleTxt provides for outbound messaging, this page is designed as a wizard, to easily section off the various stages of composing a new message. You can move forwards and backwards through the steps of the wizard by clicking on their titles at the top of the form.

[[Image:moodletxt-compose-nav.png|frame|center|The compose wizard is organised into 4 steps. Click on a step to zoom to it]]

=== Step 1: Recipients ===

Firstly, you must select the recipients for the message. You may send a text message to one or more individuals, to a pre-defined group of users/contacts, to additional recipients you specify on the page, or any combination of the three.

On the left of the screen you will see the "Potential Recipients" list. This list holds all the recipients (of a given type) that were found in your Moodle system. These are the recipients that you can add to the message. On the right of the screen you will see the "Selected Recipients" list. Any recipient that is in this list when the form is submitted will receive the message.

[[Image:moodletxt-compose-recipient-lists.png|frame|center|The "potential" and "selected" recipient lists for MoodleTxt. Clicking the >> and << buttons will add or remove selected recipients to/from the message.]]

To add a recipient to the message, find them in the list on the left, select them, and click the button with the right-facing arrows (>>). The recipient will move across to the selected list. To remove them from the message, click the button with the left-facing arrows (<<). The recipient will be removed from the selected list, and reappear in the potential list on the left; they will no longer receive a copy of the message.

You will notice that the recipients you are selecting are colour-coded. These colours designate the type of recipient that you are selecting. Underneath the two lists you will notice a number of coloured buttons: "Users", "User Groups", "Addressbook Contacts", "Addressbook Groups". Users are the user accounts and user groups defined in your Moodle installation. Address Books contain the contacts and groups you define within MoodleTxt. Click on one of these buttons to display the appropriate contact list.

[[Image:moodletxt-compose-recipient-selectors.png|frame|center|Clicking on one of these colour-coded buttons displays the appropriate contacts in the "Potential Recipients" list]]

(To select more than one contact from a list, hold down CTRL on Windows/Linux, or the Apple/cloverleaf key on a Mac, and click on each contact. You can also select a group of sequential contacts by clicking on the first contact, then holding the SHIFT key and selecting a contact further up/down the list. This will select every contact in a range.)

Finally, if you wish to add recipients to the message that are not already stored within Moodle or MoodleTxt, you can use the "Add Additional Contact" form, which you will find underneath the recipient lists at the bottom of the slide. Enter the contact's first name, last name and phone number in the appropriate boxes, and click the “Add Contact” button. The new contact will be added to the “Selected Recipients” list on the right of the page.

Any contacts you added from the “Additional Recipients” form will be destroyed when removed from the "Selected Recipients" list.

Once you are satisfied with your recipient selections, click on "Step 2" in the navigation bar at the top, and you'll be taken to the Compose Message screen.

=== Step 2: Compose Message ===

On this slide of the wizard, you will compose the actual message that is to be sent out to course participants. You can utilise pre-saved [[blocks/moodletxt/preferences|templates]] for sending out commonly used messages/notices, or write the message free-hand. You can also customise the message by merging in the recipient's name, and sign it with your own custom [[blocks/moodletxt/preferences|signature]].

Inside the large textbox marked "Message", please type your intended text message. As you type, you should see the number of characters you have used displayed directly above the message box, along with the number of individual SMS messages your text will be broken into.

[[Image:moodletxt-compose-counters.png|border|center]]

If you wish to use a pre-defined message template, select it from the drop-down list marked “Message Templates”, and it will automatically fill the textbox with the template for you. Message length counters will update automatically. If you wish to add your own customised signature to the message, checking the "Add Signature" checkbox will append your signature to the end of the message in the textbox.

Also, underneath the message text box. you will find three buttons, labelled "First Name," "Last Name," and "Full Name."

[[Image:moodletxt-compose-tag-buttons.png|border|center]]

Clicking on any of these buttons will insert a "tag" into the message. This tag will be automatically replaced, for each recipient, with the appropriate name, allowing you to add a personal touch to the message. For example:

''"Hello %FIRSTNAME%, welcome to DMU."''

Will be converted automatically to:

''"Hello Jaime, welcome to DMU."''

==== Unicode Messages ====

If you use any characters that do not fit within the standard [http://en.wikipedia.org/wiki/GSM_03.38 GSM alphabet] used by SMS messages, then these will be sent as Unicode messages. This does not affect message delivery in any way, but it does reduce the number of characters allowed per message from 160 to 70. MoodleTxt checks your text automatically as you type, and if you use characters that require a Unicode message, then a warning message will be displayed below the textbox. The "characters per message" field will also change to 70 to reflect this, and "characters/messages used" will be recalculated according to the new message length.

=== Step 3: Message Options ===

This step of the wizard allows you to schedule a message to be delivered at a later date, along with any other options that relate to message delivery.

==== Unicode Messaging Options ====

Firstly, if your message contains unicode message characters, as detailed above, you can opt to disable these characters in the outgoing message. If you decide to suppress these characters in the message, they may appear garbled on the recipient's phone (though the rest of the message should appear OK). However, doing so will restore the 160 character length of the message, and remove the restriction to 70 characters that unicode messages normally have.

To suppress unicode characters, select "Restrict message to GSM character set only" in the first option set, under the heading "Unicode Messaging Options".

==== Scheduling ====

To schedule your message for delivery at a later point, first you need to select the "Schedule to send later" option under the "Scheduling" heading. Once you have done this, select a time and date using the combo boxes provided. The date and time you enter is according to your own timezone on your Moodle user account; this will be converted automatically by MoodleTxt to Universal Time before sending.

=== Step 4: Review & Send ===

The final step of the wizard exists simply to allow you to review all the details of the message in one place, prior to it being sent. The recipients of the message are displayed, along with the message text, how many characters and messages per recipient will be used, and any unicode warnings that are relevant. Once you are happy with the information displayed on this last screen, click the "Send Message" button at the bottom to send the message to ConnectTxt.

[[Category:MoodleTxt|Send]]

Moodletxt push

2012-10-31T11:01:50Z

Tanthalas: XML push documentation for MoodleTxt.

== MoodleTxt and Pushed Updates ==

=== What is XML Push? ===

For those MoodleTxt administrators whose Moodle installations are publicly accessible from outside their local network, ConnectTxt offers a free service that automatically sends updates to sent messages, along with any new inbound messages, directly to your MoodleTxt installation.

=== Why should I use it? ===

XML Push updates are sent out as soon as they are received by the ConnectTxt system. As a result, this solution provides the quickest and most convenient update of message status records, and ensures that the information contained within your installation is up-to-date and useful. It also provides a performance boost for your MoodleTxt installation, as once XML Push is enabled you can disable the default update methods within MoodleTxt.

=== Information required for setup ===

To use XML Push, please first ensure that you are certain of the URL (web address) for your your Moodle installation. Beneath this, the XML Push script is located at “/blocks/moodletxt/push.php.” For example, if your URL for Moodle is normally:

<nowiki>https://www.yoursite.com/moodle</nowiki>

Then the path to XML Push will be:

<nowiki>https://www.yoursite.com/moodle/blocks/moodletxt/push.php</nowiki>

Once you have made a note of this URL, you must decide on a username and password for ConnectTxt to use to authenticate themselves on your installation. This username is used so that only ConnectTxt may send data through to your system, and helps to keep your installation secure – if the correct username and password are not supplied, XML Push simply shuts itself down, not accepting any further data.

When you have decided on a username and password for XML Push to use, please save them in [[admin/setting/blocksettingmoodletxt|MoodleTxt's system settings]] to enable the XML Push system.

=== Passing information to ConnectTxt ===

Now you should have all the information necessary to activate XML Push with ConnectTxt. Please contact the ConnectTxt support team (using the contact information displayed at the end of this document) with:

# A list of all the ConnectTxt accounts that will need to be enabled for use with XML Push (this is normally a list of all the accounts stored in MoodleTxt).
# The URL path to XML Push on your installation.
# The XML Push username and password you defined above and stored on the setting screen.

ConnectTxt will then activate your account(s) for use with XML Push. This process is normally completed quickly, but can take up to 24 hours.

=== After setup ===

If your change your XML Push username or password in the future, or add/remove any ConnectTxt accounts from the MoodleTxt system, please notify ConnectTxt of any changes that need to be made.

Once you have configured cron according to your needs, it is wise to turn off the per-request updates from the [[admin/setting/blocksettingmoodletxt|MoodleTxt Settings page]]. (These are the Get_Status_On_View and Get_Inbound_On_View settings.) These will no longer be needed, and you will gain a performance boost by disabling them.

=== ConnectTxt Contact Details ===

; Telephone : +44 (0) 113 234 2111
; E-mail : txttoolssupport@blackboard.com
; Live Chat : [http://messenger.providesupport.com/messenger/txttools.html Click here to chat live with our support team].

[[Category:MoodleTxt|Push Updates]]

blocks/moodletxt/preferences

2012-10-31T10:54:06Z

Tanthalas: Documentation for preferences page in MoodleTxt.

== MoodleTxt User Preferences ==

On this page of the block, you can configure your user-specific preferences. These include your message templates, SMS signature, and various other options that relate to how you use the messaging block.

=== Signature ===

A message signature is a short piece of text (up to 25 characters) that you can optionally append to the end of your outgoing messages within MoodleTxt. This signature is useful for identifying yourself to the recipient, or for including common reply information (such as "reply with keyword BEN"). If you already have a message signature stored within MoodleTxt, it will appear in the textbox labelled "signature", otherwise this block will be blank. To edit your signature, simply enter the text you would like to use in this box. You will notice the character counter above it decreasing from 25 towards 0 as you type, indicating the number of usable characters you have remaining. Once you hit 25 characters, you will be unable to type any further.

When you are happy with your signature text, click the "Save" button at the bottom of the page. The page will refresh, and you should receive a short notification that the signature text has been updated.

=== Message Templates ===

Message templates can be used to store and re-use commonly sent messages, making sending these messages quick and easy. Templates can be selected from the [[blocks/moodletxt/send|message composition page]], instead of filling in the message text by hand, and can contain any text that a regular message can.

You will notice two sections on the page, '''My Message Templates''' and '''Add New Template'''. The first of these lists all your existing message templates (if you have any), and allows you to select them for editing or deletion. The second section contains a text area in which you can add a new template to the system, or edit one you have selected from the existing list.

=== Adding a New Template ===

To add a new template, click inside the box labelled "Template Text", and enter your message. As you type, you should see the number of characters you have used displayed directly above the message box, along with the number of individual SMS messages your text will be broken into. For example, the display '''172 / 2''' means you have used 172 characters, and that this will be split into two messages when sent.

Also, underneath the message text box. you will find three buttons, labelled "First Name," "Last Name," and "Full Name."

[[Image:moodletxt-compose-tag-buttons.png|border|center]]

Clicking on any of these buttons will insert a "tag" into the message. This tag will be automatically replaced, for each recipient, with the appropriate name, allowing you to add a personal touch to the message. For example:

''"Hello %FIRSTNAME%, welcome to DMU."''

Will be converted automatically to:

''"Hello Jaime, welcome to DMU."''

When you are satisfied with the text in the template editing box, click the "Save" button at the bottom of the page. The page will refresh, and you should see a short notice at the top of the screen indicating that the template has been saved.

=== Editing an Existing Template ===

To edit a template that has already been saved in the MoodleTxt block, go to the section headed '''My Message Templates'''. Select the template you wish to edit from the list and click the "Edit Template" button below it. The '''Add New Template''' section will be retitled to '''Edit Existing Template''', and your template will appear in the editing box. You can now make your desired changes to it, exactly as if you were adding a new template to the system. When you are satisfied with your changes, click the "Save" button at the bottom of the page. The page will refresh, and you should see a short notice at the top of the screen indicating that the template has been updated.

=== Deleting a Template ===

To remove a template from MoodleTxt, go to the section headed '''My Message Templates'''. Select the template you wish to delete from the list and click the "Delete Template" button below it. A confirmation message will be displayed over the page. If you are happy to delete the template, click the "OK" button. The page will refresh, and a short message should be displayed at the top of the screen, indicating that the template has been deleted.

=== Inbox Preferences ===

Several options exist that relate to how MoodleTxt displays messages in your [[blocks/moodletxt/received|inbox]], and these are listed here. Firstly, you can instruct MoodleTxt to hide the names and phone numbers of received messages within the inbox listing. This is useful in classroom or group situations, where you wish to receive feedback or opinions from a number of people whilst keeping their responses anonymous. With this box checked, MoodleTxt will hide sender information for these messages.

Finally, there is the option to determine how often MoodleTxt's dynamic inbox checks for new messages with the Moodle system. If you are on the [[blocks/moodletxt/received|inbox]] page, it will check with the database for new messages at the interval you set here. Please note that this is separate from checking with the ConnectTxt system for new messages, and will only pick up messages that have already been received by the Moodle system. Administrators wanting more information on how messages are received by MoodleTxt can find it in the documentation for the [[admin/setting/blocksettingmoodletxt|main settings page]].

When you have edited your inbox preferences accordingly, click the "Save" button at the bottom of the page. The page will refresh, and you should see a short message at the top of the screen, indicating that your preferences have been updated.

[[Category:MoodleTxt|Preferences]]

File:moodletxt-compose-tag-buttons.png

2012-10-31T10:52:54Z

Tanthalas: Screenshot of the MoodleTxt message tagging buttons.

Screenshot of the MoodleTxt message tagging buttons.

error/block moodletxt/errornopermissionmessage

2012-10-31T10:44:23Z

Tanthalas: Error documentation for when a user attempts to view someone else's message in MoodleTxt

== Attempting to Access a Message You Do Not Have Permission to View ==

You have attempted to view the details of a sent message within MoodleTxt, and received the following message:

''You are not authorised to view this message.''

=== Cause ===
The message you have attempted to view does not belong to you, and you do not have the [[Moodletxt_capabilities|necessary access level]] to view another user's message details.

[[Category:MoodleTxt|Error]]

error/block moodletxt/errornoaccountspresent

2012-10-31T10:41:16Z

Tanthalas: Error documentation for when no ConnectTxt accounts have been linked to MoodleTxt

== No ConnectTxt Accounts Present Within MoodleTxt ==

You have gone to the "Compose a Message" page within MoodleTxt, and received the error message:

''No ConnectTxt accounts have been added to moodletxt. The system administrator must link moodletxt to one or more ConnectTxt accounts before messages can be sent.''

=== Cause ===
MoodleTxt uses SMS messaging accounts on the [http://www.bbconnecttxt.com/ ConnectTxt] messaging system to send and receive SMS messages. Before MoodleTxt can be used to send out messages, one or more ConnectTxt accounts must be made available to you via MoodleTxt's control panel.

=== Solution ===
Your system administrator must make one or more ConnectTxt accounts available for you to use.

If you are the system administrator, then you can find out more information about how to do this in the [[admin/setting/blocksettingmoodletxt|MoodleTxt settings documentation]].

[[Category:MoodleTxt|Error]]

error/block moodletxt/errorbadmessageid

2012-10-31T10:37:13Z

Tanthalas: Error documentation for invalid message IDs within MoodleTxt

== Attempting to View a Message That Does Not Exist ==

You have attempted to view a sent message within MoodleTxt, and received the error message:

''The message ID given does not exist, or does not belong to the user ID found. Please select a valid message to view.''

=== Cause ===
There are several potential causes for this error:

# The ID of the message you are attempting to view is incorrect. If you are copying and pasting a link to a message, please ensure that you have included all the page's parameters in the link.
# The message you are attempting to view no longer exists within the database.

[[Category:MoodleTxt|Error]]

error/block moodletxt/errorbadbookid

2012-10-31T10:34:42Z

Tanthalas: Error documentation for invalid address book IDs within MoodleTxt

== Attempting to View/Edit an Address Book That Is Not Yours ==

You have attempted to view or edit a MoodleTxt addressbook, or the contacts within it, and received the error message:

''The address book selected was invalid, or you do not own the address book you are attempting to edit.''

=== Cause ===
Address books created within MoodleTxt can only be edited by the user that created them, and in most cases this applies to viewing the address book also. You are attempting to edit an address book that you do not have ownership of, and as such MoodleTxt has blocked this action.

[[Category:MoodleTxt|Error]]

Moodletxt cron

2012-10-31T10:15:54Z

Tanthalas: Documentation for enabling cron updates within MoodleTxt.

== MoodleTxt Updates Via Cron ==

=== What is cron? ===

; Cron job : The term generally used (in Unix circles) to refer to a user-defined script or program that is automatically run at regular intervals.

MoodleTxt can optionally use a cron job to fetch regular updates from the ConnectTxt server, including new inbound messages, and status updates for previously sent messages.

=== Why use cron? ===

The recommended method of acquiring updates from the ConnectTxt system is [[Moodletxt_push|XML Push]]. However, this requires an inbound connection to your Moodle server. If you cannot configure this connection, but still wish to receive updates from the ConnectTxt system automatically, then you can use MoodleTxt's local cron job to automatically poll the ConnectTxt system for updates at regular intervals. This is much more efficient than the default update settings (where checks are made when certain pages are loaded) and will result in a performance increase for MoodleTxt.

=== Automatic Setup ===

As of MoodleTxt 2.4, this cron script automatically adds itself to the main Moodle maintenance script, so if you already have this running at short, regular intervals, no action is required to enable cron – MoodleTxt will automatically fetch inbound messages and status updates every time the Moodle maintenance script runs.

=== Custom Setup ===

If your Moodle maintenance script is not enabled, or does not run often enough for MoodleTxt use, you can still use cron to fetch message details. MoodleTxt provides a script that is another entry point to the cron system, which you can set to run at shorter intervals separate from the Moodle maintenance script. The path to this script is “/blocks/moodletxt/cron.php”, under your main Moodle installation directory. For example, if you have Moodle installed on Linux at:

/srv/www/moodle/

Then the path to the cron script would be:

/srv/www/moodle/blocks/moodletxt/cron.php

By specifying this file to be run in your chosen scheduling software, at an interval of your choosing, you can emulate the efficiency of the [[Moodletxt_push|XML Push]] service without changing your security configuration.

=== Steps to Take After Setup ===

Once you have configured cron according to your needs, it is wise to turn off the per-request updates from the [[admin/setting/blocksettingmoodletxt|MoodleTxt Settings page]]. (These are the Get_Status_On_View and Get_Inbound_On_View settings.) These will no longer be needed, and you will gain a performance boost by disabling them.

[[:Category:MoodleTxt | View all MoodleTxt documentation]]
[[Category:MoodleTxt|Cron]]

Moodletxt capabilities

2012-10-31T10:11:50Z

Tanthalas: Detailed listing of all capabilities installed by MoodleTxt.

== List of all capabilities installed by MoodleTxt ==

This page is an administrator's reference for the user capabilities that will be installed into your Moodle installation by MoodleTxt. You can use these to grant or deny access to the various sections of MoodleTxt using these capabilities in the standard Moodle control panel.

{| class="nicetable"
|-
! Capability Name
! Default Assignment
! Description
|-
| block/moodletxt:addressbooks
| Teachers and admins
| Granting this permission allows a user to create addressbooks within MoodleTxt
|-
| block/moodletxt:adminsettings
| Admins only
| Allows a user to use the MoodleTxt control panel and see error messages intended for administrators.
|-
| block/moodletxt:adminusers
| Admins only
| Allows a user to admin user information within MoodleTxt, such as editing a user's message filters, or viewing their message history.
|-
| block/moodletxt:defaultinbox
| Teachers and admins
| If a user has this capability assigned to them at system level, then they can be selected as the "default inbox" when creating message filters. (A default inbox is where any unfiltered messages for a given account are deposited.)
|-
| block/moodletxt:globaladdressbooks
| Teachers and admins
| If this user can create address books within MoodleTxt, they can create global address books that can be viewed and used by all users within the system.
|-
| block/moodletxt:personalsettings
| Teachers and admins
| Having this capability assigned to a user allows them to edit their own messaging preferences. This includes message templates and signatures, as well as options related to message display.
|-
| block/moodletxt:receivemessages
| Teachers and admins
| Any user that has this capability assigned can receive inbound messages within the block.
|-
| block/moodletxt:sendmessages
| Teachers and admins
| Any user that has this capability assigned can send messages out from the block.
|-
| block/moodletxt:viewstats
| Teachers and admins
| Any user that has this capability assigned can view user/message statistics. (Coming in 3.1)
|-
| block/moodletxt:viewmoodletxtpluslogs
| Admins only
| Allows the user to view the logs of event-based messaging. (Largely redundant, may be removed in 3.1. Users that have the :adminusers permission can use the sent page, which was upgraded since 3.0 beta 2, to view these logs already.)
|}

[[Category:MoodleTxt|Capabilities]]

blocks/moodletxt/addressbooks

2012-10-31T09:59:12Z

Tanthalas: Initial commit of documentation for MoodleTxt's addressbook management page

== MoodleTxt: Managing Address Books ==

MoodleTxt allows you to create your own address books of contacts for sending messages to. These are generally contacts who do not have accounts within the Moodle system themselves, such as the parents of students.

Your existing address books (if you have any) are displayed at the top of the page. Clicking on the name of an address book will open it for browsing and editing on another page. The icon next to an address book indicates whether it is a private or global addressbook.

[[Image:moodletxt-addressbook-icons.png|frame|none|Example of a global and private addressbook, with icons.]]

; Private Address Books : These are address books visible only to you, and can only have messages sent to them from your account.
; Global Address Books : These are visible to all users within the Moodle system, and messages can be sent to them from anywhere. However, the address book can still only be edited/maintained by you.

=== Adding a New Address Book ===

Adding a new address book to MoodleTxt is simple. Under the '''Add a new address book''' heading, type the name of the new address book into the box labelled "Address book name". Below that, select whether you want the address book to be private (only usable by you) or global (usable by anyone).

When you are happy with your selections, click the "Add" button below the form. The page will refresh, and your new address book should appear in the list at the top of the page, along with a short success message indicating that the address book was saved to the database successfully. You can now click into the address book and begin adding contacts to it.

=== Deleting an Existing Address Book ===

This section allows you to permanently delete an address book from the MoodleTxt block, or optionally merge it into another existing address book.

Firstly, select the address book you wish to delete from the first drop-down box in this section. Next, you have the option to either delete the contacts in the address book, or merge them into another one. If you select the first option, then when the address book is deleted, all contacts and contact groups within it will also be permanently deleted. If you select the second option, then when the address book is deleted, all of its contacts and groups will be moved into another address book within the system. In order to use this option, you must select the destination address book from the second drop-down list provided.

Once you are happy with the options selected, click the "Delete/Merge" button below the form. The page will be refreshed, and your selected address book should have been removed from the list of existing address books at the top of the page. A short notification message should also be displayed, indicating that the address book was successfully deleted from the database.

[[Category:MoodleTxt|Addressbooks]]

File:moodletxt-addressbook-icons.png

2012-10-31T09:57:57Z

Tanthalas: Screenshot of existing address books listed on the MoodleTxt addressbook management page.

Screenshot of existing address books listed on the MoodleTxt addressbook management page.

blocks/moodletxt/addressbook view

2012-10-31T09:46:21Z

Tanthalas: Initial commit of documentation for MoodleTxt's addressbook listing

== Viewing a MoodleTxt Address Book ==

This page exists displays all contacts available within the selected address book. It allows you to browse, edit and delete them, as well as export the list to a file for download. If you wish to add a new contact to the address book, or edit your address book's contact groups, two links to the pages that handle this functionality are available at the top-left of the page.

=== Contact Listing ===

The primary feature of this page is a listing of all contacts contained within the address book. The table of contacts shows the following fields:

*Contact's first name
*Contact's last name
*Name of company (if contact is a company, or represents one)
*Contact's phone number

The list displayed is a standard Moodle table, and can be re-ordered, edited and navigated like any other tabular list in Moodle.

=== Editing a Listed Contact ===

MoodleTxt supports inline editing of the contacts displayed in the contact list. To edit a contact, simply double-click on it. The text row representing that contact will be automatically converted into a form.

[[Image:moodletxt-addressbook-contact-edit.png|border|none]]

You can then make the appropriate corrections to the contact directly within the listing. Once you are satisfied with your changes, click the "Save" button at the right of the contact row, and the contact will be saved back into the listing. Clicking "Cancel" will revert any changes and restore the contact's entry to its previous state.

=== Deleting One or More Contacts ===

To delete contacts from your address book, first select them in the contact listing by checking the box at the left of each contact entry. (You can also select or deselect all contacts on the page by using the "Check all"/"Uncheck all" links at the bottom left of the table.) Once you have the contacts you wish to delete selected, click the "Delete the selected records" link underneath the contact listing, and the contacts will be removed from the address book.

Alternatively, if the set of contacts you wish to retain in the address book is smaller than the set you wish to delete, you can select the contacts you wish to keep, and then click the link labelled "Delete all records except those currently selected" underneath the contact listing. This will delete all contacts in the address book except for those that you have selected from the contact listing.

=== Changing the Address Book's Name and Visibility ===

If you wish to change the details of the address book, they are displayed as an inline form at the top-left of the page, just above the contact listing. Simply edit the address book's name and visibility level and click the "Save" button. The page will refresh, and a short notification should be displayed indicating that the address book's details were updated in the database.

Possible visibility levels for the address book:

; Private Address Books : These are address books visible only to you, and can only have messages sent to them from your account.
; Global Address Books : These are visible to all users within the Moodle system, and messages can be sent to them from anywhere. However, the address book can still only be edited/maintained by you.

[[Category:MoodleTxt|Addressbook Listing]]

File:moodletxt-addressbook-contact-edit.png

2012-10-31T09:45:33Z

Tanthalas: Screenshot of a contact being edited in the MoodleTxt address book.

Screenshot of a contact being edited in the MoodleTxt address book.

blocks/moodletxt/addressbook groups

2012-10-31T09:37:38Z

Tanthalas: Initial commit of the MoodleTxt group management page

== Managing your MoodleTxt Addressbook Groups ==

This page consists of three forms, allowing you to add, edit and delete groups.

=== Adding a Group ===

Adding a group to the address book couldn't be simpler. Locate the form at the top of the page headed '''Add a Group'''. This form has a single text box for the name of the group. Give the group a name, and then click the "Add Group" button, and the new contact group will be created.

=== Updating Group Members ===

If you wish to add or remove members from a group, first select the group you wish to modify from the large drop-down box at the top of the form labelled '''Update Group Members'''. When you have selected a group, you should see the form update, with the current group members being moved from the list of potential members on the left to the list of current members on the right (assuming that the group already has members).

[[Image:moodletxt-group-member-selector.png|frame|center|Group membership selector]]

To add contacts to the group, select them from the list of potential members on the left, and click the ">>" button. You will see them move to the list of group members on the right. To remove contacts from the group, select them from the right hand list and click the "<<" button.

Once you are satisfied with the list of group members, click the "Update Group" button, and the group membership list will be updated. The page will refresh, and a short notification should be displayed indicating that the group has been saved to the database.

=== Deleting Groups ===

The first step to deleting a group is to select the one you wish to delete from the drop-down list at the top of the form labelled '''Delete a Group'''. (You'll find it at the bottom of the page.)

When you have done this, you need to confirm what should happen to the contacts that are already in the group being deleted. Three options are available, and are shown below the group list.

; Preserve Contacts : Will remove the group without affecting the contacts contained within it.
; Delete Contacts : This will remove the group and delete its members from the address book. This is useful for erasing old classes/years from the book.
; Merge Contacts : This will remove the group and transfer its contacts into another group, allowing you to merge groups together. If you select this option, be sure to select a destination group from the drop-down list provided.

Once you have decided what you want to happen to the group's members, click the "Delete Group" button and the group will be erased from the address book.

[[Category:MoodleTxt|Addressbook Groups]]

File:moodletxt-group-member-selector.png

2012-10-31T09:37:06Z

Tanthalas: Screenshot of the MoodleTxt group membership selector.

Screenshot of the MoodleTxt group membership selector.

blocks/moodletxt/addressbook contact add

2012-10-31T09:25:16Z

Tanthalas: Initial commit of MoodleTxt "add contact" page

== Adding a Contact to a MoodleTxt Address Book ==

This page allows you to add a new contact to your address book. The first section allows you to enter some basic information about the contact:

*Contact's first name
*Contact's last name
*Name of company (if contact is a company, or represents one)
*Contact's phone number

=== Group Membership ===

Any groups that already exist within your address book are displayed in the "Addressbook Groups" list on the left of the page. If you want to add this new contact to any of these groups, select them from the list on the left and click the >> button. This will move them to the list on the right hand side of the page. The new contact will be added to any groups that are shown in this list on the right when it is saved to the address book.

=== Saving the Contact ===

When you are satisfied with the details you have entered for the new contact, you have two options when saving it. You can either save the contact, and return to the address book's listing page, or you can clear the form to add another contact. Select the appropriate button from the bottom of the form, and the contact will be saved to the database.

[[Category:MoodleTxt|Addressbook Add Contact]]

Category:MoodleTxt

2012-10-31T09:19:53Z

Tanthalas: Initial commit of MoodleTxt category page

This category contains all documentation for the MoodleTxt 2-way SMS messaging block, provided and powered by [http://www.bbconnecttxt.com/ ConnectTxt]. It also contains information on the related messaging processor, MoodleTxt Plus.

[https://moodle.org/plugins/view.php?plugin=block_moodletxt MoodleTxt block in the plugin repository]

[https://moodle.org/plugins/view.php?plugin=message_moodletxtplus MoodleTxt+ message processor add-on in the plugin repository]

User:Greg Preece

2011-07-29T15:26:41Z

Tanthalas: Editing to match the /dev wiki

= Greg J Preece =

Greg J Preece is a PHP developer, who develops and maintains the moodletxt SMS messaging block for Moodle.

[http://moodle.org/user/view.php?id=146613 Greg's Moodle Profile]

== Work and Contribs ==

Greg contributes updates to the [[Blocks|Moodle blocks developer documentation]].

[http://moodle.org/mod/data/view.php?d=13&rid=958&filter=1 moodletxt SMS block - Development and Maintenance]

[http://www.txttools.co.uk/preloginjsp/txttools/developers.jsp txttools PHP API - Development and Maintenance]

[http://www.txttools.co.uk txttools Homepage]

User:Greg Preece

2011-07-27T08:06:53Z

Tanthalas:

Greg J Preece is a PHP developer, who develops and maintains the moodletxt SMS messaging block for Moodle. He also contributes to MoodleDocs when he can, and is currently re-writing the block developer documentation, based on his experiences with redeveloping moodletxt.

[http://moodle.org/user/view.php?id=146613 Greg's Moodle Profile]

[http://moodle.org/mod/data/view.php?d=13&rid=958&filter=1 moodletxt Block]

User:Greg Preece

2011-07-27T08:06:29Z

Tanthalas:

Greg J Preece is a PHP developer, who develops and maintains the moodletxt SMS messaging block for Moodle. He also contributes to MoodleDocs when he can, and is currently re-writing the block developer documentation, based on his experiences with redeveloping moodletxt.

[http://moodle.org/user/view.php?id=146613|Greg's Moodle Profile]

[http://moodle.org/mod/data/view.php?d=13&rid=958&filter=1|moodletxt Block]

Development:Installing and upgrading plugin database tables

2010-08-18T10:08:51Z

Tanthalas: /* Introduction */

==Introduction==

If you have done the right thing, Moodle will automatically create the database tables for your plugin when you visit the Admin notifications page (.../admin/index.php). This process is controlled by three files within your plugin:
;version.php : This records the version of the plugin code ('''Please note:''' In Moodle installations below v2.0, this is not required for blocks, which use the version number returned by the block's init() method - see [[Development:Blocks#Ready.2C_Set.2C_Go.21|the blocks development page]])
;db/install.xml : This is used when someone installs your plugin for the first time.
;db/upgrade.php : This is used when someone who had an older version of your plugin installed upgrades to the latest version.

In addition, Moodle also stores in the database the currently installed version of each plugin.

In Moodle 1.9 and before, this is stored in the mdl_config table, in a row with the name ''plugintype''_''pluginname''_version. For example qtype_myqtype_version. The exception to this rule are modules and blocks. Installed module version numbers are stored in the mdl_modules table. Block version numbers are in mdl_block.

In Moodle 2.0 an beyond, plugin version numbers are stored in the mdl_config_plugins table, with ''plugintype''_''pluginname'' in the plugin column, and 'version' in the name column - with the same exception for modules and blocks.

==A specific example==

For the rest of this document, I will use a particular example, because it should make the explanation easier. You should be able to see how to generalise it.

We will suppose you that you are making a new question type myqtype. This is plugin type qtype, and the code will be in the question/type/myqtype folder. The currently installed version number will be stored in the qtype_myqtype_version row of the mdl_config table.

In addition, we will just consider the first two releases of the plugin. The first release will have version number 2008080100, and will just use one database table mdl_question_myqtype, with two columns col1 and col2. Then we will suppose that the second release is 2008080200, and that requires an extra column, newcol, to be added to the mdl_question_myqtype table.

==The files you need for the first release==

In what follows, the bits of code you need to replace are '''in bold'''.

;version.php
$plugin->version = 2008080100;
$plugin->requires = '''XXXXXXXXXX; // Copy the current value from the top-level version.php file.'''
;db/install.xml
:This file, which you should [[XMLDB editor|create with the XMLDB editor]], should contain the definition for your mdl_question_myqtype table, with the two columns col1 and col2.

At this stage, you do not need a db/upgrade.php file.

==The files you need for the second release==

;version.php
$plugin->version = 2008080200;
$plugin->requires = '''XXXXXXXXXX; // Copy the current value from the top-level version.php file.'''
;db/install.xml : This file should now contain the updated definition for your mdl_question_myqtype table, with three columns col1, col2 and newcol. You modify this file using the XMLDB editor.
;db/upgrade.php
:This file should contain the code that people need to run to upgrade from version 2008080100 of your plugin. That is, the code to add a column newcol to the mdl_question_myqtype table. You don't have to write this code yourself as the XMLDB editor will generate it for you. The upgrade.php file should contain a single function xmldb_qtype_myqtype_upgrade that looks a bit like:
function xmldb_qtype_myqtype_upgrade($oldversion = 0) {
$result = true;

/// Add a new column newcol to the mdl_question_myqtype
if ($result && $oldversion < 2008080200) {
'''// Code to add the column, generated by the 'View PHP Code' option of the XMLDB editor.'''
}

return $result;
}

''Hint: If you are modifying or adding a field/table, get the XMLDB editor to generate the PHP update code for you '''after''' making the changes in the editor. If you are deleting one, you need to generate the PHP code '''before''' making the change - or you won't be able to select the field/table to write the code for, because it no longer exists.''

==What happens when a user installs or upgrades your plugin==

The process is triggered when an administrator goes to the Admin notifications page (.../admin/index.php). The code that does the work is the upgrade_plugins function in lib/adminlib.php and reading this code is the best way to find out exactly what happens. In pseudo-code, what it does is:

For each plugin of this type (e.g. all qtype plugins) {
// For the body of this loop, suppose the current plugin being processed is myqtype.

Check that question/type/myqtype/version.php, .../db/upgrade.php and .../db/install.xml exist.

if ($CFG->qtype_myqtype_version exists, and is less than the number in version.php) {
Call the upgrade function xmldb_qtype_myqtype_upgrade from
upgrade.php, passing the old version number ($CFG->qtype_myqtype_version)
which says what is currently installed
Update $CFG->qtype_myqtype_version to the latest number from version.php
to record what is currently installed
}

else if ($CFG->qtype_myqtype_version does not exist) {
Create the tables from the definitions in install.xml
Update $CFG->qtype_myqtype_version to the latest number from version.php
to record what is currently installed
}
}

Of course, it is a bit more complex that than. However, the code in the upgrade_plugins is quite clear, and I encourage you to go and have a look at it so you can see all the details of how it works.

Let us now look at some worked examples:

===User installs version 2008080100 of myqtype===

To start with, the mdl_question_myqtype does not exist, and there will not be a qtype_myqtype_version row in the mdl_config table.

# The user will unzip myqtype.zip into the question/type folder.
# The user will visit the Admin notifications page.
# This will trigger Moodle to search for plugings to upgrade. It will find that the code for the qtype_myqtype plugin is now present, but there is no trace of it in the database, so it will install the plugin from the install.xml file.

At the end of this process, the mdl_question_myqtype table will exist with the two columns col1 and col2; and the qtype_myqtype_version row in the mdl_config table will contain 2008080100.

===User upgrades from version 2008080100 to version 2008080200 of myqtype===

To start with, the mdl_question_myqtype table will exist with the two columns col1 and col2; and the qtype_myqtype_version row in the mdl_config table will contain 2008080100.

# The user will delete the old question/type/myqtype folder.
# The user will unzip the new myqtype.zip into the question/type folder.
# The user will visit the Admin notifications page.
# This will trigger Moodle to search for plugings to upgrade. It will find that the code for version 2008080200 the qtype_myqtype plugin is now present, but the installed version of the the database tables (qtype_myqtype_version) is 2008080100. Therefore, it will call xmldb_qtype_myqtype_upgrade from upgrade.php, passing 2008080100 as the $oldversion argument.

At the end of this process, the mdl_question_myqtype table will now have three columns col1, col2 and newcol; and the qtype_myqtype_version row in the mdl_config table will contain 2008080200.

===User installs version 2008080200 of myqtype into a clean Moodle install===

To start with, the mdl_question_myqtype does not exist, and there will not be a qtype_myqtype_version row in the mdl_config table.

# The user will unzip the 2008080200 version of myqtype.zip into the question/type folder.
# The user will visit the Admin notifications page.
# This will trigger Moodle to search for plugings to upgrade. It will find that the code for the qtype_myqtype plugin is now present, but there is no trace of it in the database, so it will install the plugin from the install.xml file.

At the end of this process, the mdl_question_myqtype table will exist with three columns col1, col2 and newcol; and the qtype_myqtype_version row in the mdl_config table will contain 2008080200.

==Summary==

The first time a user installs any version of your plugin, the install.xml file will be used to create all the required database tables. Therefore install.xml should always contain the definition of the up-to-date database structure. Moodle recognises this situation because there is a version.php file on disc, but there is no ''plugintype''_''pluginname''_version value in the mdl_config table.

If the user already had a version of your plugin installed, and then upgrades to a newer version, Moodle will detect this because the version.php file will contain a newer version number than the ''plugintype''_''pluginname''_version value in the mdl_config table. In this case, Moodle will run the code in the upgrade.php file, passing in the old version number, so that the correct bits of upgrade can be run, as controlled by the if ($oldversion < XXXXXXXXXX) blocks of code.

The contents of the install.xml and upgrade.php files should be generated using the XMLDB editor.

==Database upgrades and stable branches==

The simple rule is, never make any database changes on a stable branch. You only need to read this section in the rare situations where a database change on the stable branch is unavoidable.

'''Warning!!! advanced material follows.'''

Suppose, in order to fix a bug, you need to make a database change in Moodle 1.9.3+ (which must also be merged into HEAD). The root of the problem is that people may upgrade their Moodle in three different ways, which

* Upgrade from <=1.9.3 to 1.9.4 - this executes the ugprade script on the 1.9 branch.
* Upgrade from <=1.9.3 directly to >=2.0 - this executes the upgrade script on the HEAD branch.
* Upgrade from 1.9.4 to >=2.0 - in this case, you must ensure that the upgrade on HEAD is not executed.

The normal way to do this is ensure that your database upgrade is idempotent. That is, it does not matter if you do it twice. So for example, instead of doing

$dbman->create_table($table);

you should do

if (!$dbman->table_exists($table)) {
$dbman->create_table($table);
}

You should also think about what version numbers to put in your version.php file on each branch. Above all, test carefully.

==See also==

* [[Development:XMLDB_Documentation|XMLDB_Documentation]]
* [[Development:Coding|Coding guidelines]]
* [[Development:DDL functions|DDL functions]]
* [[Development:XMLDB defining an XML structure|install.xml file documentation]]

[[Category:Developer]]
[[Category:XMLDB]]
[[Category:Installation]]

Development:Installing and upgrading plugin database tables

2010-06-25T08:53:50Z

Tanthalas: Noting that version.php is not required for blocks

==Introduction==

If you have done the right thing, Moodle will automatically create the database tables for your plugin when you visit the Admin notifications page (.../admin/index.php). This process is controlled by three files within your plugin:
;version.php : This records the version of the plugin code ('''Please note:''' not required for blocks, which use the version number returned by the block's init() method - see [[Development:Blocks#Ready.2C_Set.2C_Go.21|the blocks development page]])
;db/install.xml : This is used when someone installs your plugin for the first time.
;db/upgrade.php : This is used when someone who had an older version of your plugin installed upgrades to the latest version.

In addition, Moodle also stores in the database the currently installed version of each plugin.

In Moodle 1.9 and before, this is stored in the mdl_config table, in a row with the name ''plugintype''_''pluginname''_version. For example qtype_myqtype_version. The exception to this rule are modules and blocks. Installed module version numbers are stored in the mdl_modules table. Block version numbers are in mdl_block.

In Moodle 2.0 an beyond, plugin version numbers are stored in the mdl_config_plugins table, with ''plugintype''_''pluginname'' in the plugin column, and 'version' in the name column - with the same exception for modules and blocks.

==A specific example==

For the rest of this document, I will use a particular example, because it should make the explanation easier. You should be able to see how to generalise it.

We will suppose you that you are making a new question type myqtype. This is plugin type qtype, and the code will be in the question/type/myqtype folder. The currently installed version number will be stored in the qtype_myqtype_version row of the mdl_config table.

In addition, we will just consider the first two releases of the plugin. The first release will have version number 2008080100, and will just use one database table mdl_question_myqtype, with two columns col1 and col2. Then we will suppose that the second release is 2008080200, and that requires an extra column, newcol, to be added to the mdl_question_myqtype table.

==The files you need for the first release==

In what follows, the bits of code you need to replace are '''in bold'''.

;version.php
$plugin->version = 2008080100;
$plugin->requires = '''XXXXXXXXXX; // Copy the current value from the top-level version.php file.'''
;db/install.xml
:This file, which you should [[XMLDB editor|create with the XMLDB editor]], should contain the definition for your mdl_question_myqtype table, with the two columns col1 and col2.

At this stage, you do not need a db/upgrade.php file.

==The files you need for the second release==

;version.php
$plugin->version = 2008080200;
$plugin->requires = '''XXXXXXXXXX; // Copy the current value from the top-level version.php file.'''
;db/install.xml : This file should now contain the updated definition for your mdl_question_myqtype table, with three columns col1, col2 and newcol. You modify this file using the XMLDB editor.
;db/upgrade.php
:This file should contain the code that people need to run to upgrade from version 2008080100 of your plugin. That is, the code to add a column newcol to the mdl_question_myqtype table. You don't have to write this code yourself as the XMLDB editor will generate it for you. The upgrade.php file should contain a single function xmldb_qtype_myqtype_upgrade that looks a bit like:
function xmldb_qtype_myqtype_upgrade($oldversion = 0) {
$result = true;

/// Add a new column newcol to the mdl_question_myqtype
if ($result && $oldversion < 2008080200) {
'''// Code to add the column, generated by the 'View PHP Code' option of the XMLDB editor.'''
}

return $result;
}

''Hint: If you are modifying or adding a field/table, get the XMLDB editor to generate the PHP update code for you '''after''' making the changes in the editor. If you are deleting one, you need to generate the PHP code '''before''' making the change - or you won't be able to select the field/table to write the code for, because it no longer exists.''

==What happens when a user installs or upgrades your plugin==

The process is triggered when an administrator goes to the Admin notifications page (.../admin/index.php). The code that does the work is the upgrade_plugins function in lib/adminlib.php and reading this code is the best way to find out exactly what happens. In pseudo-code, what it does is:

For each plugin of this type (e.g. all qtype plugins) {
// For the body of this loop, suppose the current plugin being processed is myqtype.

Check that question/type/myqtype/version.php, .../db/upgrade.php and .../db/install.xml exist.

if ($CFG->qtype_myqtype_version exists, and is less than the number in version.php) {
Call the upgrade function xmldb_qtype_myqtype_upgrade from
upgrade.php, passing the old version number ($CFG->qtype_myqtype_version)
which says what is currently installed
Update $CFG->qtype_myqtype_version to the latest number from version.php
to record what is currently installed
}

else if ($CFG->qtype_myqtype_version does not exist) {
Create the tables from the definitions in install.xml
Update $CFG->qtype_myqtype_version to the latest number from version.php
to record what is currently installed
}
}

Of course, it is a bit more complex that than. However, the code in the upgrade_plugins is quite clear, and I encourage you to go and have a look at it so you can see all the details of how it works.

Let us now look at some worked examples:

===User installs version 2008080100 of myqtype===

To start with, the mdl_question_myqtype does not exist, and there will not be a qtype_myqtype_version row in the mdl_config table.

# The user will unzip myqtype.zip into the question/type folder.
# The user will visit the Admin notifications page.
# This will trigger Moodle to search for plugings to upgrade. It will find that the code for the qtype_myqtype plugin is now present, but there is no trace of it in the database, so it will install the plugin from the install.xml file.

At the end of this process, the mdl_question_myqtype table will exist with the two columns col1 and col2; and the qtype_myqtype_version row in the mdl_config table will contain 2008080100.

===User upgrades from version 2008080100 to version 2008080200 of myqtype===

To start with, the mdl_question_myqtype table will exist with the two columns col1 and col2; and the qtype_myqtype_version row in the mdl_config table will contain 2008080100.

# The user will delete the old question/type/myqtype folder.
# The user will unzip the new myqtype.zip into the question/type folder.
# The user will visit the Admin notifications page.
# This will trigger Moodle to search for plugings to upgrade. It will find that the code for version 2008080200 the qtype_myqtype plugin is now present, but the installed version of the the database tables (qtype_myqtype_version) is 2008080100. Therefore, it will call xmldb_qtype_myqtype_upgrade from upgrade.php, passing 2008080100 as the $oldversion argument.

At the end of this process, the mdl_question_myqtype table will now have three columns col1, col2 and newcol; and the qtype_myqtype_version row in the mdl_config table will contain 2008080200.

===User installs version 2008080200 of myqtype into a clean Moodle install===

To start with, the mdl_question_myqtype does not exist, and there will not be a qtype_myqtype_version row in the mdl_config table.

# The user will unzip the 2008080200 version of myqtype.zip into the question/type folder.
# The user will visit the Admin notifications page.
# This will trigger Moodle to search for plugings to upgrade. It will find that the code for the qtype_myqtype plugin is now present, but there is no trace of it in the database, so it will install the plugin from the install.xml file.

At the end of this process, the mdl_question_myqtype table will exist with three columns col1, col2 and newcol; and the qtype_myqtype_version row in the mdl_config table will contain 2008080200.

==Summary==

The first time a user installs any version of your plugin, the install.xml file will be used to create all the required database tables. Therefore install.xml should always contain the definition of the up-to-date database structure. Moodle recognises this situation because there is a version.php file on disc, but there is no ''plugintype''_''pluginname''_version value in the mdl_config table.

If the user already had a version of your plugin installed, and then upgrades to a newer version, Moodle will detect this because the version.php file will contain a newer version number than the ''plugintype''_''pluginname''_version value in the mdl_config table. In this case, Moodle will run the code in the upgrade.php file, passing in the old version number, so that the correct bits of upgrade can be run, as controlled by the if ($oldversion < XXXXXXXXXX) blocks of code.

The contents of the install.xml and upgrade.php files should be generated using the XMLDB editor.

==Database upgrades and stable branches==

The simple rule is, never make any database changes on a stable branch. You only need to read this section in the rare situations where a database change on the stable branch is unavoidable.

'''Warning!!! advanced material follows.'''

Suppose, in order to fix a bug, you need to make a database change in Moodle 1.9.3+ (which must also be merged into HEAD). The root of the problem is that people may upgrade their Moodle in three different ways, which

* Upgrade from <=1.9.3 to 1.9.4 - this executes the ugprade script on the 1.9 branch.
* Upgrade from <=1.9.3 directly to >=2.0 - this executes the upgrade script on the HEAD branch.
* Upgrade from 1.9.4 to >=2.0 - in this case, you must ensure that the upgrade on HEAD is not executed.

The normal way to do this is ensure that your database upgrade is idempotent. That is, it does not matter if you do it twice. So for example, instead of doing

$dbman->create_table($table);

you should do

if (!$dbman->table_exists($table)) {
$dbman->create_table($table);
}

You should also think about what version numbers to put in your version.php file on each branch. Above all, test carefully.

==See also==

* [[Development:XMLDB_Documentation|XMLDB_Documentation]]
* [[Development:Coding|Coding guidelines]]
* [[Development:DDL functions|DDL functions]]
* [[Development:XMLDB defining an XML structure|install.xml file documentation]]

[[Category:Developer]]
[[Category:XMLDB]]
[[Category:Installation]]

User:Greg Preece

2008-06-25T11:54:26Z

Tanthalas: New page: Greg Preece is a PHP developer, who develops and maintains the moodletxt SMS messaging block for Moodle. See: http://moodle.org/user/view.php?id=146613

Greg Preece is a PHP developer, who develops and maintains the moodletxt SMS messaging block for Moodle.

See: http://moodle.org/user/view.php?id=146613

Development:Blocks

2008-06-25T11:53:02Z

Tanthalas: Added after_install and before_delete methods to appendix. Noted when methods were first introduced.

''' A Step-by-step Guide To Creating Blocks '''

Original Author: Jon Papaioannou (pj@moodle.org)

The present document serves as a guide to developers who want to create their own blocks for use in Moodle. It applies to the 1.5 development version of Moodle (and any newer) '''only''', as the blocks subsystem was rewritten and expanded for the 1.5 release. However, you can also find it useful if you want to modify blocks written for Moodle 1.3 and 1.4 to work with the latest versions (look at [[Blocks_Howto#appendix_b| Appendix B]]).
The guide is written as an interactive course which aims to develop a configurable, multi-purpose block that displays arbitrary HTML. It's targeted mainly at people with little experience with Moodle or programming in general and aims to show how easy it is to create new blocks for Moodle. A certain small amount of PHP programming knowledge is still required, though. Experienced developers and those who just want a reference text should refer to [[Blocks_Howto#appendix_a| Appendix A]] because the main guide has a rather low concentration of pure information in the text.

== Basic Concepts ==
Through this guide, we will be following the creation of an "HTML" block from scratch in order to demonstrate most of the block features at our disposal. Our block will be named "SimpleHTML". This does not constrain us regarding the name of the actual directory on the server where the files for our block will be stored, but for consistency we will follow the practice of using the lowercased form "simplehtml" in any case where such a name is required. Whenever we refer to a file or directory name which contains "simplehtml", it's important to remember that ''only'' the "simplehtml" part is up to us to change; the rest is standardized and essential for Moodle to work correctly.
Whenever a file's path is mentioned in this guide, it will always start with a slash. This refers to the Moodle home directory; all files and directories will be referred to with respect to that directory.

== Ready, Set, Go! ==
To define a "block" in Moodle, in the most basic case we need to provide just one source code file. We start by creating the directory <span class="filename">/blocks/simplehtml/</span> and creating a file named <span class="filename">/blocks/simplehtml/block_simplehtml.php</span> which will hold our code. We then begin coding the block:
<?php
class block_simplehtml extends block_base {
function init() {
$this->title = get_string('simplehtml', 'block_simplehtml');
$this->version = 2004111200;
}

The first line is our block class definition; it must be named exactly in the manner shown. Again, only the "simplehtml" part can (and indeed must) change; everything else is standardized.
Our class is then given a small method: [[Blocks_Howto#method_init| init]]. This is essential for all blocks, and its purpose is to set the two class member variables listed inside it. But what do these values actually mean? Here's a more detailed description.
[[Blocks_Howto#variable_title| $this->title]] is the title displayed in the header of our block. We can set it to whatever we like; in this case it's set to read the actual title from a language file we are presumably distributing together with the block. I 'll skip ahead a bit here and say that if you want your block to display '''no''' title at all, then you should set this to any descriptive value you want (but '''not''' make it an empty string). We will later see [[Blocks_Howto#section_eye_candy| how to disable the title's display]].
[[Blocks_Howto#variable_version| $this->version]] is the version of our block. This actually would only make a difference if your block wanted to keep its own data in special tables in the database (i.e. for very complex blocks). In that case the version number is used exactly as it's used in activities; an upgrade script uses it to incrementally upgrade an "old" version of the block's data to the latest. We will outline this process further ahead, since blocks tend to be relatively simple and not hold their own private data. In our example,
this is certainly the case so we just set [[Blocks_Howto#variable_version| $this->version]] to '''YYYYMMDD00''' and forget about it.
'''UPDATING:''' Prior to version 1.5, the basic structure of each block class was slightly different. Refer to [[Blocks_Howto#appendix_b| Appendix B]] for more information on the changes that old blocks have to make to conform to the new standard.

== I Just Hear Static ==
In order to get our block to actually display something on screen, we need to add one more method to our class (before the final closing brace in our file). The new code is:
function get_content() {
if ($this->content !== NULL) {
return $this->content;
}

$this->content = new stdClass;
$this->content->text = 'The content of our SimpleHTML block!';
$this->content->footer = 'Footer here...';

return $this->content;
}
}
?>
It can't get any simpler than that, can it? Let's dissect this method to see what's going on...
First of all, there is a check that returns the current value of [[Blocks_Howto#variable_content| $this->content]] if it's not NULL; otherwise we proceed with "computing" it. Since the computation is potentially a time-consuming operation and it '''will''' be called several times for each block (Moodle works that way internally), we take a precaution and include this time-saver.
Supposing the content had not been computed before (it was NULL), we then define it from scratch. The code speaks for itself there, so there isn't much to say. Just keep in mind that we can use HTML both in the text '''and''' in the footer, if we want to.
At this point our block should be capable of being automatically installed in Moodle and added to courses; visit your administration page to install it and after seeing it in action come back to continue our tutorial.

== Configure That Out ==
The current version of our block doesn't really do much; it just displays a fixed message, which is not very useful. What we 'd really like to do is allow the teachers to customize what goes into the block. This, in block-speak, is called "instance configuration". So let's give our block some instance configuration...
First of all, we need to tell Moodle that we want it to provide instance-specific configuration amenities to our block. That's as simple as adding one more method to our block class:
function instance_allow_config() {
return true;
}
This small change is enough to make Moodle display an "Edit..." icon in our block's header when we turn editing mode on in any course. However, if you try to click on that icon you will be presented with a notice that complains about the block's configuration not being implemented correctly. Try it, it's harmless.
Moodle's complaints do make sense. We told it that we want to have configuration, but we didn't say ''what'' kind of configuration we want, or how it should be displayed. To do that, we need to create one more file: <span class="filename">/blocks/simplehtml/config_instance.html</span> (which has to be named exactly like that). For the moment, copy paste the following into it and save:
<nowiki>
<table cellpadding="9" cellspacing="0">
<tr valign="top">
<td align="right">
<?php print_string('configcontent', 'block_simplehtml'); ?>:
</td>
<td>
<?php print_textarea(true, 10, 50, 0, 0, 'text', $this->config->text); ?>
</td>
</tr>
<tr>
<td colspan="2" align="center">
<input type="submit" value="<?php print_string('savechanges') ?>" />
</td>
</tr>
</table>
<?php use_html_editor(); ?>
</nowiki>
It isn't difficult to see that the above code just provides us with a wysiwyg-editor-enabled textarea to write our block's desired content in and a submit button to save. But... what's $this->config->text? Well...
Moodle goes a long way to make things easier for block developers. Did you notice that the textarea is actually named "text"? When the submit button is pressed, Moodle saves each and every field it can find in our <span class="filename">config_instance.html</span> file as instance configuration data. We can then access that data as '''$this->config->''variablename''''', where ''variablename'' is the actual name we used for our field; in this case, "text". So in essence, the above form just pre-populates the textarea with the current content of the block (as indeed it should) and then allows us to change it.
You also might be surprised by the presence of a submit button and the absence of any <form> element at the same time. But the truth is, we don't need to worry about that at all; Moodle goes a really long way to make things easier for developers! We just print the configuration options we want, in any format we want; include a submit button, and Moodle will handle all the rest itself. The instance configuration variables are automatically at our disposal to access from any of the class methods ''except'' [[Blocks_Howto#method_init| init]].
In the event where the default behavior is not satisfactory, we can still override it. However, this requires advanced modifications to our block class and will not be covered here; refer to [[Blocks_Howto#appendix_a| Appendix A]] for more details.
Having now the ability to refer to this instance configuration data through [[Blocks_Howto#variable_config| $this->config]], the final twist is to tell our block to actually ''display'' what is saved in is configuration data. To do that, find this snippet in <span class="filename">/blocks/simplehtml/block_simplehtml.php</span><nowiki>:</nowiki>

$this->content = new stdClass;
$this->content->text = 'The content of our SimpleHTML block!';
$this->content->footer = 'Footer here...';
and change it to:

$this->content = new stdClass;
$this->content->text = $this->config->text;
$this->content->footer = 'Footer here...';
Oh, and since the footer isn't really exciting at this point, we remove it from our block because it doesn't contribute anything. We could just as easily have decided to make the footer configurable in the above way, too. So for our latest code, the snippet becomes:
<nowiki>
$this->content = new stdClass;
$this->content->text = $this->config->text;
$this->content->footer = '';</nowiki>
After this discussion, our block is ready for prime time! Indeed, if you now visit any course with a SimpleHTML block, you will see that modifying its contents is now a snap.

== The Specialists ==
Implementing instance configuration for the block's contents was good enough to whet our appetite, but who wants to stop there? Why not customize the block's title, too?
Why not, indeed. Well, our first attempt to achieve this is natural enough: let's add another field to <span class="filename">/blocks/simplehtml/config_instance.html</span>. Here goes:
<nowiki>
<tr valign="top">
<td align="right"><p><?php print_string('configtitle', 'block_simplehtml'); ?>:</p></td>
<td><input type="text" name="title" size="30" value="<?php echo $this->config->title; ?>" /></td>
</tr>
</nowiki>
We save the edited file, go to a course, edit the title of the block and... nothing happens! The instance configuration is saved correctly, all right (editing it once more proves that) but it's not being displayed. All we get is just the simple "SimpleHTML" title.
That's not too wierd, if we think back a bit. Do you remember that [[Blocks_Howto#method_init| init]] method, where we set [[Blocks_Howto#variable_title| $this->title]]? We didn't actually change its value from then, and [[Blocks_Howto#variable_title| $this->title]] is definitely not the same as $this->config->title (to Moodle, at least). What we need is a way to update [[Blocks_Howto#variable_title| $this->title]] with the value in the instance configuration. But as we said a bit earlier, we can use [[Blocks_Howto#variable_config| $this->config]] in all methods ''except'' [[Blocks_Howto#method_init| init]]<nowiki>! So what can we do?</nowiki>
Let's pull out another ace from our sleeve, and add this small method to our block class:

function specialization() {
if(!empty($this->config->title)){
$this->title = $this->config->title;
}
else{
$this->config->title = ''''''';
}
if(empty($this->config->text)){
$this->config->text = ''''''';
}
}
Aha, here's what we wanted to do all along! But what's going on with the [[Blocks_Howto#method_specialization| specialization]] method?
This "magic" method has actually a very nice property: it's ''guaranteed'' to be automatically called by Moodle as soon as our instance configuration is loaded and available (that is, immediately after [[Blocks_Howto#method_init| init]] is called). That means before the block's content is computed for the first time, and indeed before ''anything'' else is done with the block. Thus, providing a [[Blocks_Howto#method_specialization| specialization]] method is the natural choice for any configuration data that needs to be acted upon "as soon as possible", as in this case.

== Now You See Me, Now You Don't ==
Now would be a good time to mention another nifty technique that can be used in blocks, and which comes in handy quite often. Specifically, it may be the case that our block will have something interesting to display some of the time; but in some other cases, it won't have anything useful to say. (An example here would be the "Recent Activity" block, in the case where no recent activity in fact exists. However in that case the block chooses to explicitly inform you of the lack of said activity, which is arguably useful). It would be nice, then, to be able to have our block "disappear" if it's not needed to display it.
This is indeed possible, and the way to do it is to make sure that after the [[Blocks_Howto#method_get_content| get_content]]<nowiki> method is called, the block is completely void of content. Specifically, "void of content" means that both $this->content->text and $this->content->footer are each equal to the empty string (''). Moodle performs this check by calling the block's </nowiki>[[Blocks_Howto#method_is_empty| is_empty()]] method, and if the block is indeed empty then it is not displayed at all.
Note that the exact value of the block's title and the presence or absence of a [[Blocks_Howto#method_hide_header| hide_header]] method do ''not'' affect this behavior. A block is considered empty if it has no content, irrespective of anything else.
== We Are Legion ==
Right now our block is fully configurable, both in title and content. It's so versatile, in fact, that we could make pretty much anything out of it. It would be really nice to be able to add multiple blocks of this type to a single course. And, as you might have guessed, doing that is as simple as adding another small method to our block class:

function instance_allow_multiple() {
return true;
}
This tells Moodle that it should allow any number of instances of the SimpleHTML block in any course. After saving the changes to our file, Moodle immediately allows us to add multiple copies of the block without further ado!
There are a couple more of interesting points to note here. First of all, even if a block itself allows multiple instances in the same page, the administrator still has the option of disallowing such behavior. This setting can be set separately for each block from the Administration / Configuration / Blocks page.
And finally, a nice detail is that as soon as we defined an [[Blocks_Howto#method_instance_allow_multiple| instance_allow_multiple]] method, the method [[Blocks_Howto#method_instance_allow_config| instance_allow_config]] that was already defined became obsolete. Moodle assumes that if a block allows multiple instances of itself, those instances will want to be configured (what is the point of same multiple instances in the same page if they are identical?) and thus automatically provides an "Edit" icon. So, we can also remove the whole [[Blocks_Howto#method_instance_allow_config| instance_allow_config]] method now without harm. We had only needed it when multiple instances of the block were not allowed.
== The Effects of Globalization ==
Configuring each block instance with its own personal data is cool enough, but sometimes administrators need some way to "touch" all instances of a specific block at the same time. In the case of our SimpleHTML block, a few settings that would make sense to apply to all instances aren't that hard to come up with. For example, we might want to limit the contents of each block to only so many characters, or we might have a setting that filters HTML out of the block's contents, only allowing pure text in. Granted, such a feature wouldn't win us any awards for naming our block "SimpleHTML" but some tormented administrator somewhere might actually find it useful.
This kind of configuration is called "global configuration" and applies only to a specific block type (all instances of that block type are affected, however). Implementing such configuration for our block is quite similar to implementing the instance configuration. We will now see how to implement the second example, having a setting that only allows text and not HTML in the block's contents.
First of all, we need to tell Moodle that we want our block to provide global configuration by, what a surprise, adding a small method to our block class:

function has_config() {
return true;
}
Then, we need to create a HTML file that actually prints out the configuration screen. In our case, we 'll just print out a checkbox saying "Do not allow HTML in the content" and a "submit" button. Let's create the file <span class="filename">/blocks/simplehtml/config_global.html</span> which again must be named just so, and copy paste the following into it:

<pre>
<div style="text-align: center;">
<input type="hidden" name="block_simplehtml_strict" value="0" />
<input type="checkbox" name="block_simplehtml_strict" value="1"
<?php if(!empty($CFG->block_simplehtml_strict)) echo 'checked="checked"'; ?> />
<?php print_string('donotallowhtml', 'block_simplehtml'); ?>
<p><input type="submit" value="<?php print_string('savechanges'); ?>" /></p>
</div>
</pre>

True to our block's name, this looks simple enough. What it does is that it displays a checkbox named "block_simplehtml_strict" and if the Moodle configuration variable with the same name (i.e., $CFG->block_simplehtml_strict) is set and not empty (that means it's not equal to an empty string, to zero, or to boolean false) it displays the box as pre-checked (reflecting the current status). Why does it check the configuration setting with the same name? Because the default implementation of the global configuration saving code takes all the variables we have in our form and saves them as Moodle configuration options with the same name. Thus, it's good practice to use a descriptive name and also one that won't possibly conflict with the name of another setting. "block_simplehtml_strict" clearly satisfies both requirements.
The astute reader may have noticed that we actually have ''two'' input fields named "block_simplehtml_strict" in our configuration file. One is hidden and its value is always 0; the other is the checkbox and its value is 1. What gives? Why have them both there?
Actually, this is a small trick we use to make our job as simple as possible. HTML forms work this way: if a checkbox in a form is not checked, its name does not appear at all in the variables passed to PHP when the form is submitted. That effectively means that, when we uncheck the box and click submit, the variable is not passed to PHP at all. Thus, PHP does not know to update its value to "0", and our "strict" setting cannot be turned off at all once we turn it on for the first time. Not the behavior we want, surely.
However, when PHP handles received variables from a form, the variables are processed in the order in which they appear in the form. If a variable comes up having the same name with an already-processed variable, the new value overwrites the old one. Taking advantage of this, our logic runs as follows: the variable "block_simplehtml_strict" is first unconditionally set to "0". Then, ''if'' the box is checked, it is set to "1", overwriting the previous value as discussed. The net result is that our configuration setting behaves as it should.
To round our bag of tricks up, notice that the use of if(!empty($CFG->block_simplehtml_strict)) in the test for "should the box be checked by default?" is quite deliberate. The first time this script runs, the variable $CFG->block_simplehtml_strict will not exist at all. After it's set for the first time, its value can be either "0" or "1". Given that both "not set" and the string "0" evaluate as empty while the sting "1" does not, we manage to avoid any warnings from PHP regarding the variable not being set at all, ''and'' have a nice human-readable representation for its two possible values ("0" and "1").
Now that we have managed to cram a respectable amount of tricks into a few lines of HTML, we might as well discuss the alternative in case that tricks are not enough for a specific configuration setup we have in mind. Saving the data is done in the method [[Blocks_Howto#method_config_save| config_save]], the default implementation of which is as follows:

function config_save($data) {
// Default behavior: save all variables as $CFG properties
foreach ($data as $name => $value) {
set_config($name, $value);
}
return true;
}
As can be clearly seen, Moodle passes this method an associative array $data which contains all the variables coming in from our configuration screen. If we wanted to do the job without the "hidden variable with the same name" trick we used above, one way to do it would be by overriding this method with the following:

function config_save($data) {
if(isset($data['block_simplehtml_strict'])) {
set_config('block_simplehtml_strict', '1');
}
else {
set_config('block_simplehtml_strict', '0');
}
return true;
}
Quite straightfoward: if the variable "block_simplehtml_strict" is passed to us, then it can only mean that the user has checked it, so set the configuration variable with the same name to "1". Otherwise, set it to "0". Of course, this version would need to be updated if we add more configuration options because it doesn't respond to them as the default implementation does. Still, it's useful to know how we can override the default implementation if it does not fit our needs (for example, we might not want to save the variable as part of the Moodle configuration but do something else with it).
So, we are now at the point where we know if the block should allow HTML tags in its content or not. How do we get the block to actually respect that setting?
We could decide to do one of two things: either have the block "clean" HTML out from the input before saving it in the instance configuration and then display it as-is (the "eager" approach); or have it save the data "as is" and then clean it up each time just before displaying it (the "lazy" approach). The eager approach involves doing work once when saving the configuration; the lazy approach means doing work each time the block is displayed and thus it promises to be worse performance-wise. We shall hence go with the eager approach.
Much as we did just before with overriding [[Blocks_Howto#method_config_save| config_save]], what is needed here is overriding the method [[Blocks_Howto#method_instance_config_save| instance_config_save]] which handles the instance configuration. The default implementation is as follows:

function instance_config_save($data) {
$data = stripslashes_recursive($data);
$this->config = $data;
return set_field('block_instance', 'configdata', base64_encode(serialize($data)),
'id', $this->instance->id);
}
This may look intimidating at first (what's all this stripslashes_recursive() and base64_encode() and serialize() stuff?) but do not despair; we won't have to touch any of it. We will only add some extra validation code in the beginning and then instruct Moodle to additionally call this default implementation to do the actual storing of the data. Specifically, we will add a method to our class which goes like this:

function instance_config_save($data) {
// Clean the data if we have to
global $CFG;
if(!empty($CFG->block_simplehtml_strict)) {
$data->text = strip_tags($data->text);
}

// And now forward to the default implementation defined in the parent class
return parent::instance_config_save($data);
}
At last! Now the administrator has absolute power of life and death over what type of content is allowed in our "SimpleHTML" block! Absolute? Well... not exactly. In fact, if we think about it for a while, it will become apparent that if at some point in time HTML is allowed and some blocks have saved their content with HTML included, and afterwards the administrator changes the setting to "off", this will only prevent subsequent content changes from including HTML. Blocks which already had HTML in their content would continue to display it!
Following that train of thought, the next stop is realizing that we wouldn't have this problem if we had chosen the lazy approach a while back, because in that case we would "sanitize" each block's content just before it was displayed. The only thing we can do with the eager approach is strip all the tags from the content of all SimpleHTML instances as soon as the admin setting is changed to "HTML off"; but even then, turning the setting back to "HTML on" won't bring back the tags we stripped away. On the other hand, the lazy approach might be slower, but it's more versatile; we can choose whether to strip or keep the HTML before displaying the content, and we won't lose it at all if the admin toggles the setting off and on again. Isn't the life of a developer simple and wonderful?
We will let this part of the tutorial come to a close with the obligatory excercise for the reader: in order to have the SimpleHTML block work "correctly", find out how to strengthen the eager approach to strip out all tags from the existing configuration of all instances of our block, '''or''' go back and implement the lazy approach instead. (Hint: do that in the [[Blocks_Howto#method_get_content| get_content]] method)
'''UPDATING'''<nowiki>: Prior to version 1.5, the file </nowiki><span class="filename">config_global.html</span> was named simply <span class="filename">config.html</span>. Also, the methods [[Blocks_Howto#method_config_save| config_save]] and [[Blocks_Howto#method_config_print| config_print]] were named '''handle_config''' and '''print_config''' respectively. Upgrading a block to work with Moodle 1.5 involves updating these aspects; refer to [[Blocks_Howto#appendix_b| Appendix B]] for more information.

== Eye Candy ==
Our block is just about complete functionally, so now let's take a look at some of the tricks we can use to make its behavior customized in a few more useful ways.
First of all, there are a couple of ways we can adjust the visual aspects of our block. For starters, it might be useful to create a block that doesn't display a header (title) at all. You can see this effect in action in the Course Description block that comes with Moodle. This behavior is achieved by, you guessed it, adding one more method to our block class:

function hide_header() {
return true;
}
One more note here: we cannot just set an empty title inside the block's [[Blocks_Howto#method_init| init]] method; it's necessary for each block to have a unique, non-empty title after [[Blocks_Howto#method_init| init]] is called so that Moodle can use those titles to differentiate between all of the installed blocks.
Another adjustment we might want to do is instruct our block to take up a certain amount of width on screen. Moodle handles this as a two-part process: first, it queries each block about its preferred width and takes the maximum number as the desired value. Then, the page that's being displayed can choose to use this value or, more probably, bring it within some specific range of values if it isn't already. That means that the width setting is a best-effort settlement; your block can ''request'' a certain width and Moodle will ''try'' to provide it, but there's no guarantee whatsoever about the end result. As a concrete example, all standard Moodle course formats will deliver any requested width between 180 and 210 pixels, inclusive.
To instruct Moodle about our block's preferred width, we add one more method to the block class:

function preferred_width() {
// The preferred value is in pixels
return 200;
}
This will make our block (and all the other blocks displayed at the same side of the page) a bit wider than standard.
Finally, we can also affect some properties of the actual HTML that will be used to print our block. Each block is fully contained within a <table> element, inside which all the HTML for that block is printed. We can instruct Moodle to add HTML attributes with specific values to that container. This would be done to either a) directly affect the end result (if we say, assign bgcolor="black"), or b) give us freedom to customize the end result using CSS (this is in fact done by default as we 'll see below).
The default behavior of this feature in our case will assign to our block's container the class HTML attribute with the value "sideblock block_simplehtml" (the prefix "block_" followed by the name of our block, lowercased). We can then use that class to make CSS selectors in our theme to alter this block's visual style (for example, ".sideblock.block_simplehtml { border: 1px black solid}").
To change the default behavior, we will need to define a method which returns an associative array of attribute names and values. For example, the version

function html_attributes() {
return array(
'class' => 'sideblock block_'. $this->name(),
'onmouseover' => "alert('Mouseover on our block!');"
);
}
will result in a mouseover event being added to our block using JavaScript, just as if we had written the onmouseover="alert(...)" part ourselves in HTML. Note that we actually duplicate the part which sets the class attribute (we want to keep that, and since we override the default behavior it's our responsibility to emulate it if required). And the final elegant touch is that we don't set the class to the hard-coded value "block_simplehtml" but instead use the [[Blocks_Howto#method_name| name]] method to make it dynamically match our block's name.

== Authorized Personnel Only ==
It's not difficult to imagine a block which is very useful in some circumstances but it simply cannot be made meaningful in others. An example of this would be the "Social Activities" block which is indeed useful in a course with the social format, but doesn't do anything useful in a course with the weeks format. There should be some way of allowing the use of such blocks only where they are indeed meaningful, and not letting them confuse users if they are not.
Moodle allows us to declare which course formats each block is allowed to be displayed in, and enforces these restrictions as set by the block developers at all times. The information is given to Moodle as a standard associative array, with each key corresponding to a page format and defining a boolean value (true/false) that declares whether the block should be allowed to appear in that page format.
Notice the deliberate use of the term ''page'' instead of ''course'' in the above paragraph. This is because in Moodle 1.5 and onwards, blocks can be displayed in any page that supports them. The best example of such pages are the course pages, but we are not restricted to them. For instance, the quiz view page (the first one we see when we click on the name of the quiz) also supports blocks.
The format names we can use for the pages derive from the name of the script which is actually used to display that page. For example, when we are looking at a course, the script is <span class="filename">/course/view.php</span> (this is evident from the browser's address line). Thus, the format name of that page is '''course-view'''. It follows easily that the format name for a quiz view page is '''mod-quiz-view'''. This rule of thumb does have a few exceptions, however:
#* The format name for the front page of Moodle is '''site-index'''.
#* The format name for courses is actually not just '''course-view'''<nowiki>; it is </nowiki>'''course-view-weeks''', '''course-view-topics''', etc.
#* Even though there is no such page, the format name '''all''' can be used as a catch-all option.
We can include as many format names as we want in our definition of the applicable formats. Each format can be allowed or disallowed, and there are also three more rules that help resolve the question "is this block allowed into this page or not?":
#* Prefixes of a format name will match that format name; for example, '''mod''' will match all the activity modules. '''course-view''' will match any course, regardless of the course format. And finally, '''site''' will also match the front page (remember that its full format name is '''site-index''').
#* The more specialized a format name that matches our page is, the higher precedence it has when deciding if the block will be allowed. For example, '''mod''', '''mod-quiz''' and '''mod-quiz-view''' all match the quiz view page. But if all three are present, '''mod-quiz-view''' will take precedence over the other two because it is a better match.
#* The character '''<nowiki>*</nowiki>''' can be used in place of any word. For example, '''mod''' and '''mod-*''' are equivalent. At the time of this document's writing, there is no actual reason to utilize this "wildcard matching" feature, but it exists for future usage.
#* The order that the format names appear does not make any difference.
All of the above are enough to make the situation sound complex, so let's look at some specific examples. First of all, to have our block appear '''only''' in the site front page, we would use:

function applicable_formats() {
return array('site' => true);
}
Since '''all''' is missing, the block is disallowed from appearing in ''any'' course format; but then '''site''' is set to true, so it's explicitly allowed to appear in the site front page (remember that '''site''' matches '''site-index''' because it's a prefix).
For another example, if we wanted to allow the block to appear in all course formats ''except'' social, and also to ''not'' be allowed anywhere but in courses, we would use:

function applicable_formats() {
return array('course-view' => true, 'course-view-social' => false);
}
This time, we first allow the block to appear in all courses and then we explicitly disallow the social format.
For our final, most complicated example, suppose that a block can be displayed in the site front page, in courses (but not social courses) and also when we are viewing any activity module, ''except'' quiz. This would be:

function applicable_formats() {
return array('site-index' => true,
'course-view' => true, 'course-view-social' => false,
'mod' => true, 'mod-quiz' => false);
}
It is not difficult to realize that the above accomplishes the objective if we remember that there is a "best match" policy to determine the end result.
'''UPDATING:''' Prior to version 1.5, blocks were only allowed in courses (and in Moodle 1.4, in the site front page). Also, the keywords used to describe the valid course formats at the time were slightly different and had to be changed in order to allow for a more open architecture. Refer to [[Blocks_Howto#appendix_b| Appendix B]] for more information on the changes that old blocks have to make to conform to the new standard.
== Lists and Icons ==
In this final part of the guide we will briefly discuss an additional capability of Moodle's block system, namely the ability to very easily create blocks that display a list of choices to the user. This list is displayed with one item per line, and an optional image (icon) next to the item. An example of such a ''list block'' is the standard Moodle "admin" block, which illustrates all the points discussed in this section.
As we have seen so far, blocks use two properties of [[Blocks_Howto#variable_content| $this->content]]<nowiki>: "text" and "footer". The text is displayed as-is as the block content, and the footer is displayed below the content in a smaller font size. List blocks use $this->content->footer in the exact same way, but they ignore $this->content->text.</nowiki>
Instead, Moodle expects such blocks to set two other properties when the [[Blocks_Howto#method_get_content| get_content]] method is called: $this->content->items and $this->content->icons. $this->content->items should be a numerically indexed array containing elements that represent the HTML for each item in the list that is going to be displayed. Usually these items will be HTML anchor tags which provide links to some page. $this->content->icons should also be a numerically indexed array, with exactly as many items as $this->content->items has. Each of these items should be a fully qualified HTML <img> tag, with "src", "height", "width" and "alt" attributes. Obviously, it makes sense to keep the images small and of a uniform size.
In order to tell Moodle that we want to have a list block instead of the standard text block, we need to make a small change to our block class declaration. Instead of extending class '''block_base''', our block will extend class '''block_list'''. For example:

class block_my_menu extends block_list {
// The init() method does not need to change at all
}
In addition to making this change, we must of course also modify the [[Blocks_Howto#method_get_content| get_content]] method to construct the [[Blocks_Howto#variable_content| $this->content]] variable as discussed above:

function get_content() {
if ($this->content !== NULL) {
return $this->content;
}

$this->content = new stdClass;
$this->content->items = array();
$this->content->icons = array();
$this->content->footer = 'Footer here...';

$this->content->items[] = '<a href="some_file.php">Menu Option 1</a>';
$this->content->icons[] = '<img src="images/icons/1.gif" class="icon" alt="" />';

// Add more list items here

return $this->content;
}
To summarize, if we want to create a list block instead of a text block, we just need to change the block class declaration and the [[Blocks_Howto#method_get_content| get_content]] method. Adding the mandatory [[Blocks_Howto#method_init| init]] method as discussed earlier will then give us our first list block in no time!

== 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.

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: ===
** <div class="function_title">after_install</div>
<nowiki>
function after_install() {
}
</nowiki>
Available in Moodle 1.7 and later

This method is designed to be overridden by block subclasses, and allows you to specify a set of tasks to be executed after the block is installed. For example, you may wish to store the date on which the block was installed. However, each database type has its own way of getting the current date, and when using XMLDB to install your block, these operations are also unsupported. So the best way to complete such a task while maintaining database abstraction is to use XMLDB to install the block, and then use the after_install() method to perform the insertion before the block is used.

Please note that after_install() is called once per block, not once per instance.

** <div class="function_title">applicable_formats</div>
<nowiki>
function applicable_formats() {
// Default case: the block can be used in courses and site index, but not in activities
return array('all' => true, 'mod' => false);
}
</nowiki>
Available in Moodle 1.5 and later

This method allows you to control which pages your block can be added to. Page formats are formulated from the full path of the script that is used to display that page. You should return an array with the keys being page format names and the values being booleans (true or false). Your block is only allowed to appear in those formats where the value is true.
Example format names are: '''course-view''', '''site-index''' (this is an exception, referring front page of the Moodle site), '''course-format-weeks''' (referring to a specific course format), '''mod-quiz''' (referring to the quiz module) and '''all''' (this will be used for those formats you have not explicitly allowed or disallowed).
The full matching rules are:
*** Prefixes of a format name will match that format name; for example, '''mod''' will match all the activity modules. '''course-view''' will match any course, regardless of the course format. And finally, '''site''' will also match the front page (remember that its full format name is '''site-index''').
*** The more specialized a format name that matches our page is, the higher precedence it has when deciding if the block will be allowed. For example, '''mod''', '''mod-quiz''' and '''mod-quiz-view''' all match the quiz view page. But if all three are present, '''mod-quiz-view''' will take precedence over the other two because it is a better match.
*** The character '''<nowiki>*</nowiki>''' can be used in place of any word. For example, '''mod''' and '''mod-*''' are equivalent. At the time of this document's writing, there is no actual reason to utilize this "wildcard matching" feature, but it exists for future usage.
*** The order that the format names appear does not make any difference.

** <div class="function_title">before_delete</div>

<nowiki>
function before_delete() {
}
</nowiki>
Available in Moodle 1.7 and later

This method is called when an administrator removes a block from the Moodle installation, immediately before the relevant database tables are deleted. It allows block authors to perform any necessary cleanup - removing temporary files and so on - before the block is deleted.

** <div class="function_title">config_print</div>
<nowiki>
function config_print() {
// Default behavior: print the config_global.html file
// You don't need to override this if you're satisfied with the above
if (!$this->has_config()) {
return false;
}
global $CFG, $THEME;
print_simple_box_start('center', '', $THEME->cellheading);
include($CFG->dirroot.'/blocks/'. $this->name() .'/config_global.html');
print_simple_box_end();
return true;
}</nowiki>
Available in Moodle 1.5 and later

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:
**# If you save your configuration options in $CFG, you will probably need to use global $CFG; before including any HTML configuration screens.
**# 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.
** <div class="function_title">config_save</div>

function config_save($data) {
// Default behavior: save all variables as $CFG properties
// You don't need to override this if you 're satisfied with the above
foreach ($data as $name => $value) {
set_config($name, $value);
}
return true;
}
Available in Moodle 1.5 and later

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 $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.
** <div class="function_title">get_content</div>

function get_content() {
// This should be implemented by the derived class.
return NULL;
}
Available in Moodle 1.5 and later

This method should, when called, populate the [[Blocks_Howto#variable_content| $this->content]] variable of your block. Populating the variable means:
'''EITHER'''<br />defining $this->content->text and $this->content->footer if your block derives from '''block_base'''. Both of these should be strings, and can contain arbitrary HTML.
'''OR'''<br />defining $this->content->items, $this->content->icons and $this->content->footer if your block derives from '''block_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 hide itself to unclutter the screen if there is no reason to have it displayed.
Before starting to populate [[Blocks_Howto#variable_content| $this->content]], you should also include a simple caching check. If [[Blocks_Howto#variable_content| $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 [[Blocks_Howto#variable_content| $this->content]] variable.
** <div class="function_title">has_config</div>

function has_config() {
return false;
}
Available in Moodle 1.5 and later

This method should return a boolean value that denotes whether your block wants to present a configuration interface to site admins or not. The configuration that this interface offers will impact all instances of the block equally.
To actually implement the configuration interface, you will either need to rely on the default [[Blocks_Howto#method_instance_config_print| config_print]] method or override it. The full guide contains [[Blocks_Howto#section_effects_of_globalization| more information on this]].
** <div class="function_title">hide_header</div>

function hide_header() {
//Default, false--> the header is shown
return false;
}
Available in Moodle 1.5 and later

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.
** <div class="function_title">html_attributes</div>

function html_attributes() {
// Default case: an id with the instance and a class with our name in it
return array('id' => 'inst'.$this->instance->id, 'class' => 'block_'. $this->name());
}
Available in Moodle 1.5 and later

This method should return an associative array of HTML attributes that will be given to your block's container element when Moodle constructs the output HTML. No sanitization will be performed in these elements at all.
If you intend to override this method, you should return the default attributes as well as those you add yourself. The recommended way to do this is:

function html_attributes() {
$attrs = parent::html_attributes();
// Add your own attributes here, e.g.
// $attrs['width'] = '50%';
return $attrs;
}
** <div class="function_title">init</div>

function init() {
$this->title = get_string('simplehtml', 'block_simplehtml');
$this->version = 2004111200;
}
Available in Moodle 1.5 and later

This method must be implemented for all blocks. It has to assign meaningful values to the object variables [[Blocks_Howto#variable_title| $this->title]] and [[Blocks_Howto#variable_version| $this->version]] (which is used by Moodle for performing automatic updates when available).
No return value is expected from this method.
** <div class="function_title">instance_allow_config</div>

function instance_allow_config() {
return false;
}
Available in Moodle 1.5 and later

This method should return a boolean value. True indicates that your block wants to have per-instance configuration, while false means it does not. If you do want to implement instance configuration, you will need to take some additional steps apart from overriding this method; refer to the full guide for [[Blocks_Howto#section_configure_that_out| more information]].
This method's return value is irrelevant if [[Blocks_Howto#method_instance_allow_multiple| instance_allow_multiple]] returns true; it is assumed that if you want multiple instances then each instance needs its own configuration.
** <div class="function_title">instance_allow_multiple</div>

function instance_allow_multiple() {
// Are you going to allow multiple instances of each block?
// If yes, then it is assumed that the block WILL USE per-instance configuration
return false;
}
Available in Moodle 1.5 and later

This method should return a boolean value, indicating whether you want to allow multiple instances of this block in the same page or not. If you do allow multiple instances, it is assumed that you will also be providing per-instance configuration for the block. Thus, you will need to take some additional steps apart from overriding this method; refer to the full guide for [[Blocks_Howto#section_configure_that_out| more information]].
** <div class="function_title">instance_config_print</div>
<nowiki>
function instance_config_print() {
// Default behavior: print the config_instance.html file
// You don't need to override this if you're satisfied with the above
if (!$this->instance_allow_multiple() && !$this->instance_allow_config()) {
return false;
}
global $CFG, $THEME;

if (is_file($CFG->dirroot .'/blocks/'. $this->name() .'/config_instance.html')) {
print_simple_box_start('center', '', $THEME->cellheading);
include($CFG->dirroot .'/blocks/'. $this->name() .'/config_instance.html');
print_simple_box_end();
} else {
notice(get_string('blockconfigbad'),
str_replace('blockaction=', 'dummy=', qualified_me()));
}

return true;
}</nowiki>
Available in Moodle 1.5 and later

This method allows you to choose how to display the instance configuration screen for your block. Override it if you need something much more complex than the default implementation allows you to do. Keep in mind that whatever you do output from [[Blocks_Howto#method_instance_config_print| config_print]], it will be enclosed in a HTML form automatically. You only need to provide a way to submit that form.
You should return a boolean value denoting the success or failure of your method's actions.
** <div class="function_title">instance_config_save</div>

function instance_config_save($data) {
$data = stripslashes_recursive($data);
$this->config = $data;
return set_field('block_instance', 'configdata', base64_encode(serialize($data)),
'id', $this->instance->id);
}
Available in Moodle 1.5 and later

This method allows you to override the storage mechanism for your instance configuration data. The received argument is an associative array, with the keys being setting names and the values being setting values.
The configuration must be stored in the "configdata" field of your instance record in the database so that Moodle can auto-load it when your block is constructed. However, you may still want to override this method if you need to take some additional action apart from saving the data. In that case, you really should do what data processing you want and then call parent::instance_config_save($data) with your new $data array. This will keep your block from becoming broken if the default implementation of instance_config_save changes in the future.
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.
If you want to update the stored copy of the configuration data at run time (for example to persist some changes you made programmatically), you should not use this method. The correct procedure for that purpose is to call [[Blocks_Howto#method_instance_config_commit| instance_config_commit]].
You should return a boolean value denoting the success or failure of your method's actions.
** <div class="function_title">preferred_width</div>

function preferred_width() {
// Default case: the block wants to be 180 pixels wide
return 180;
}
Available in Moodle 1.5 and later

This method should return an integer value, which is the number of pixels of width your block wants to take up when displayed. Moodle will try to honor your request, but this is actually up to the implementation of the format of the page your block is being displayed in and therefore no guarantee is given. You might get exactly what you want or any other width the format decides to give you, although obviously an effort to accomodate your block will be made.
Most display logic at this point allocates the maximum width requested by the blocks that are going to be displayed, bounding it both downwards and upwards to avoid having a bad-behaving block break the format.
** <div class="function_title">refresh_content</div>

function refresh_content() {
// Nothing special here, depends on content()
$this->content = NULL;
return $this->get_content();
}
Available in Moodle 1.5 and later

This method should cause your block to recalculate its content immediately. If you follow the guidelines for [[Blocks_Howto#get_content| get_content]], which say to respect the current content value unless it is NULL, then the default implementation will do the job just fine.
You should return the new value of [[Blocks_Howto#variable_content| $this->content]] after refreshing it.
** <div class="function_title">specialization</div>

function specialization() {
// Just to make sure that this method exists.
}
Available in Moodle 1.5 and later

This method is automatically called by the framework immediately after your instance data (which includes the page type and id and all instance configuration data) is loaded from the database. If there is some action that you need to take as soon as this data becomes available and which cannot be taken earlier, you should override this method.
The instance data will be available in the variables [[Blocks_Howto#variable_instance| $this->instance]] and [[Blocks_Howto#variable_config| $this->config]].
This method should not return anything at all.
=== Methods which you should ''not'' override but may want to use: ===
** <div class="function_title">instance_config_commit</div>

function instance_config_commit() {
return set_field('block_instance',
'configdata', base64_encode(serialize($this->config)),
'id', $this->instance->id);
}
Available in Moodle 1.5 and later

This method saves the current contents of [[Blocks_Howto#variable_config| $this->config]] to the database. If you need to make a change to the configuration settings of a block instance at run time (and not through the usual avenue of letting the user change it), just make the changes you want to [[Blocks_Howto#variable_config| $this->config]] and then call this method.
** <div class="function_title">get_content_type</div>

function get_content_type() {
return $this->content_type;
}
Available in Moodle 1.5 and later

This method returns the value of [[Blocks_Howto#variable_content_type| $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'''<nowiki>; future library changes may break compatibility with code that does so.</nowiki>
** <div class="function_title">get_title</div>

function get_title() {
return $this->title;
}
Available in Moodle 1.5 and later

This method returns the value of [[Blocks_Howto#variable_title| $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'''<nowiki>; future library changes may break compatibility with code that does so.</nowiki>
** <div class="function_title">get_version</div>

function get_version() {
return $this->version;
}
Available in Moodle 1.5 and later

This method returns the value of [[Blocks_Howto#variable_version| $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'''<nowiki>; future library changes may break compatibility with code that does so.</nowiki>
** <div class="function_title">is_empty</div>
For blocks that extend class '''block_base'''<nowiki>:</nowiki>

function is_empty() {
$this->get_content();
return(empty($this->content->text) && empty($this->content->footer));
}
Available in Moodle 1.5 and later

For blocks that extend class '''block_list'''<nowiki>:</nowiki>

function is_empty() {
$this->get_content();
return (empty($this->content->items) && empty($this->content->footer));
}
This method returns the a boolean true/false value, depending on whether the block has any content at all to display. Blocks without content are not displayed by the framework.
** <div class="function_title">name</div>

function name() {
static $myname;
if ($myname === NULL) {
$myname = strtolower(get_class($this));
$myname = substr($myname, strpos($myname, '_') + 1);
}
return $myname;
}
Available in Moodle 1.5 and later

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 [[Blocks_Howto#method_config_print| config_print]] method.
=== Methods which you should ''not'' override and ''not'' use at all: ===
** <div class="function_title">_self_test</div>
This is a private method; no description is given.
** <div class="function_title">_add_edit_controls</div>
This is a private method; no description is given.
** <div class="function_title">_load_instance</div>
This is a private method; no description is given.
** <div class="function_title">_print_block</div>
This is a private method; no description is given.
** <div class="function_title">_print_shadow</div>
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, 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: ===

* <div class="variable_title">$this->config</div>
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 <span class="filename">config_instance.html</span> file.
The variable is initialized just after the block object is constructed, immediately before [[Blocks_Howto#method_specialization| 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 accessing the configdata field yourself. If you absolutely must update its value at any time, it is recommended that you call the method [[Blocks_Howto#method_instance_config_commit| instance_config_commit]] to do the actual work.
* <div class="variable_title">$this->content_type</div>
This variable instructs Moodle on what type of content it should assume the block has, and is used to differentiate text blocks from list blocks. 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 variable [[Blocks_Howto#variable_content| $this->content]]. The variable is expected to have a valid value after the framework calls the [[Blocks_Howto#method_init| init]] method for each block.
The only valid values for this variable are the two named constants [[Blocks_Howto#constant_block_type_text| BLOCK_TYPE_TEXT]] and [[Blocks_Howto#constant_block_type_list| BLOCK_TYPE_LIST]].
* <div class="variable_title">$this->content</div>
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 [[Blocks_Howto#method_get_content| get_content]] is called.
After it is fully constructed, this object is expected to have certain properties, depending on the value of [[Blocks_Howto#variable_content_type| $this->content_type]]. Specifically:
** If [[Blocks_Howto#variable_content_type| $this->content_type]] is [[Blocks_Howto#constant_block_type_text| BLOCK_TYPE_TEXT]], then [[Blocks_Howto#variable_content| $this->content]] is expected to have the following member variables:
*** <div>'''text'''</div>This is a string of arbitrary length and content. It is displayed inside the main area of the block, and can contain HTML.
*** <div>'''footer'''</div>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 [[Blocks_Howto#variable_content_type| $this->content_type]] is [[Blocks_Howto#constant_block_type_list| BLOCK_TYPE_LIST]], then [[Blocks_Howto#variable_content| $this->content]] is expected to have the following member variables:
*** <div>'''items'''</div>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.
*** <div>'''icons'''</div>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.
*** <div>'''footer'''</div>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.
* <div class="variable_title">$this->instance</div>
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.
* <div class="variable_title">$this->title</div>
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 [[Blocks_Howto#method_init| 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 [[Blocks_Howto#method_init| init]]. This title may then be overridden when the [[Blocks_Howto#method_specialization| 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;
}

A lot of blocks seem to use

$this->title = get_string('blockname', ... );

to set the title of the block (and then put a more specific title inside the language file)
If there is no proper language string, the title of the block will then be set to ''blockname''. If there is another block with the same generic title, then an error will show up: Naming conflict.

To avoid this error on installations with missing language strings, use a more specific name when calling the language string...

$this->title = get_string('simplehtml', ... );

That way all blocks will show up with a unique title in the admin area, even if people have not yet succeeded in placing language files in the correct location

* <div class="variable_title">$this->version</div>
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 [[Blocks_Howto#method_init| 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:

=== Named constants: ===

* <div class="named_constant">BLOCK_TYPE_LIST</div>
This is one of the two valid values for the [[Blocks_Howto#variable_content_type| $this->content_type]] member variable of every block. Its value specifies the exact requirements that Moodle will then have for [[Blocks_Howto#variable_content| $this->content]].
* <div class="named_constant">BLOCK_TYPE_TEXT</div>
This is one of the two valid values for the [[Blocks_Howto#variable_content_type| $this->content_type]] member variable of every block. Its value specifies the exact requirements that Moodle will then have for [[Blocks_Howto#variable_content| $this->content]].

== Appendix B: Differences in the Blocks API for Moodle versions prior to 1.5 ==

This Appendix will discuss what changes in the Blocks API were introduced by Moodle 1.5 and what steps developers need to take to update their blocks to be fully compatible with Moodle 1.5. Unfortunately, with these changes backward compatibility is broken; this means that blocks from Moodle 1.4 will never work with 1.5 and vice versa.

=== Class naming conventions changed ===
In Moodle 1.4, all block classes were required to have a name like '''CourseBlock_something''' and the base class from which the derived was '''MoodleBlock'''. This has changed in Moodle 1.5, to bring the naming conventions in line with other object-oriented aspects of Moodle (for example there are classes enrolment_base, resource_base etc). The new block classes should instead be named like '''block_something''' and derive from '''block_base'''. This means that in order to make a block compatible with Moodle 1.5, you need to change the class definition

class CourseBlock_online_users extends MoodleBlock { ... }
to

class block_online_users extends block_base { ... }
An exception to the above is the special case where the block is intended to display a list of items instead of arbitrary text; in this case the block class must derive from class '''block_list''' instead, like this:

class block_admin extends block_list { ... }

=== Constructor versus init() ===

In Moodle 1.4, in each block class it was mandatory to define a constructor which accepted a course data record as an argument (the example is from the actual Online Users block):

function CourseBlock_online_users ($course) {
$this->title = get_string('blockname','block_online_users');
$this->content_type = BLOCK_TYPE_TEXT;
$this->course = $course;
$this->version = 2004052700;
}
In contrast, Moodle 1.5 does away with the constructor and instead requires you to define an init() method that takes no arguments:

function init() {
$this->title = get_string('blockname','block_online_users');
$this->version = 2004111600;
}
Of course, this leaves you without access to the $course object, which you might actually need. Since that's probably going to be needed inside [[Blocks_Howto#method_get_content| get_content]], the way to retrieve it is by using this code:

$course = get_record('course', 'id', $this->instance->pageid);
If you are going to need access to $course from inside other methods in addition to [[Blocks_Howto#method_get_content| get_content]], you might fetch the $course object inside the [[Blocks_Howto#method_specialization| specialization]] method and save it as a class variable for later use, in order to avoid executing the same query multiple times:

function specialization() {
$this->course = get_record('course', 'id', $this->instance->pageid);
}

=== Blocks with configuration ===
In Moodle 1.4, blocks could only have what are now (in Moodle 1.5) called "global configuration" options, to differentiate from the new "instance configuration" options. If your block has support for configuration, you will need to take these steps:
## Rename your <span class="filename">config.html</span> file to <span class="filename">config_global.html</span>.
## Edit the newly renamed file and completely remove the <form> tag (Moodle now wraps your configuration in a form automatically).
## If you are using any HTML <input> tags other than those that directly affect your configuration (for example, "sesskey"), REMOVE those too (Moodle will add them automatically as required).
## If you have overridden '''print_config''', rename your method to '''config_print'''.
## If you have overridden '''handle_config''', rename your method to '''config_save'''.
=== Blocks with customized applicable formats ===
The correct way to specify the formats you want to allow or disallow your block to exist has been reworked for Moodle 1.5 to take account of the fact that blocks are no longer restricted to just courses. To have a block retain its intended behavior, you must change these format names (array keys in the return value of [[Blocks_Howto#method_applicable_formats| applicable_formats]]) if they are used in your block:
#* '''social''' should become '''course-view-social'''
#* '''topics''' should become '''course-view-topics'''
#* '''weeks''' should become '''course-view-weeks'''
You should also keep in mind that there is now the possibility of blocks being displayed in other pages too, like the introductory page that users see when they enter an activity module. You might therefore need to make the specification for applicable formats more restrictive to keep your block out of pages it is not supposed to be shown in. Also, there are subtle changes to the way that the final decision to allow or disallow a block is made. For the technical details refer to the definition of [[Blocks_Howto#method_applicable_formats| applicable_formats]], and for a more extended example read [[Blocks_Howto#section_authorized_personnel_only| the section dedicated to this subject]].
That's everything; your block will now be ready for use in Moodle 1.5!

[[Category:Developer|Blocks]]

[[es:Desarrollo de bloques]]

== Creating Database Tables for Blocks ==

'''The following describes what to do in Moodle <= 1.6. For Moodle >= 1.7, you need to use [[Development:XMLDB_Documentation|XMLDB]], that is, create an install.xml file, instead of *.sql files.'''

You can easily create a database table for your block by adding
two files mysql.sql and postgres7.sql to a subdirectory db/ of
your block. The tables HAVE TO be named the same way as the
block (e.g. block_rss2_feeds) otherwise moodle will not be able
to drop the table upon removal of the block from the system.
Here is an example for mysql.sql:

CREATE TABLE prefix_rss2_feeds (
`id` int(11) NOT NULL auto_increment,
`userid` int(11) NOT NULL default '0',
`title` text NOT NULL default '',
`description` text NOT NULL default '',
`url` varchar(255) NOT NULL default '',
`pingbacktokenurl` varchar(255) NOT NULL default '',
PRIMARY KEY (`id`)
) TYPE=MyISAM COMMENT='Remote news feed information.';

Pay attention that, furthermore, you might want to add a
mysql.php and postgres7.php page that contains update
routines for upgrading the database tables with evolving
version numbers of the block. In case you use that be sure
that you provide the necessary structure (again function
name should be like the block name + "_upgrade"!).
Here is an example:

function rss_pingback_upgrade( $oldversion ) {
global $CFG;
if ($oldversion < 2003111500) {
# Do something ...
}
return true;
}

Windows installation

2007-09-12T14:40:13Z

Tanthalas: /* Manual Installation */

==Installation Packages==
If you are running a small (less than 30 users) Moodle server or just want to test Moodle on your Windows XP PC, pre-built packages are available for you to use. Here are links to pages containing step-by-step instructions for installing Moodle using install packages:

*[[Complete install packages]] for most Windows versions

*[[Installing_AMP#Windows| This section has a quick]] way to install a complete package on a Windows XP machine

*[[Windows installation using XAMPP|Installation guide for Windows using XAMPP]] in case you want to retrofit

*[[Installation guide for Windows using EasyPHP]]

*[[Installation guide - Moodle for Windows on a USB Memory Stick]]

== Manual Installation ==
For medium to large installations (e.g. a college, university or business), it is best practice to install Moodle on your server manually.

* '''Plan your system capacity'''. This involves estimating the appropriate hardware to support the number of users in your organisation. See [[Installing Moodle]] in the How Many Users section for a method of doing this.
* '''Install your database server'''. You have a choice of [http://dev.mysql.com/downloads/ MySQL] (recommended), [http://www.postgresql.org/download/ PostgreSQL], [[Installing MSSQL for PHP | Microsoft SQL Server 2005]] (only for Moodle 1.7 or later) or Oracle.
* '''Install PHP'''. See [http://www.peterguy.com/php/install_IIS6.html How to install PHP 5.x on Windows Server 2003 with IIS 6] for instructions.
* '''Install your web server'''. You have several choices - the decision as to which one to use will depend on your in-house expertise and your required level of sustainability:
**Apache 2 is recommended as the most tested and popular for Moodle installations. See these instructions for [[Installing Apache on Windows |manually installing Apache 2 on Windows]].
**IIS 6 can also be used. See the Windows forum for guidance on installation and, in particular, permission settings for using Moodle with IIS.
**Other webservers are known to install on Windows, e.g. Lighttpd, so you may wish to experiment with these if available memory is low on your server.
* '''Install Moodle''' by getting the standard installation for Moodle from [http://download.moodle.org/ http://download.moodle.org/] and read [[Installing Moodle]] which has detailed generic information.
* '''Setup backups'''. Once Moodle is setup and configured, you should setup backups of the system in case of failure or loss of data.
** '''To perform full site backups''' you need to backup the moodledata and moodle directories, Apache webserver configuration (httpd.conf) if you're using Apache, PHP configuration (php.ini) and any php extensions which are non-standard, and the mysql database. To do this use the integrated backup program (Start -> All Programs -> Accessories -> System Tools -> Backup) or your own proprietary backup software (e.g. BackupExec). To backup your mysql database see the [[Backup FAQ]].
** '''To perform course backups''' see the [[Course backup]] page.
** You should also perform a '''state backup''' of the [http://technet2.microsoft.com/WindowsServer/en/library/921f0ed5-523d-48ac-8825-e850b0e548841033.mspx?mfr=true server] or [http://www.microsoft.com/resources/documentation/windows/xp/all/proddocs/en-us/ntbackup_backup_sysstate.mspx?mfr=true PC]. This is especially important if you're using IIS as this will backup the IIS metabase.
* '''Check your server security and performance'''. It is also good practice to read the [[Performance]] and [[Security]] documentation. Although much of the content is targetted at Linux/Unix users, there is a growing amount for Windows systems.
* Set-up your '''Active Directory authentication'''. You can use the standard [[LDAP authentication]] which prompts users with a username/password, or [[NTLM authentication | integrated NTLM authentication]] which does not require campus users to enter their credentials.

== See also ==

* [http://moodle.org/mod/forum/view.php?id=6799 Windows-based server forum] is the main forum for asking questions about your Moodle Windows installation.
* [[Installing APC in Windows]] contains instructions for using a PHP accelerator to reduce processor load.
* [[Cron | Installing Cron on Windows]] for setting up the Moodle scheduled task.
* [[Configuring aspell on Windows 2003 Server]] for setting up the Moodle spell checker.
* [http://moodle.org/mod/forum/discuss.php?d=56835 Running Apache and IIS on the same server] forum discussion.
* [http://moodle.org/blog/index.php?userid=212926&courseid=55 A Windows installation log.]

[[Category:Administrator]]
[[Category:Installation]]

Installing MSSQL for PHP

2007-09-11T11:28:58Z

Tanthalas: /* Using FreeTDS on Windows */

{{Moodle 1.7}}
== Introduction ==

This short manual is suitable if you are trying to run Moodle 1.7 (and upwards) using the SQL*Server (MSSQL) RDBMS. Steps detailed below must be performed '''before''' installing Moodle itself.

First of all, minimum required version of MSSQL has been stabilised to MSSQL 2005 (v.9), although it '''might work with MSSQL 2000 (v.8) or newer'''. All the development process has been performed using MSSQL 2005 and there could be some '''unknown problems''' with previous releases.

While PHP comes with one, more or less, standard extension (mssql) that provides access to MSSQL databases, early we found some hard limits on it. Basically such default extension has some limits that prevent us to use it at all (you can find more info about this problems [[Development:XMLDB problems#MSSQL, PHP, UTF-8 and UCS-2|here]].

So, in order to allow PHP (i.e. Moodle) to access to MSSQL DBs properly we have to install a '''mssql extension alternative''' to save us from the problems related above. See the sections below for details about the various options.

== Installation overview ==

1. Get MSSQL Server installed and running.
:Make sure that you choose mixed authentication (Windows and local accounts) to keep things simpler later. You'll be asked to define the "sa" account password (it's the default System Administrator account which has full access to all databases by default).

2. Make sure MS SQL Server can accept incoming TCP/IP connections on port 1433 (the standard one).
:You might need to explicitly allow this in your Windows firewall (see the Control Panel). You may also need to edit options in the :'''SQL Server Configuration Manager''' -> '''Network Configuration''' -> '''Protocols''' -> '''TCP/IP enabled'''

3. Open the "SQL Server Management Studio" and create a new empty database. If you are using the "sa" account then you don't need to do anything else here.

4. Configure these settings in your created (and still empty) database:

:* ANSI NULLS Enabled = true
:* Quoted Identifiers Enabled = true

5. Get PHP installed with a web server. Unless you want to do it under IIS or some other way, the packages on the [http://download.moodle.org Moodle download page] are a good solution.

6. Choose one of the following specific sections for your server to install the '''mssql extension alternative''' installed and running properly on your PHP box.

7. Set the following settings in your php.ini file
:* mssql.textlimit = 20971520
:* mssql.textsize = 20971520
:Also, don't forget to set one of the following '''alternatives''', in order to get all the data properly "slashed":
:* magic_quotes_gpc = Off '''or'''
:* magic_quotes_gpc = On '''and''' magic_quotes_sybase = On

8. With all this properly configured, you can continue with a [[Installing Moodle|standard Moodle installation]].

== Using FreeTDS on Unix ==

If you web server is on Linux or some other flavour of Unix, try FreeTDS, http://www.freetds.org (documentation at http://www.freetds.org/docs.html)

Note that the download link above is a '''source download''', so you will need to install and compile it properly.

Once downloaded and uncompressed you must '''"configure, make, make install"''' it. This will deploy some stuff in the "/usr/local" directory of your machine, mainly:
* /usr/local/etc: where the freetds conf files will reside.
* /usr/local/lib: where compiled libraries will reside.
* /usr/local/bin: where some executables will reside.

Then, you must configure FreeTDS to point to your MSSQL DB server. To do so, edit (or create) the /usr/local/etc/freetds.conf file and put in there exclusively these lines:

[global]
host = xxx.xxx.xxx.xxx (ip of the MSSQL server)
port = 1433
client charset = UTF-8
tds version = 7.0
text size = 20971520

At this point, and previously to build the '''mssql extension alternative''', you can test conectivity with your MSSQL DB using the "/usr/local/bin/tsql" executable. Just do this:

tsql -S serverhost -U dbowner -P dbpassword

If everything is ok, you'll get this output:

locale is "es_ES.UTF-8"
locale charset is "UTF-8"
1>

just type, for example:

sp_help sysobjects

and you might get some output from DB. Finally type:

exit

and you'll be out from the "tsql" command line interpreter.

Now that you've successfully built, configured and tested FreeTDS it is time to create the '''mssql extension alternative''' that will provide us with the capacity of handling MSSQL DBs from within Moodle. To do so, you'll need configure your PHP server adding this new option to the usual ones:

--with-mssql=/usr/local/

then, after the standard "make and make install" steps, your PHP server will be built with MSSQL support provided by FreeTDS.

Finally, configure your Moodle config.php with this DB related info and continue with a normal Moodle install:

$CFG->dbtype = 'mssql_n'; // Required
$CFG->dbhost = 'xxx.xxx.xxx.xxx'; // IP of the MSSQL server (also proper hostname is allowed)
$CFG->dbname = 'moodle'; // or whatever you called the database you created
$CFG->dbuser = 'yourusername'; // I usually use the 'sa' account (dbowner perms are enough)
$CFG->dbpass = 'yourpassword';
$CFG->dbpersist = false;
$CFG->prefix = 'mdl_'; //Prefix, you can change it, but '''never''' leave it blank.

== Using FreeTDS on Windows ==

If your web server is on Windows, use '''php_dblib.dll''' from Frank Kromann ([http://kromann.info/article.php?Id=11062598797760000 original details here]). Despite the name, it's FreeTDS compiled for Windows. Many thanks to Frank for providing this DLL. Here's how to set it up:

1. Download the appropriate copy of php_dblib.dll from the list below, and save it into your /PHP/ext directory. (php_dblib.dll does not appear to be available for PHP 4.x at this time.)

[http://kromann.info/php5_1-Release_TS/php_dblib.dll php_dblib.dll for PHP 5.1.x]

[http://kromann.info/php5_2-Release_TS/php_dblib.dll php_dblib.dll for PHP 5.2.x]

[http://kromann.info/php6-Release_TS/php_dblib.dll php_dblib.dll for PHP 6.x]

2. FreeTDS requires the .NET Framework v1.1 to be installed. You can [http://www.microsoft.com/downloads/details.aspx?FamilyID=262d25e3-f589-4842-8157-034d1e7cf3a3&DisplayLang=en download it from the Microsoft website] along with its [http://www.microsoft.com/downloads/details.aspx?FamilyID=a8f5654f-088e-40b2-bbdb-a83353618b38&DisplayLang=en service pack]. Alternatively, if you do not wish to install this framework, you can [http://kromann.info/ms-libs/msvcr71.dll download the required DLL] from Frank's site, and save it into your /PHP root directory.

3. Edit your /PHP/php.ini file and add this line:

extension=php_dblib.dll

Make sure that any lines referring to the php_mssql.dll extension are DISABLED (commented out).

4. Create a file called C:\freetds.conf with:

[global]
host = xxx.xxx.xxx.xxx (ip of the MSSQL server)
port = 1433
client charset = UTF-8
tds version = 7.0
text size = 20971520

5. Your Moodle config.php should include lines like these:

$CFG->dbtype = 'mssql_n'; // Required
$CFG->dbhost = 'localhost'; // assuming MS SQL is on the same server, otherwise use an IP
$CFG->dbname = 'moodle'; // or whatever you called the database you created
$CFG->dbuser = 'yourusername'; // I usually use the 'sa' account (dbowner perms are enough)
$CFG->dbpass = 'yourpassword';
$CFG->dbpersist = false;
$CFG->prefix = 'mdl_'; //Prefix, you can change it, but '''never''' leave it blank.

If you don't have a config.php file yet, it can be generated as normal from the Moodle installer.

6. Restart or start your web server. If Moodle still cannot communicate with the database server, please turn display_startup_errors to "On" in your /PHP/php.ini file, then restart the web server and check for any errors that may indicate incorrect DLL versions or missing dependencies. These error reports, turned off by default in PHP, can be vital in locating a problem with new extension installations.

7. Install Moodle as usual. Good luck!

== Using ODBTP on Unix or Windows ==

You can download ODBTP from http://odbtp.sourceforge.net/. Also you will access to the documentation from the same page.

The downloaded package includes both the source code and some binaries to be installed in the server and some ready-to-use '''mssql extension alternatives''' for some platforms/PHP versions (so you won't need to compile it if your PHP server/version binary package is present).

First of all, we have to install the Win32 service that comes with the package. Let's assume that it's going to run in the same Win32 machine where your MSSQL server is running (although it can run in any other Win32 server in your network).

To do do, following the instructions present in http://odbtp.sourceforge.net/install.html, you must:

# Create a directory on the Windows host where the service program files will reside, i.e., md odbtp.
# Copy the files odbtpctl.exe, odbtpsrv.exe and odbtpsrv.ini files from the winservice directory into the directory created in step 1.
# Edit the file odbtpsrv.ini of the previous step and this line: <pre>MaxRequestSize=20971520</pre>
# Open a command prompt (cmd) window on the Windows host.
# Change to the directory to which the service program files were copied, i.e., cd odbtp.
# Run the following commands to install and start the service:
#* odbtpctl install
#* odbtpctl start
# With these steps you should have one new service running in your host called "odbtp". Verify it's present and running in the "Services" control panel.
# Don't forget to enable TCP/IP incoming connections to port 2799 in the host you have installed the service!

Now it's time to build the '''mssql extension alternative'''. First of all, verify if, in the downloaded package, under the "php" dir, there is one extension suitable for your PHP server/version. If it's present, you can simply copy it to the php/extensions dir in your PHP server and skip next points about compiling it from source. It's important to point that, inside each directory, you'll find '''two different''' libraries/dll files. The one that must be copied to the extensions dir is the one called '''"php_odbtp_mssql.xxx"'''!

If in the downloaded package isn't present the extension matching your PHP platform/version, you should build if from source files. To do that, just '''"configure, make, make install"'''. That will create some stuff under "/usr/local".

Now that you've successfully built ODBTP is time to create the '''mssql extension alternative''' that will provide us with the capacity of handling MSSQL DBs from within Moodle. To do so, just configure your PHP server adding this new option to the usual ones:

--with-odbtp-mssql

then, after the standard "make and make install" steps, your PHP server will be built with MSSQL support provided by ODBTP.

Finally, independently if we are using the binary extension provided in the download or if you have built it from source files, it's time to configure the extension. To do so, add this lines, if no present, to your php.ini file:

extension=php_odbtp.dll

(only for Win32 PHP servers!)

And, for all the server platforms:

[odbtp]
odbtp.interface_file = "/path/to/your/odbtp.conf"
odbtp.datetime_format = mdyhmsf
odbtp.detach_default_queries = yes

(where ''/path/to/your/odbtp.conf" is usually "/usr/local/etc/odbtp.conf"" for Unix systems and "C:\odbtp\odbtp.conf" for Windows systems)

Then, edit such "odbtp.conf" file and put there these contents:

[global]
odbtp host = xxx.xxx.xxx (ip or hostname of the Win32 box running the ODBTP service)
type = mssql
unicode sql = yes
use row cache = yes
right trim text = yes
var data size = 20971520

With this, your PHP server will be able to connect with the MSSQL DB server using ODBTP. From here, just continue with the installation.

Finally, if you find the ODBTP executables and '''mssql extension alternative''' in binary formats, it only will be necessary to install them in your server (binary packages...) without the need to recompile anything (just the php.ini and odbtp.conf edition steps above will be necessary). Of course, it will be really welcome to have all those binary alternatives documented here.

== Using ODBC on Windows ==

{{Not for production sites}}

1. Go to the '''Administrative Tools''' control panel, then the '''Data Sources (ODBC)''' panel.

2. Configure one new System/User DSN (call it, for example "moodle"). Dont forget to enable these options if the driver asks for them:

:* ANSI NULLS Enabled = true
:* Quoted Identifiers Enabled = true

3. Your Moodle config.php should include lines like these:

$CFG->dbtype = 'odbc_mssql'; // Note this is different to all the other configs on this page!
$CFG->dbhost = 'moodle'; // Where this matches the Data source name you chose above
$CFG->dbname = '''''''; // Keep it blank!!
$CFG->dbuser = 'yourusername'; // I usually use the 'sa' account (dbowner perms are enough)
$CFG->dbpass = 'yourpassword';
$CFG->dbpersist = false;
$CFG->prefix = 'mdl_'; //Prefix, you can change it, but '''never''' leave it blank.

4. Install Moodle as usual. Good luck!

== Related links ==

[[Installing Oracle for PHP]]

[[Category:Installation]]
[[Category:Developer]]
[[Category:XMLDB]]

Installing MSSQL for PHP

2007-09-10T09:50:55Z

Tanthalas: /* Using FreeTDS on Windows */

{{Moodle 1.7}}
== Introduction ==

This short manual is suitable if you are trying to run Moodle 1.7 (and upwards) using the SQL*Server (MSSQL) RDBMS. Steps detailed below must be performed '''before''' installing Moodle itself.

First of all, minimum required version of MSSQL has been stabilised to MSSQL 2005 (v.9), although it '''might work with MSSQL 2000 (v.8) or newer'''. All the development process has been performed using MSSQL 2005 and there could be some '''unknown problems''' with previous releases.

While PHP comes with one, more or less, standard extension (mssql) that provides access to MSSQL databases, early we found some hard limits on it. Basically such default extension has some limits that prevent us to use it at all (you can find more info about this problems [[Development:XMLDB problems#MSSQL, PHP, UTF-8 and UCS-2|here]].

So, in order to allow PHP (i.e. Moodle) to access to MSSQL DBs properly we have to install a '''mssql extension alternative''' to save us from the problems related above. See the sections below for details about the various options.

== Installation overview ==

1. Get MSSQL Server installed and running.
:Make sure that you choose mixed authentication (Windows and local accounts) to keep things simpler later. You'll be asked to define the "sa" account password (it's the default System Administrator account which has full access to all databases by default).

2. Make sure MS SQL Server can accept incoming TCP/IP connections on port 1433 (the standard one).
:You might need to explicitly allow this in your Windows firewall (see the Control Panel). You may also need to edit options in the :'''SQL Server Configuration Manager''' -> '''Network Configuration''' -> '''Protocols''' -> '''TCP/IP enabled'''

3. Open the "SQL Server Management Studio" and create a new empty database. If you are using the "sa" account then you don't need to do anything else here.

4. Configure these settings in your created (and still empty) database:

:* ANSI NULLS Enabled = true
:* Quoted Identifiers Enabled = true

5. Get PHP installed with a web server. Unless you want to do it under IIS or some other way, the packages on the [http://download.moodle.org Moodle download page] are a good solution.

6. Choose one of the following specific sections for your server to install the '''mssql extension alternative''' installed and running properly on your PHP box.

7. Set the following settings in your php.ini file
:* mssql.textlimit = 20971520
:* mssql.textsize = 20971520
:Also, don't forget to set one of the following '''alternatives''', in order to get all the data properly "slashed":
:* magic_quotes_gpc = Off '''or'''
:* magic_quotes_gpc = On '''and''' magic_quotes_sybase = On

8. With all this properly configured, you can continue with a [[Installing Moodle|standard Moodle installation]].

== Using FreeTDS on Unix ==

If you web server is on Linux or some other flavour of Unix, try FreeTDS, http://www.freetds.org (documentation at http://www.freetds.org/docs.html)

Note that the download link above is a '''source download''', so you will need to install and compile it properly.

Once downloaded and uncompressed you must '''"configure, make, make install"''' it. This will deploy some stuff in the "/usr/local" directory of your machine, mainly:
* /usr/local/etc: where the freetds conf files will reside.
* /usr/local/lib: where compiled libraries will reside.
* /usr/local/bin: where some executables will reside.

Then, you must configure FreeTDS to point to your MSSQL DB server. To do so, edit (or create) the /usr/local/etc/freetds.conf file and put in there exclusively these lines:

[global]
host = xxx.xxx.xxx.xxx (ip of the MSSQL server)
port = 1433
client charset = UTF-8
tds version = 7.0
text size = 20971520

At this point, and previously to build the '''mssql extension alternative''', you can test conectivity with your MSSQL DB using the "/usr/local/bin/tsql" executable. Just do this:

tsql -S serverhost -U dbowner -P dbpassword

If everything is ok, you'll get this output:

locale is "es_ES.UTF-8"
locale charset is "UTF-8"
1>

just type, for example:

sp_help sysobjects

and you might get some output from DB. Finally type:

exit

and you'll be out from the "tsql" command line interpreter.

Now that you've successfully built, configured and tested FreeTDS it is time to create the '''mssql extension alternative''' that will provide us with the capacity of handling MSSQL DBs from within Moodle. To do so, you'll need configure your PHP server adding this new option to the usual ones:

--with-mssql=/usr/local/

then, after the standard "make and make install" steps, your PHP server will be built with MSSQL support provided by FreeTDS.

Finally, configure your Moodle config.php with this DB related info and continue with a normal Moodle install:

$CFG->dbtype = 'mssql_n'; // Required
$CFG->dbhost = 'xxx.xxx.xxx.xxx'; // IP of the MSSQL server (also proper hostname is allowed)
$CFG->dbname = 'moodle'; // or whatever you called the database you created
$CFG->dbuser = 'yourusername'; // I usually use the 'sa' account (dbowner perms are enough)
$CFG->dbpass = 'yourpassword';
$CFG->dbpersist = false;
$CFG->prefix = 'mdl_'; //Prefix, you can change it, but '''never''' leave it blank.

== Using FreeTDS on Windows ==

If your web server is on Windows, use '''php_dblib.dll''' from Frank Kromann ([http://kromann.info/article.php?Id=11062598797760000 original details here]). Despite the name, it's FreeTDS compiled for Windows. Many thanks to Frank for providing this DLL. Here's how to set it up:

1. Download the appropriate copy of php_dblib.dll from the list below, and save it into your /PHP/ext directory. (php_dblib.dll does not appear to be available for PHP 4.x at this time.)

[http://kromann.info/php5_1-Release_TS/php_dblib.dll php_dblib.dll for PHP 5.1.x]

[http://kromann.info/php5_2-Release_TS/php_dblib.dll php_dblib.dll for PHP 5.2.x]

[http://kromann.info/php6-Release_TS/php_dblib.dll php_dblib.dll for PHP 6.x]

2. FreeTDS requires the .NET Framework v1.1 to be installed. You can [http://www.microsoft.com/downloads/details.aspx?FamilyID=262d25e3-f589-4842-8157-034d1e7cf3a3&DisplayLang=en download it from the Microsoft website] along with its [http://www.microsoft.com/downloads/details.aspx?FamilyID=a8f5654f-088e-40b2-bbdb-a83353618b38&DisplayLang=en service pack]. Alternatively, if you do not wish to install this framework, you can [http://kromann.info/ms-libs/msvcr71.dll download the required DLL] from Frank's site, and save it into your /PHP root directory.

3. Edit your /PHP/php.ini file and add this line:

extension=php_dblib.dll

Make sure that any lines referring to the php_mssql.dll extension are DISABLED (commented out).

4. Create a file called C:\freetds.conf with:

[global]
host = xxx.xxx.xxx.xxx (ip of the MSSQL server)
port = 1433
client charset = UTF-8
tds version = 7.0
text size = 20971520

5. Your Moodle config.php should include lines like these:

$CFG->dbtype = 'mssql_n'; // Required
$CFG->dbhost = 'localhost'; // assuming MS SQL is on the same server, otherwise use an IP
$CFG->dbname = 'moodle'; // or whatever you called the database you created
$CFG->dbuser = 'yourusername'; // I usually use the 'sa' account (dbowner perms are enough)
$CFG->dbpass = 'yourpassword';
$CFG->dbpersist = false;
$CFG->prefix = 'mdl_'; //Prefix, you can change it, but '''never''' leave it blank.

If you don't have a config.php file yet, it can be generated as normal from the Moodle installer.

6. Restart or start your web server.

7. Install Moodle as usual. Good luck!

== Using ODBTP on Unix or Windows ==

You can download ODBTP from http://odbtp.sourceforge.net/. Also you will access to the documentation from the same page.

The downloaded package includes both the source code and some binaries to be installed in the server and some ready-to-use '''mssql extension alternatives''' for some platforms/PHP versions (so you won't need to compile it if your PHP server/version binary package is present).

First of all, we have to install the Win32 service that comes with the package. Let's assume that it's going to run in the same Win32 machine where your MSSQL server is running (although it can run in any other Win32 server in your network).

To do do, following the instructions present in http://odbtp.sourceforge.net/install.html, you must:

# Create a directory on the Windows host where the service program files will reside, i.e., md odbtp.
# Copy the files odbtpctl.exe, odbtpsrv.exe and odbtpsrv.ini files from the winservice directory into the directory created in step 1.
# Edit the file odbtpsrv.ini of the previous step and this line: <pre>MaxRequestSize=20971520</pre>
# Open a command prompt (cmd) window on the Windows host.
# Change to the directory to which the service program files were copied, i.e., cd odbtp.
# Run the following commands to install and start the service:
#* odbtpctl install
#* odbtpctl start
# With these steps you should have one new service running in your host called "odbtp". Verify it's present and running in the "Services" control panel.
# Don't forget to enable TCP/IP incoming connections to port 2799 in the host you have installed the service!

Now it's time to build the '''mssql extension alternative'''. First of all, verify if, in the downloaded package, under the "php" dir, there is one extension suitable for your PHP server/version. If it's present, you can simply copy it to the php/extensions dir in your PHP server and skip next points about compiling it from source. It's important to point that, inside each directory, you'll find '''two different''' libraries/dll files. The one that must be copied to the extensions dir is the one called '''"php_odbtp_mssql.xxx"'''!

If in the downloaded package isn't present the extension matching your PHP platform/version, you should build if from source files. To do that, just '''"configure, make, make install"'''. That will create some stuff under "/usr/local".

Now that you've successfully built ODBTP is time to create the '''mssql extension alternative''' that will provide us with the capacity of handling MSSQL DBs from within Moodle. To do so, just configure your PHP server adding this new option to the usual ones:

--with-odbtp-mssql

then, after the standard "make and make install" steps, your PHP server will be built with MSSQL support provided by ODBTP.

Finally, independently if we are using the binary extension provided in the download or if you have built it from source files, it's time to configure the extension. To do so, add this lines, if no present, to your php.ini file:

extension=php_odbtp.dll

(only for Win32 PHP servers!)

And, for all the server platforms:

[odbtp]
odbtp.interface_file = "/path/to/your/odbtp.conf"
odbtp.datetime_format = mdyhmsf
odbtp.detach_default_queries = yes

(where ''/path/to/your/odbtp.conf" is usually "/usr/local/etc/odbtp.conf"" for Unix systems and "C:\odbtp\odbtp.conf" for Windows systems)

Then, edit such "odbtp.conf" file and put there these contents:

[global]
odbtp host = xxx.xxx.xxx (ip or hostname of the Win32 box running the ODBTP service)
type = mssql
unicode sql = yes
use row cache = yes
right trim text = yes
var data size = 20971520

With this, your PHP server will be able to connect with the MSSQL DB server using ODBTP. From here, just continue with the installation.

Finally, if you find the ODBTP executables and '''mssql extension alternative''' in binary formats, it only will be necessary to install them in your server (binary packages...) without the need to recompile anything (just the php.ini and odbtp.conf edition steps above will be necessary). Of course, it will be really welcome to have all those binary alternatives documented here.

== Using ODBC on Windows ==

{{Not for production sites}}

1. Go to the '''Administrative Tools''' control panel, then the '''Data Sources (ODBC)''' panel.

2. Configure one new System/User DSN (call it, for example "moodle"). Dont forget to enable these options if the driver asks for them:

:* ANSI NULLS Enabled = true
:* Quoted Identifiers Enabled = true

3. Your Moodle config.php should include lines like these:

$CFG->dbtype = 'odbc_mssql'; // Note this is different to all the other configs on this page!
$CFG->dbhost = 'moodle'; // Where this matches the Data source name you chose above
$CFG->dbname = '''''''; // Keep it blank!!
$CFG->dbuser = 'yourusername'; // I usually use the 'sa' account (dbowner perms are enough)
$CFG->dbpass = 'yourpassword';
$CFG->dbpersist = false;
$CFG->prefix = 'mdl_'; //Prefix, you can change it, but '''never''' leave it blank.

4. Install Moodle as usual. Good luck!

== Related links ==

[[Installing Oracle for PHP]]

[[Category:Installation]]
[[Category:Developer]]
[[Category:XMLDB]]

Installing MSSQL for PHP

2007-09-10T09:29:35Z

Tanthalas: /* Using FreeTDS on Windows */

{{Moodle 1.7}}
== Introduction ==

This short manual is suitable if you are trying to run Moodle 1.7 (and upwards) using the SQL*Server (MSSQL) RDBMS. Steps detailed below must be performed '''before''' installing Moodle itself.

First of all, minimum required version of MSSQL has been stabilised to MSSQL 2005 (v.9), although it '''might work with MSSQL 2000 (v.8) or newer'''. All the development process has been performed using MSSQL 2005 and there could be some '''unknown problems''' with previous releases.

While PHP comes with one, more or less, standard extension (mssql) that provides access to MSSQL databases, early we found some hard limits on it. Basically such default extension has some limits that prevent us to use it at all (you can find more info about this problems [[Development:XMLDB problems#MSSQL, PHP, UTF-8 and UCS-2|here]].

So, in order to allow PHP (i.e. Moodle) to access to MSSQL DBs properly we have to install a '''mssql extension alternative''' to save us from the problems related above. See the sections below for details about the various options.

== Installation overview ==

1. Get MSSQL Server installed and running.
:Make sure that you choose mixed authentication (Windows and local accounts) to keep things simpler later. You'll be asked to define the "sa" account password (it's the default System Administrator account which has full access to all databases by default).

2. Make sure MS SQL Server can accept incoming TCP/IP connections on port 1433 (the standard one).
:You might need to explicitly allow this in your Windows firewall (see the Control Panel). You may also need to edit options in the :'''SQL Server Configuration Manager''' -> '''Network Configuration''' -> '''Protocols''' -> '''TCP/IP enabled'''

3. Open the "SQL Server Management Studio" and create a new empty database. If you are using the "sa" account then you don't need to do anything else here.

4. Configure these settings in your created (and still empty) database:

:* ANSI NULLS Enabled = true
:* Quoted Identifiers Enabled = true

5. Get PHP installed with a web server. Unless you want to do it under IIS or some other way, the packages on the [http://download.moodle.org Moodle download page] are a good solution.

6. Choose one of the following specific sections for your server to install the '''mssql extension alternative''' installed and running properly on your PHP box.

7. Set the following settings in your php.ini file
:* mssql.textlimit = 20971520
:* mssql.textsize = 20971520
:Also, don't forget to set one of the following '''alternatives''', in order to get all the data properly "slashed":
:* magic_quotes_gpc = Off '''or'''
:* magic_quotes_gpc = On '''and''' magic_quotes_sybase = On

8. With all this properly configured, you can continue with a [[Installing Moodle|standard Moodle installation]].

== Using FreeTDS on Unix ==

If you web server is on Linux or some other flavour of Unix, try FreeTDS, http://www.freetds.org (documentation at http://www.freetds.org/docs.html)

Note that the download link above is a '''source download''', so you will need to install and compile it properly.

Once downloaded and uncompressed you must '''"configure, make, make install"''' it. This will deploy some stuff in the "/usr/local" directory of your machine, mainly:
* /usr/local/etc: where the freetds conf files will reside.
* /usr/local/lib: where compiled libraries will reside.
* /usr/local/bin: where some executables will reside.

Then, you must configure FreeTDS to point to your MSSQL DB server. To do so, edit (or create) the /usr/local/etc/freetds.conf file and put in there exclusively these lines:

[global]
host = xxx.xxx.xxx.xxx (ip of the MSSQL server)
port = 1433
client charset = UTF-8
tds version = 7.0
text size = 20971520

At this point, and previously to build the '''mssql extension alternative''', you can test conectivity with your MSSQL DB using the "/usr/local/bin/tsql" executable. Just do this:

tsql -S serverhost -U dbowner -P dbpassword

If everything is ok, you'll get this output:

locale is "es_ES.UTF-8"
locale charset is "UTF-8"
1>

just type, for example:

sp_help sysobjects

and you might get some output from DB. Finally type:

exit

and you'll be out from the "tsql" command line interpreter.

Now that you've successfully built, configured and tested FreeTDS it is time to create the '''mssql extension alternative''' that will provide us with the capacity of handling MSSQL DBs from within Moodle. To do so, you'll need configure your PHP server adding this new option to the usual ones:

--with-mssql=/usr/local/

then, after the standard "make and make install" steps, your PHP server will be built with MSSQL support provided by FreeTDS.

Finally, configure your Moodle config.php with this DB related info and continue with a normal Moodle install:

$CFG->dbtype = 'mssql_n'; // Required
$CFG->dbhost = 'xxx.xxx.xxx.xxx'; // IP of the MSSQL server (also proper hostname is allowed)
$CFG->dbname = 'moodle'; // or whatever you called the database you created
$CFG->dbuser = 'yourusername'; // I usually use the 'sa' account (dbowner perms are enough)
$CFG->dbpass = 'yourpassword';
$CFG->dbpersist = false;
$CFG->prefix = 'mdl_'; //Prefix, you can change it, but '''never''' leave it blank.

== Using FreeTDS on Windows ==

If your web server is on Windows, use '''php_dblib.dll''' from Frank Kromann ([http://kromann.info/article.php?Id=11062598797760000 original details here]). Despite the name, it's FreeTDS compiled for Windows. Many thanks to Frank for providing this DLL. Here's how to set it up:

1. Download the appropriate copy of php_dblib.dll from the list below, and save it into your /PHP/ext directory. (php_dblib.dll does not appear to be available for PHP 4.x at this time.)

[http://kromann.info/php5_1-Release_TS/php_dblib.dll php_dblib.dll for PHP 5.1.x]

[http://kromann.info/php5_2-Release_TS/php_dblib.dll php_dblib.dll for PHP 5.2.x]

[http://kromann.info/php6-Release_TS/php_dblib.dll php_dblib.dll for PHP 6.x]

2. Edit your php.ini and add this line:

extension=php_dblib.dll

Make sure that any lines referring to the php_mssql.dll extension are DISABLED (commented out).

3. Create a file called C:\freetds.conf with:

[global]
host = xxx.xxx.xxx.xxx (ip of the MSSQL server)
port = 1433
client charset = UTF-8
tds version = 7.0
text size = 20971520

4. Your Moodle config.php should include lines like these:

$CFG->dbtype = 'mssql_n'; // Required
$CFG->dbhost = 'localhost'; // assuming MS SQL is on the same server, otherwise use an IP
$CFG->dbname = 'moodle'; // or whatever you called the database you created
$CFG->dbuser = 'yourusername'; // I usually use the 'sa' account (dbowner perms are enough)
$CFG->dbpass = 'yourpassword';
$CFG->dbpersist = false;
$CFG->prefix = 'mdl_'; //Prefix, you can change it, but '''never''' leave it blank.

4. Restart or start your web server.

5. Install Moodle as usual. Good luck!

== Using ODBTP on Unix or Windows ==

You can download ODBTP from http://odbtp.sourceforge.net/. Also you will access to the documentation from the same page.

The downloaded package includes both the source code and some binaries to be installed in the server and some ready-to-use '''mssql extension alternatives''' for some platforms/PHP versions (so you won't need to compile it if your PHP server/version binary package is present).

First of all, we have to install the Win32 service that comes with the package. Let's assume that it's going to run in the same Win32 machine where your MSSQL server is running (although it can run in any other Win32 server in your network).

To do do, following the instructions present in http://odbtp.sourceforge.net/install.html, you must:

# Create a directory on the Windows host where the service program files will reside, i.e., md odbtp.
# Copy the files odbtpctl.exe, odbtpsrv.exe and odbtpsrv.ini files from the winservice directory into the directory created in step 1.
# Edit the file odbtpsrv.ini of the previous step and this line: <pre>MaxRequestSize=20971520</pre>
# Open a command prompt (cmd) window on the Windows host.
# Change to the directory to which the service program files were copied, i.e., cd odbtp.
# Run the following commands to install and start the service:
#* odbtpctl install
#* odbtpctl start
# With these steps you should have one new service running in your host called "odbtp". Verify it's present and running in the "Services" control panel.
# Don't forget to enable TCP/IP incoming connections to port 2799 in the host you have installed the service!

Now it's time to build the '''mssql extension alternative'''. First of all, verify if, in the downloaded package, under the "php" dir, there is one extension suitable for your PHP server/version. If it's present, you can simply copy it to the php/extensions dir in your PHP server and skip next points about compiling it from source. It's important to point that, inside each directory, you'll find '''two different''' libraries/dll files. The one that must be copied to the extensions dir is the one called '''"php_odbtp_mssql.xxx"'''!

If in the downloaded package isn't present the extension matching your PHP platform/version, you should build if from source files. To do that, just '''"configure, make, make install"'''. That will create some stuff under "/usr/local".

Now that you've successfully built ODBTP is time to create the '''mssql extension alternative''' that will provide us with the capacity of handling MSSQL DBs from within Moodle. To do so, just configure your PHP server adding this new option to the usual ones:

--with-odbtp-mssql

then, after the standard "make and make install" steps, your PHP server will be built with MSSQL support provided by ODBTP.

Finally, independently if we are using the binary extension provided in the download or if you have built it from source files, it's time to configure the extension. To do so, add this lines, if no present, to your php.ini file:

extension=php_odbtp.dll

(only for Win32 PHP servers!)

And, for all the server platforms:

[odbtp]
odbtp.interface_file = "/path/to/your/odbtp.conf"
odbtp.datetime_format = mdyhmsf
odbtp.detach_default_queries = yes

(where ''/path/to/your/odbtp.conf" is usually "/usr/local/etc/odbtp.conf"" for Unix systems and "C:\odbtp\odbtp.conf" for Windows systems)

Then, edit such "odbtp.conf" file and put there these contents:

[global]
odbtp host = xxx.xxx.xxx (ip or hostname of the Win32 box running the ODBTP service)
type = mssql
unicode sql = yes
use row cache = yes
right trim text = yes
var data size = 20971520

With this, your PHP server will be able to connect with the MSSQL DB server using ODBTP. From here, just continue with the installation.

Finally, if you find the ODBTP executables and '''mssql extension alternative''' in binary formats, it only will be necessary to install them in your server (binary packages...) without the need to recompile anything (just the php.ini and odbtp.conf edition steps above will be necessary). Of course, it will be really welcome to have all those binary alternatives documented here.

== Using ODBC on Windows ==

{{Not for production sites}}

1. Go to the '''Administrative Tools''' control panel, then the '''Data Sources (ODBC)''' panel.

2. Configure one new System/User DSN (call it, for example "moodle"). Dont forget to enable these options if the driver asks for them:

:* ANSI NULLS Enabled = true
:* Quoted Identifiers Enabled = true

3. Your Moodle config.php should include lines like these:

$CFG->dbtype = 'odbc_mssql'; // Note this is different to all the other configs on this page!
$CFG->dbhost = 'moodle'; // Where this matches the Data source name you chose above
$CFG->dbname = '''''''; // Keep it blank!!
$CFG->dbuser = 'yourusername'; // I usually use the 'sa' account (dbowner perms are enough)
$CFG->dbpass = 'yourpassword';
$CFG->dbpersist = false;
$CFG->prefix = 'mdl_'; //Prefix, you can change it, but '''never''' leave it blank.

4. Install Moodle as usual. Good luck!

== Related links ==

[[Installing Oracle for PHP]]

[[Category:Installation]]
[[Category:Developer]]
[[Category:XMLDB]]

Development:Coding

2006-08-24T15:14:21Z

Tanthalas: /* Database structures */

Any collaborative project needs consistency and stability to stay strong.

These '''coding guidelines''' are to provide a goal for all Moodle code to strive to. It's true that some of the older existing code falls short in a few areas, but it will all be fixed eventually. All new code definitely must adhere to these standards as closely as possible.

==General rules==

# All code files should use the .php extension.
# All template files should use the .html extension.
# All text files should use Unix-style text format (most text editors have this as an option).
# All php tags must be 'full' tags like <?php ?> ... not 'short' tags like <? ?>.
# All existing copyright notices must be retained. You can add your own if necessary.
# Each file should include the main config.php file.
# Each file should check that the user is authenticated correctly, using require_login() and isadmin(), isteacher(), iscreator() or isstudent().
# All access to databases should use the functions in ''lib/datalib.php'' whenever possible - this allows compatibility across a wide range of databases. You should find that almost anything is possible using these functions. If you must write SQL code then make sure it is: cross-platform; restricted to specific functions within your code (usually a lib.php file); and clearly marked.
# Don't create or use global variables except for the standard $CFG, $SESSION, $THEME, $SITE, $COURSE and $USER.
# All variables should be initialised or at least tested for existence using isset() or empty() before they are used.
# All strings should be translatable - create new texts in the "lang/en_utf8" files with concise English lowercase names and retrieve them from your code using get_string() or print_string().
# All help files should be translatable - create new texts in the "lang/en_utf8/help" directory and call them using helpbutton(). If you need to update a help file:
#* with a minor change, where an old translation of the file would still make sense, then it's OK to make the change but you should notify translation AT moodle DOT org.
#* for a major change you should create a new file by adding an incrementing number (eg filename2.html) so that translators can easily see it's a new version of the file. Obviously the new code and the help index files should also be modified to point to the newest versions.
# Incoming data from the browser (sent via GET or POST) automatically has magic_quotes applied (regardless of the PHP settings) so that you can safely insert it straight into the database. All other raw data (from files, or from databases) must be escaped with addslashes() before inserting it into the database.
# VERY IMPORTANT: All texts within Moodle, especially those that have come from users, should be printed using the format_text() function. This ensures that text is filtered and cleaned correctly.
# User actions should be logged using the [[add_to_log|add_to_log()]] function. These logs are used for [[Settings#Show_activity_reports|activity reports]] and [[Logs]].

==Coding style==

I know it can be a little annoying to change your style if you're used to something else, but balance that annoyance against the annoyance of all the people trying later on to make sense of Moodle code with mixed styles. There are obviously many good points for and against any style that people use, but the current style just is, so please stick to it.

1. Indenting should be consistently 4 spaces. Don't use tabs AT ALL.

2. Variable names should always be easy-to-read, meaningful lowercase English words. If you really need more than one word then run them together, but keep them short as possible. Use plural names for arrays of objects.

GOOD: $quiz
GOOD: $errorstring
GOOD: $assignments (for an array of objects)
GOOD: $i (but only in little loops)

BAD: $Quiz
BAD: $aReallyLongVariableNameWithoutAGoodReason
BAD: $error_string

3. Constants should always be in upper case, and always start with the name of the module. They should have words separated by underscores.

define("FORUM_MODE_FLATOLDEST", 1);
4. Function names should be simple English lowercase words, and start with the name of the module to avoid conflicts between modules. Words should be separated by underscores. Parameters should always have sensible defaults if possible. Note there is no space between the function name and the following (brackets).

function forum_set_display_mode($mode=0) {
global $USER, $CFG;

if ($mode) {
$USER->mode = $mode;
} else if (empty($USER->mode)) {
$USER->mode = $CFG->forum_displaymode;
}
}

5. Blocks must always be enclosed in curly braces (even if there is only one line). Moodle uses this style:

if ($quiz->attempts) {
if ($numattempts > $quiz->attempts) {
error($strtoomanyattempts, "view.php?id=$cm->id");
}
}

6. Strings should be defined using single quotes where possible, for increased speed.

$var = 'some text without any variables';
$var = "with special characters like a new line \n";
$var = 'a very, very long string with a '.$single.' variable in it';
$var = "some $text with $many variables $within it";

7. Comments should be added as much as is practical, to explain the code flow and the purpose of functions and variables.

* Every function (and class) should use the popular [http://www.phpdoc.org/ phpDoc format]. This allows code documentation to be generated automatically.
* Inline comments should use the // style, laid out neatly so that it fits among the code and lines up with it.

/**
* The description should be first, with asterisks laid out exactly
* like this example. If you want to refer to a another function,
* do it like this: {@link clean_param()}. Then, add descriptions
* for each parameter as follows.
*
* @param int $postid The PHP type is followed by the variable name
* @param array $scale The PHP type is followed by the variable name
* @param array $ratings The PHP type is followed by the variable name
* @return mixed
*/
function forum_get_ratings_mean($postid, $scale, $ratings=NULL) {
if (!$ratings) {
$ratings = array(); // Initialize the empty array
if ($rates = get_records("forum_ratings", "post", $postid)) {
// Process each rating in turn
foreach ($rates as $rate) {
....etc

8. Space should be used liberally - don't be afraid to spread things out a little to gain some clarity. Generally, there should be one space between brackets and normal statements, but no space between brackets and variables or functions:

foreach ($objects as $key => $thing) {
process($thing);
}

if ($x == $y) {
$a = $b;
} else if ($x == $z) {
$a = $c;
} else {
$a = $d;
}

9. When making a COPY of an object, always use the php5 clone() function (otherwise you may end up with just a reference to the first object). Moodle will make sure this works consistently on php4 too.

BAD: $b = $a;
GOOD: $b = clone($a);

If the thing you want to copy is not an object, but may contain objects (eg an array of objects) then use fullclone() instead.

==Database structures==

# Every table must have an auto-incrementing id field (INT10) as primary index. (see [[IdColumnReasons]])
# The main table containing instances of each module must have the same name as the module (eg widget) and contain the following minimum fields:
#* id - as described above
#* course - the id of the course that each instance belongs to
#* name - the full name of each instance of the module
# Other tables associated with a module that contain information about 'things' should be named widget_things (note the plural).
# Table and column names should avoid using [[Database reserved words|reserved words in any database]]. Please check them before creation.
# Column names should be always lowercase, simple and short, following the same rules as for variable names.
# Where possible, columns that contain a reference to the id field of another table (eg widget) should be called widgetid. (Note that this convention is newish and not followed in some older tables)
# Boolean fields should be implemented as small integer fields (eg INT4) containing 0 or 1, to allow for later expansion of values if necessary.
# Most tables should have a timemodified field (INT10) which is updated with a current timestamp obtained with the PHP time() function.
# Always define a default value for each field (and make it sensible)
# Each table name should start with the database prefix ($CFG->prefix). In a lot of cases, this is taken care of for you automatically. Also, under Postgres, the name of every index must start with the prefix too.

==Security issues (and handling form and URL data)==

# Do not rely on 'register_globals'. Every variable must be properly initialised in every code file. It must be obvious where the variable came from
# Initialise all arrays and objects, even if empty. $a = array() or $obj = new stdClass();.
# Do not use the optional_variable() function (this function is now deprecated). Use the optional_param() function instead. Pick the correct PARAM_XXXX value for the data type you expect.
# Do not use the require_variable() function (this function is now deprecated). Use the required_param() function instead. Pick the correct PARAM_XXXX value for the data type you expect.
# Use data_submitted(), with care. Data must still be cleaned before use.
# Do not use $_GET, $_POST or $_REQUEST. Use the appropriate required_param() or optional_param() appropriate to your need.
# Do not check for an action using something like if (isset($_GET['something'])). Use, e.g., $something = optional_param( 'something',-1,PARAM_INT ) and then perform proper test for it being in its expected range of values e.g., if ($something>=0) {....
# Wherever possible group all your required_param(), optional_param() and other variables initialisation at the beginning of each file to make them easy to find.
# Use 'sesskey' mechanism to protect form handling routines from attack. Basic example of use: when form is generated, include <input type="hidden" name="sesskey" value="<?php echo sesskey(); ?>" />. When you process the form check with if (!confirm_sesskey()) {error('Bad Session Key');}.
# All filenames must be 'cleaned' using the clean_filename() function, if this has not been done already by appropriate use of required_param() or optional_param()
# Any data read from the database must have addslashes() applied to it before it can be written back. A whole object of data can be hit at once with addslashes_object().
# Wherever possible, data to be stored in the database must come from POST data (from a form with method="POST") as opposed to GET data (ie, data from the URL line).
# Do not use data from $_SERVER if you can avoid it. This has portability issues.
# If it hasn't been done somewhere else, make sure all data written to the database has been through the clean_param() function using the appropriate PARAM_XXXX for the datatype.
# If you write custom SQL code, make very sure it is correct. In particular watch out for missing quotes around values. Possible SQL 'injection' exploit.
# Check all data (particularly that written to the database) in every file it is used. Do not expect or rely on it being done somewhere else.
# Blocks of code to be included should contain a definite PHP structure (e.g, a class declaration, function definition(s) etc.) - straight blocks of code promote uninitialised variable usage.

[[Category:Developer]]

[[es:Manual de Estilo de Código]]