MoodleDocs - User contributions [en]

User:Nicolas Connault

2010-07-11T11:21:46Z

Nicolasconnault: Removing all content from page

User:Nicolas Connault

2009-10-26T22:31:42Z

Nicolasconnault: /* Contact Details */

==Contact Details==
ICQ: 826611
Yahoo : nicolasconnault
AIM: NikoZeta
Skype: nicolasconnault
Email: nicolasconnault@gmail.com
Cell: 0435423748

==First steps towards Moodle==
Born in 1978 in France, I have 4 brothers and 1 sister. At age 19, I spent 2 years on a mission in England for the [http://www.mormon.org Church of Jesus Christ of Latter-Day Saints]. There I learned much about human nature and saw much misery and suffering, mostly caused by dysfunctional relationships between people, especially in families. I decided I would study psychology and become a family counselor, to help alleviate the hurt I saw all around me.

I returned home to France in 2000, and shortly thereafter met my wife Anne-Marie while chatting on ICQ. We discovered we had similar interests, beliefs and values, and within 2 weeks (!?) I proposed to her over the Internet. I hadn't yet seen a picture of her. To me, physical appearance was not a concern.

She came over to France 6 (long!) months later, and we were married in France (civilly) and in England (for eternity in the Temple). A few months later we moved to England for a job which did not work out as expected, following which we moved to Western Australia in 2001.

==University and Self-teaching==
There I started taking interest in Web Development as a hobby (I had already built a couple of static websites as a youth), and used the many resources available online to teach myself LAMP/WAMP development. When I started my psychology degree (externally at Edith Cowan University), I chose a minor in professional computing, which included Object-Oriented programming, Database design and Web Development, but these added little to the knowledge I had already gained through learning online. The vibrant PHP community was the greatest source of learning for me.

A few years ago I undertook my first serious open source project with two other friends, Christopher Vance and Vickie Comrie (both from the USA). The project was a PHP auction framework, along the lines of Ebay but much more simple, which could be implemented by small companies wanting an auction system. It was a voluntary project for a fairly large american charity. This project hasn't been maintained for years, and I would probably cringe if I looked at the source code now, but the skills I learned while working on it have proven invaluable.

The code for the auction project attracted the attention of a small web development company, Triangle Solutions, who contracted me immediately on a part-time basis, later to become full-time. During the 1.5 years I worked for Triangle, I contributed to many different projects, but the most important was PHP Support Tickets, an application originally written in horrible spaghetti PHP which I was asked to upgrade. My decision was to rewrite it using Object-Oriented principles, of which I knew enough to improve the application at the time. Unfortunately I did not have the time resources available to devote enough time on this project, which greatly hindered its development. I still think it has great potential, but I would certainly refactor it if I had the opportunity to work on it again.

==Beginnings at Moodle HQ==
In December 2006, I applied for the developer position at Moodle HQ in Perth, and was hired on a full-time basis. I started out doing mainly bug-squashing for version 1.8, but was also made responsible for unit testing, an area which had been greatly neglected until then. As soon as 1.8 was stable and released, I started working on the new gradebook internals for 1.9, together with Yu Zhang, Martin Dougiamas and Petr Skoda.

==Other programming interests==
=== Ruby ===
One last note on development: I have recently taken great interest in the Ruby language, although that interest started much earlier than the current Ruby on Rails craze. I find the language extremely elegant, intuitive and fun to write in. It enables me to be much more creative than with PHP or Java. I also enjoy the Rails framework, although it certainly isn't as easy to learn as some people would have you believe. I am currently working on a real estate application (sales and rentals) written on that platform. You can see the front-end for one of my clients at [http://www.glenmarrealty.com.au Glenmar Realty].

=== Test-Driven Development (TDD) ===
Since my early days with Object-Oriented languages, I have been a strong proponent of unit testing, and a keen supporter of the Test-Driven Development approach. Unfortunately it is not always easy to adopt such methodology when working on a project like Moodle, with much legacy and non-OO code. The approach was successfully used when developing the new gradebook for Moodle 1.9, although it could have used better.

In the last 6 months I have given 3 presentations on the subject of Unit Testing. One was at the [http://elearning.lse.ac.uk/blogs/clt/?p=251 2007 UK Moodle Moot], and the other two were given at two different branches of the BCS, [http://nottmderby.bcs.org/events08-feb.htm Derby-Nottingham] and [http://www.herts.bcs.org/past.htm Hertfordshire]. [http://moodlemoot.org/file.php/4/moddata/assignment/1/438/presentation.ppt My slides] are available at these sites, but there are minor differences between them, since I try to improve my presentation each time.

==Psychology==
On the topic of psychology: during my external studies, I became more and more disillusioned with the traditional counseling practice. I felt that, although the intentions of most professional psychologists were noble, their skills were often exercised within an ideological framework of manufactured needs. This meant that often, their contributions to the well-being of the human race were more imagined than real.

My interests diverged towards community development, group processes, interpersonal relationships, child development and the learning process. I became aware that people tended to get better emotionally when they had a strong support network, and that non-professional assistance in the form of support groups was often more effective than prohibitory and extensive therapy sessions.

I also became more and more disenchanted with the educational practices of the universities in Australia. They seemed to be based on ancient traditions and to ignore the very principles they were teaching. I especially abhorred the lecture medium of teaching, which was one reason why I chose to study externally. However I did a few units on campus and was glad to see some tutors trying to change their delivery methods to something more informal and participative. Overall I was extremely disappointed in the appalling quality of external teaching. It was extremely difficult to connect with other students, and you only got help if you persistently sought for it. Feedback was as rare (and precious) as gold. BlackBoard was inadequate in many ways, and most tutors didn't even use it. The drop-out rates from external courses was so great that it was very difficult to extract that figure from university staff. I wouldn't be surprised if only around 10% of all external students across all Australian universities actually stuck to their entire course, not to mention those who stay but fail.

My project for the honours degree (which I have delayed for next year) was to compare the teaching methods of a German university with those of Edith Cowan University, and to compare the measurable results. The project for my doctorate was to develop an online, open source software suite that would enable external students to connect with each other as a vibrant community, in order to facilitate self-motivated learning and participation. This was a major factor in me accepting the job with Moodle, which represented exactly what I had in mind.

Well, this is a rather lengthy description, but those that have read all of it now know a lot about me, and will be better able to understand the person behind the posts and the code.

Development:Blog 2.0

2009-10-22T23:44:22Z

Nicolasconnault: /* External blogs */

{{Work in progress}}{{Moodle 2.0}}

* '''PROJECT STATE: Coding'''
* '''MAIN TRACKER ISSUE''': MDL-19676 Blog 2.0 improvements
* '''DISCUSSION AND COMMENTS''': http://moodle.org/mod/forum/discuss.php?d=133348

== Description of improvements ==
=== Who can view blog entries? ===
Blog entries are either in draft mode (only the author can view it), or in public mode. In public mode, everyone on the entire site can view the blog entry.

Before 2.0 there was an attempt to restrict who can view certain blog entries, based on course enrolment and capabilities. However, after extensive discussion and feasibility testing it became clear that this could lead to serious performance and usability issues on large sites, and was turning the blog into something more akin to a forum. It was thus decided to make all blogs public. (See MDL-19676)

This simplification means that sites using the old BLOG_GROUP_LEVEL and BLOG_COURSE_LEVEL and values of $CFG->bloglevel have to perform an special upgrade which copies all the site's blog entries into a special "blog-type" forum in each course in which the blog entry's author is enrolled, then disables blogging at site level.

Capabilities:
*moodle/blog:view
*moodle/blog:viewdrafts

=== Associations ===
A blog entry can optionally be associated with a course. This makes it possible for a user to blog "about" that course. All blog entries associated in that way can be viewed on a page like blog/index.php?courseid=3. This type of filtering of blog entries does not take into account course enrolments.

Additionally, blog entries can be associated with an activity module.

This requires the creation of a new table, in which the associations are recorded.
Tracker issue: MDL-14408

Capabilities:
*moodle/blog:associatecourse
*moodle/blog:associatemodule

=== Improved navigation ===
Before 2.0, the navigation for any listing of blog entries was either "Site > User > Blogs" (for a user's blog entries) or "Site > Blogs" for the whole site's blog entries, optionally filtered by tag. With the new association features, we need a better way to display what type of blog listing we are looking at, based on the parameters passed to blog/index.php. The navigation should also reflect additional filters such as tag and search.

=== External blogs ===
A user can specify external blogs which publish an RSS/ATOM feed. This feed is then checked periodically through a cron task, and entries are copied into the user's blog in Moodle, as read-only entries.

This synchronisation checks if external entries have been modified or deleted since the last sync, and updates the Moodle entries accordingly.

These external blogs are a user preference, and two types of tags can be added to each of them: "Filter tags" and "Automatic tags":
*Filter tags are used to filter the external blog entries that get copied into Moodle. They must match the tags used by that external blog. An external entry will be selected if it has at least one of the filter tags. (Tags are called "categories" in RSS feeds)
*Automatic tags are automatically added to each blog entry copied into Moodle from an external blog that uses such tags.

This requires the creation of a new DB table.
Tracker issue: MDL-19683

Capabilities:
*moodle/blog:manageexternal

=== Search blog entries ===
It is now possible to search blog entries using a search box. The results maintain the current context, so that if you are viewing a list of blog entries for a particular user, entering a term in the search box will return only the blog entries for that user that match the search term. The search term also appears in the navigation breadcrumbs.

Tracker issue: MDL-19686

Capabilities:
*moodle/blog:search

=== Contextual blog menu ===
Previously, the "blog menu" block was the same on every page on which it appeared. In 2.0 it changes depending on which page you are. For example, if you are on course/view.php, it will include a link to blog entries associated with that course. Also, the link for adding a new entry will include the courseid, making the course association automatically pre-selected in the blog entry edit form.

Tracker issue: MDL-19687

=== File attachments ===
The [[Development:File_API|new file manager]] must be implemented to allow for multiple file attachments per blog entry.

Tracker issue: MDL-19744

=== Comments ===
The new [[Development:Comments_2.0|Comments API]] makes it possible for anyone having the correct capability to comment on blog entries.

Tracker issue: MDL-8776

=== New "Recent blog entries" block ===
This block can be configured to display the last N blog entries, filtered by context. For example, if you are viewing an assignment activity, this block would display the last N blog entries that are associated with that assignment.

Tracker issue: MDL-19688

== Potential problems and limitations ==

===Upgrade from "Users can only see blogs for people who share a course"===

This mode was always a slightly quirky and uncomfortable hack. It was mostly useful for sites with very distinct courses and users, such as those where each course consists of the employees from a separate company, and My Moodle was used to hide the companies from each other. However, for the general case, the main problem is that you see ALL blog entries from those people, not just ones that are about your courses.

This mode has no direct equivalent in Moodle 2.0 because we have resolved not to emulate "course-like" modes within a system that is at system level, and outside the courses. This helps understanding of the blog system, simplifies the implementation and improves performance.

However some people may be using that mode so we do need to provide an upgrade path for them.

Informationally, the idea of just seeing all the blogs from people who are in your course is the same as a course forum.

So a possible upgrade would be to do this:
If the mode is set to "Users can only see blogs for people who share a course" then
Set the new mode to "Users can only see their own blog"
Foreach user who has a blog
Foreach course that user is enrolled in
If a "Course blogs (recovered)" forum doesn't exist yet in the course (section 0) then create one
Foreach blog entry that the user created
Create a new discussion from the blog post with the same dates, attachments etc

This way no data is lost. The teachers can choose to delete the whole forum if they choose to. The original blog entries should not be touched.

== DB Structure ==
2 new tables need to be added: blog_external and blog_association

=== blog_external ===

{| class="nicetable"
|-
! Field
! Type
! Default
! Info
|-
| id
| int(10)
| auto-incrementing
| The unique ID for this external blog.
|-
| userid
| int(10)
|
| The owner of the external blog
|-
| name
| char(255)
|
| A descriptive name for the external blog. Automatically fetched during initial import, can be overridden.
|-
| description
| text(small)
|
| A long description of the external blog. Automatically fetched during initial import, can be overridden.
|-
| url
| text(small)
|
| The URL to the external blog (e.g. http://moodle.org/rss.xml)
|-
| failedlastsync
| int(1)
|
| Whether or not the last synchronisation failed
|-
| timemodified
| int(10)
|
|
|-
| timefetched
| int(10)
|
| The last time the entries from this external blog were fetched by Moodle.
|}

=== blog_association ===

{| class="nicetable"
|-
! Field
! Type
! Default
! Info
|-
| id
| int(10)
| auto-incrementing
| The unique ID for this blog entry<->contextid association.
|-
| contextid
| int(10)
|
| The context id defined in context table - identifies the instance of the course or plugin associated with the blog entry.
|-
| blogid
| int(10)
|
| The id of the blog entry (from the post table) being associated with a course or module instance
|}

== Upgrade process ==
The only task required by the upgrade process is to install the new DB tables.

== See also ==
*[[Development:Blogs|Early wishlist]]
*[[Student_projects/Blog_improvements|2008 GSoC project addressing some of these improvements]]

Development:Blog 2.0

2009-10-22T08:56:15Z

Nicolasconnault: /* blog_external */

{{Work in progress}}{{Moodle 2.0}}

* '''PROJECT STATE: Coding'''
* '''MAIN TRACKER ISSUE''': MDL-19676 Blog 2.0 improvements
* '''DISCUSSION AND COMMENTS''': http://moodle.org/mod/forum/discuss.php?d=133348

== Description of improvements ==
=== Who can view blog entries? ===
Blog entries are either in draft mode (only the author can view it), or in public mode. In public mode, everyone on the entire site can view the blog entry.

Before 2.0 there was an attempt to restrict who can view certain blog entries, based on course enrolment and capabilities. However, after extensive discussion and feasibility testing it became clear that this could lead to serious performance and usability issues on large sites, and was turning the blog into something more akin to a forum. It was thus decided to make all blogs public. (See MDL-19676)

This simplification means that sites using the old BLOG_GROUP_LEVEL and BLOG_COURSE_LEVEL and values of $CFG->bloglevel have to perform an special upgrade which copies all the site's blog entries into a special "blog-type" forum in each course in which the blog entry's author is enrolled, then disables blogging at site level.

Capabilities:
*moodle/blog:view
*moodle/blog:viewdrafts

=== Associations ===
A blog entry can optionally be associated with a course. This makes it possible for a user to blog "about" that course. All blog entries associated in that way can be viewed on a page like blog/index.php?courseid=3. This type of filtering of blog entries does not take into account course enrolments.

Additionally, blog entries can be associated with an activity module.

This requires the creation of a new table, in which the associations are recorded.
Tracker issue: MDL-14408

Capabilities:
*moodle/blog:associatecourse
*moodle/blog:associatemodule

=== Improved navigation ===
Before 2.0, the navigation for any listing of blog entries was either "Site > User > Blogs" (for a user's blog entries) or "Site > Blogs" for the whole site's blog entries, optionally filtered by tag. With the new association features, we need a better way to display what type of blog listing we are looking at, based on the parameters passed to blog/index.php. The navigation should also reflect additional filters such as tag and search.

=== External blogs ===
A user can import blog entries into Moodle from external blogs. The external blog's entries are copied into Moodle when the external blog URL is entered, and a cron task periodically checks these external blogs to copy new entries not yet entered in Moodle. The period of time between checks can be adjusted as an admin setting.

These external blogs are a user preference, and two types of tags can be added to each of them: "External tags" and "Moodle tags":
*External tags are used to filter the external blog entries that get copied into Moodle. They must match the tags used by that external blog.
*Moodle tags are automatically added to each blog entry copied into Moodle from an external blog that uses such tags. This makes it easier to distinguish which of a user's blog entries come from an external blog.

This requires the creation of a new DB table.
Tracker issue: MDL-19683

Capabilities:
*moodle/blog:manageexternal

=== Search blog entries ===
It is now possible to search blog entries using a search box. The results maintain the current context, so that if you are viewing a list of blog entries for a particular user, entering a term in the search box will return only the blog entries for that user that match the search term. The search term also appears in the navigation breadcrumbs.

Tracker issue: MDL-19686

Capabilities:
*moodle/blog:search

=== Contextual blog menu ===
Previously, the "blog menu" block was the same on every page on which it appeared. In 2.0 it changes depending on which page you are. For example, if you are on course/view.php, it will include a link to blog entries associated with that course. Also, the link for adding a new entry will include the courseid, making the course association automatically pre-selected in the blog entry edit form.

Tracker issue: MDL-19687

=== File attachments ===
The [[Development:File_API|new file manager]] must be implemented to allow for multiple file attachments per blog entry.

Tracker issue: MDL-19744

=== Comments ===
The new [[Development:Comments_2.0|Comments API]] makes it possible for anyone having the correct capability to comment on blog entries.

Tracker issue: MDL-8776

=== New "Recent blog entries" block ===
This block can be configured to display the last N blog entries, filtered by context. For example, if you are viewing an assignment activity, this block would display the last N blog entries that are associated with that assignment.

Tracker issue: MDL-19688

== Potential problems and limitations ==

===Upgrade from "Users can only see blogs for people who share a course"===

This mode was always a slightly quirky and uncomfortable hack. It was mostly useful for sites with very distinct courses and users, such as those where each course consists of the employees from a separate company, and My Moodle was used to hide the companies from each other. However, for the general case, the main problem is that you see ALL blog entries from those people, not just ones that are about your courses.

This mode has no direct equivalent in Moodle 2.0 because we have resolved not to emulate "course-like" modes within a system that is at system level, and outside the courses. This helps understanding of the blog system, simplifies the implementation and improves performance.

However some people may be using that mode so we do need to provide an upgrade path for them.

Informationally, the idea of just seeing all the blogs from people who are in your course is the same as a course forum.

So a possible upgrade would be to do this:
If the mode is set to "Users can only see blogs for people who share a course" then
Set the new mode to "Users can only see their own blog"
Foreach user who has a blog
Foreach course that user is enrolled in
If a "Course blogs (recovered)" forum doesn't exist yet in the course (section 0) then create one
Foreach blog entry that the user created
Create a new discussion from the blog post with the same dates, attachments etc

This way no data is lost. The teachers can choose to delete the whole forum if they choose to. The original blog entries should not be touched.

== DB Structure ==
2 new tables need to be added: blog_external and blog_association

=== blog_external ===

{| class="nicetable"
|-
! Field
! Type
! Default
! Info
|-
| id
| int(10)
| auto-incrementing
| The unique ID for this external blog.
|-
| userid
| int(10)
|
| The owner of the external blog
|-
| name
| char(255)
|
| A descriptive name for the external blog. Automatically fetched during initial import, can be overridden.
|-
| description
| text(small)
|
| A long description of the external blog. Automatically fetched during initial import, can be overridden.
|-
| url
| text(small)
|
| The URL to the external blog (e.g. http://moodle.org/rss.xml)
|-
| failedlastsync
| int(1)
|
| Whether or not the last synchronisation failed
|-
| timemodified
| int(10)
|
|
|-
| timefetched
| int(10)
|
| The last time the entries from this external blog were fetched by Moodle.
|}

=== blog_association ===

{| class="nicetable"
|-
! Field
! Type
! Default
! Info
|-
| id
| int(10)
| auto-incrementing
| The unique ID for this blog entry<->contextid association.
|-
| contextid
| int(10)
|
| The context id defined in context table - identifies the instance of the course or plugin associated with the blog entry.
|-
| blogid
| int(10)
|
| The id of the blog entry (from the post table) being associated with a course or module instance
|}

== Upgrade process ==
The only task required by the upgrade process is to install the new DB tables.

== See also ==
*[[Development:Blogs|Early wishlist]]
*[[Student_projects/Blog_improvements|2008 GSoC project addressing some of these improvements]]

Development:Blog 2.0

2009-10-22T08:52:04Z

Nicolasconnault: /* blog_external */

{{Work in progress}}{{Moodle 2.0}}

* '''PROJECT STATE: Coding'''
* '''MAIN TRACKER ISSUE''': MDL-19676 Blog 2.0 improvements
* '''DISCUSSION AND COMMENTS''': http://moodle.org/mod/forum/discuss.php?d=133348

== Description of improvements ==
=== Who can view blog entries? ===
Blog entries are either in draft mode (only the author can view it), or in public mode. In public mode, everyone on the entire site can view the blog entry.

Before 2.0 there was an attempt to restrict who can view certain blog entries, based on course enrolment and capabilities. However, after extensive discussion and feasibility testing it became clear that this could lead to serious performance and usability issues on large sites, and was turning the blog into something more akin to a forum. It was thus decided to make all blogs public. (See MDL-19676)

This simplification means that sites using the old BLOG_GROUP_LEVEL and BLOG_COURSE_LEVEL and values of $CFG->bloglevel have to perform an special upgrade which copies all the site's blog entries into a special "blog-type" forum in each course in which the blog entry's author is enrolled, then disables blogging at site level.

Capabilities:
*moodle/blog:view
*moodle/blog:viewdrafts

=== Associations ===
A blog entry can optionally be associated with a course. This makes it possible for a user to blog "about" that course. All blog entries associated in that way can be viewed on a page like blog/index.php?courseid=3. This type of filtering of blog entries does not take into account course enrolments.

Additionally, blog entries can be associated with an activity module.

This requires the creation of a new table, in which the associations are recorded.
Tracker issue: MDL-14408

Capabilities:
*moodle/blog:associatecourse
*moodle/blog:associatemodule

=== Improved navigation ===
Before 2.0, the navigation for any listing of blog entries was either "Site > User > Blogs" (for a user's blog entries) or "Site > Blogs" for the whole site's blog entries, optionally filtered by tag. With the new association features, we need a better way to display what type of blog listing we are looking at, based on the parameters passed to blog/index.php. The navigation should also reflect additional filters such as tag and search.

=== External blogs ===
A user can import blog entries into Moodle from external blogs. The external blog's entries are copied into Moodle when the external blog URL is entered, and a cron task periodically checks these external blogs to copy new entries not yet entered in Moodle. The period of time between checks can be adjusted as an admin setting.

These external blogs are a user preference, and two types of tags can be added to each of them: "External tags" and "Moodle tags":
*External tags are used to filter the external blog entries that get copied into Moodle. They must match the tags used by that external blog.
*Moodle tags are automatically added to each blog entry copied into Moodle from an external blog that uses such tags. This makes it easier to distinguish which of a user's blog entries come from an external blog.

This requires the creation of a new DB table.
Tracker issue: MDL-19683

Capabilities:
*moodle/blog:manageexternal

=== Search blog entries ===
It is now possible to search blog entries using a search box. The results maintain the current context, so that if you are viewing a list of blog entries for a particular user, entering a term in the search box will return only the blog entries for that user that match the search term. The search term also appears in the navigation breadcrumbs.

Tracker issue: MDL-19686

Capabilities:
*moodle/blog:search

=== Contextual blog menu ===
Previously, the "blog menu" block was the same on every page on which it appeared. In 2.0 it changes depending on which page you are. For example, if you are on course/view.php, it will include a link to blog entries associated with that course. Also, the link for adding a new entry will include the courseid, making the course association automatically pre-selected in the blog entry edit form.

Tracker issue: MDL-19687

=== File attachments ===
The [[Development:File_API|new file manager]] must be implemented to allow for multiple file attachments per blog entry.

Tracker issue: MDL-19744

=== Comments ===
The new [[Development:Comments_2.0|Comments API]] makes it possible for anyone having the correct capability to comment on blog entries.

Tracker issue: MDL-8776

=== New "Recent blog entries" block ===
This block can be configured to display the last N blog entries, filtered by context. For example, if you are viewing an assignment activity, this block would display the last N blog entries that are associated with that assignment.

Tracker issue: MDL-19688

== Potential problems and limitations ==

===Upgrade from "Users can only see blogs for people who share a course"===

This mode was always a slightly quirky and uncomfortable hack. It was mostly useful for sites with very distinct courses and users, such as those where each course consists of the employees from a separate company, and My Moodle was used to hide the companies from each other. However, for the general case, the main problem is that you see ALL blog entries from those people, not just ones that are about your courses.

This mode has no direct equivalent in Moodle 2.0 because we have resolved not to emulate "course-like" modes within a system that is at system level, and outside the courses. This helps understanding of the blog system, simplifies the implementation and improves performance.

However some people may be using that mode so we do need to provide an upgrade path for them.

Informationally, the idea of just seeing all the blogs from people who are in your course is the same as a course forum.

So a possible upgrade would be to do this:
If the mode is set to "Users can only see blogs for people who share a course" then
Set the new mode to "Users can only see their own blog"
Foreach user who has a blog
Foreach course that user is enrolled in
If a "Course blogs (recovered)" forum doesn't exist yet in the course (section 0) then create one
Foreach blog entry that the user created
Create a new discussion from the blog post with the same dates, attachments etc

This way no data is lost. The teachers can choose to delete the whole forum if they choose to. The original blog entries should not be touched.

== DB Structure ==
2 new tables need to be added: blog_external and blog_association

=== blog_external ===

{| class="nicetable"
|-
! Field
! Type
! Default
! Info
|-
| id
| int(10)
| auto-incrementing
| The unique ID for this external blog.
|-
| userid
| int(10)
|
| The owner of the external blog
|-
| name
| char(255)
|
| A descriptive name for the external blog. Automatically fetched during initial import, can be overridden.
|-
| description
| text(small)
|
| A long description of the external blog. Automatically fetched during initial import, can be overridden.
|-
| url
| text(small)
|
| The URL to the external blog (e.g. http://moodle.org/rss.xml)
|-
| validationresult
| int(1)
|
| A cached boolean of the last Feed validation test
|-
| timemodified
| int(10)
|
|
|-
| timefetched
| int(10)
|
| The last time the entries from this external blog were fetched by Moodle.
|}

=== blog_association ===

{| class="nicetable"
|-
! Field
! Type
! Default
! Info
|-
| id
| int(10)
| auto-incrementing
| The unique ID for this blog entry<->contextid association.
|-
| contextid
| int(10)
|
| The context id defined in context table - identifies the instance of the course or plugin associated with the blog entry.
|-
| blogid
| int(10)
|
| The id of the blog entry (from the post table) being associated with a course or module instance
|}

== Upgrade process ==
The only task required by the upgrade process is to install the new DB tables.

== See also ==
*[[Development:Blogs|Early wishlist]]
*[[Student_projects/Blog_improvements|2008 GSoC project addressing some of these improvements]]

Development:Blog 2.0

2009-10-15T03:02:29Z

Nicolasconnault: /* Who can view blog entries? */

{{Work in progress}}{{Moodle 2.0}}

* '''PROJECT STATE: Coding'''
* '''MAIN TRACKER ISSUE''': MDL-19676 Blog 2.0 improvements
* '''DISCUSSION AND COMMENTS''': http://moodle.org/mod/forum/discuss.php?d=133348

== Description of improvements ==
=== Who can view blog entries? ===
Blog entries are either in draft mode (only the author can view it), or in public mode. In public mode, everyone on the entire site can view the blog entry.

Before 2.0 there was an attempt to restrict who can view certain blog entries, based on course enrolment and capabilities. However, after extensive discussion and feasibility testing it became clear that this could lead to serious performance and usability issues on large sites, and was turning the blog into something more akin to a forum. It was thus decided to make all blogs public. (See MDL-19676)

This simplification means that sites using the old BLOG_GROUP_LEVEL and BLOG_COURSE_LEVEL and values of $CFG->bloglevel have to perform an special upgrade which copies all the site's blog entries into a special "blog-type" forum in each course in which the blog entry's author is enrolled, then disables blogging at site level.

Capabilities:
*moodle/blog:view
*moodle/blog:viewdrafts

=== Associations ===
A blog entry can optionally be associated with a course. This makes it possible for a user to blog "about" that course. All blog entries associated in that way can be viewed on a page like blog/index.php?courseid=3. This type of filtering of blog entries does not take into account course enrolments.

Additionally, blog entries can be associated with an activity module.

This requires the creation of a new table, in which the associations are recorded.
Tracker issue: MDL-14408

Capabilities:
*moodle/blog:associatecourse
*moodle/blog:associatemodule

=== Improved navigation ===
Before 2.0, the navigation for any listing of blog entries was either "Site > User > Blogs" (for a user's blog entries) or "Site > Blogs" for the whole site's blog entries, optionally filtered by tag. With the new association features, we need a better way to display what type of blog listing we are looking at, based on the parameters passed to blog/index.php. The navigation should also reflect additional filters such as tag and search.

=== External blogs ===
A user can import blog entries into Moodle from external blogs. The external blog's entries are copied into Moodle when the external blog URL is entered, and a cron task periodically checks these external blogs to copy new entries not yet entered in Moodle. The period of time between checks can be adjusted as an admin setting.

These external blogs are a user preference, and two types of tags can be added to each of them: "External tags" and "Moodle tags":
*External tags are used to filter the external blog entries that get copied into Moodle. They must match the tags used by that external blog.
*Moodle tags are automatically added to each blog entry copied into Moodle from an external blog that uses such tags. This makes it easier to distinguish which of a user's blog entries come from an external blog.

This requires the creation of a new DB table.
Tracker issue: MDL-19683

Capabilities:
*moodle/blog:manageexternal

=== Search blog entries ===
It is now possible to search blog entries using a search box. The results maintain the current context, so that if you are viewing a list of blog entries for a particular user, entering a term in the search box will return only the blog entries for that user that match the search term. The search term also appears in the navigation breadcrumbs.

Tracker issue: MDL-19686

Capabilities:
*moodle/blog:search

=== Contextual blog menu ===
Previously, the "blog menu" block was the same on every page on which it appeared. In 2.0 it changes depending on which page you are. For example, if you are on course/view.php, it will include a link to blog entries associated with that course. Also, the link for adding a new entry will include the courseid, making the course association automatically pre-selected in the blog entry edit form.

Tracker issue: MDL-19687

=== File attachments ===
The [[Development:File_API|new file manager]] must be implemented to allow for multiple file attachments per blog entry.

Tracker issue: MDL-19744

=== Comments ===
The new [[Development:Comments_2.0|Comments API]] makes it possible for anyone having the correct capability to comment on blog entries.

Tracker issue: MDL-8776

=== New "Recent blog entries" block ===
This block can be configured to display the last N blog entries, filtered by context. For example, if you are viewing an assignment activity, this block would display the last N blog entries that are associated with that assignment.

Tracker issue: MDL-19688

== Potential problems and limitations ==

===Upgrade from "Users can only see blogs for people who share a course"===

This mode was always a slightly quirky and uncomfortable hack. It was mostly useful for sites with very distinct courses and users, such as those where each course consists of the employees from a separate company, and My Moodle was used to hide the companies from each other. However, for the general case, the main problem is that you see ALL blog entries from those people, not just ones that are about your courses.

This mode has no direct equivalent in Moodle 2.0 because we have resolved not to emulate "course-like" modes within a system that is at system level, and outside the courses. This helps understanding of the blog system, simplifies the implementation and improves performance.

However some people may be using that mode so we do need to provide an upgrade path for them.

Informationally, the idea of just seeing all the blogs from people who are in your course is the same as a course forum.

So a possible upgrade would be to do this:
If the mode is set to "Users can only see blogs for people who share a course" then
Set the new mode to "Users can only see their own blog"
Foreach user who has a blog
Foreach course that user is enrolled in
If a "Course blogs (recovered)" forum doesn't exist yet in the course (section 0) then create one
Foreach blog entry that the user created
Create a new discussion from the blog post with the same dates, attachments etc

This way no data is lost. The teachers can choose to delete the whole forum if they choose to. The original blog entries should not be touched.

== DB Structure ==
2 new tables need to be added: blog_external and blog_association

=== blog_external ===

{| class="nicetable"
|-
! Field
! Type
! Default
! Info
|-
| id
| int(10)
| auto-incrementing
| The unique ID for this external blog.
|-
| userid
| int(10)
|
| The owner of the external blog
|-
| name
| char(255)
|
| A descriptive name for the external blog. Automatically fetched during initial import, can be overridden.
|-
| description
| text(small)
|
| A long description of the external blog. Automatically fetched during initial import, can be overridden.
|-
| url
| text(small)
|
| The URL to the external blog (e.g. http://moodle.org/rss.xml)
|-
| timemodified
| int(10)
|
|
|-
| timefetched
| int(10)
|
| The last time the entries from this external blog were fetched by Moodle.
|}

=== blog_association ===

{| class="nicetable"
|-
! Field
! Type
! Default
! Info
|-
| id
| int(10)
| auto-incrementing
| The unique ID for this blog entry<->contextid association.
|-
| contextid
| int(10)
|
| The context id defined in context table - identifies the instance of the course or plugin associated with the blog entry.
|-
| blogid
| int(10)
|
| The id of the blog entry (from the post table) being associated with a course or module instance
|}

== Upgrade process ==
The only task required by the upgrade process is to install the new DB tables.

== See also ==
*[[Development:Blogs|Early wishlist]]
*[[Student_projects/Blog_improvements|2008 GSoC project addressing some of these improvements]]

Development:Blog 2.0

2009-10-15T02:45:30Z

Nicolasconnault: /* Associations */

{{Work in progress}}{{Moodle 2.0}}

* '''PROJECT STATE: Coding'''
* '''MAIN TRACKER ISSUE''': MDL-19676 Blog 2.0 improvements
* '''DISCUSSION AND COMMENTS''': http://moodle.org/mod/forum/discuss.php?d=133348

== Description of improvements ==
=== Who can view blog entries? ===
Blog entries are either in draft mode (only the author can view it), or in public mode. In public mode, everyone on the entire site can view the blog entry.

At one stage in 2.0 development there was an attempt to restrict who can view certain blog entries, based on course enrolment and capabilities. However, after extensive discussion and feasibility testing it became clear that this would lead to serious performance and usability issues, and would turn the blog into something more akin to a forum. It was thus decided to make all blogs public. (See MDL-19676)

An admin setting can allow for blog entries to be accessible by non-logged-in users, for the purpose of publishing and RSS feed aggregation.

Capabilities:
*moodle/blog:view
*moodle/blog:viewdrafts

=== Associations ===
A blog entry can optionally be associated with a course. This makes it possible for a user to blog "about" that course. All blog entries associated in that way can be viewed on a page like blog/index.php?courseid=3. This type of filtering of blog entries does not take into account course enrolments.

Additionally, blog entries can be associated with an activity module.

This requires the creation of a new table, in which the associations are recorded.
Tracker issue: MDL-14408

Capabilities:
*moodle/blog:associatecourse
*moodle/blog:associatemodule

=== Improved navigation ===
Before 2.0, the navigation for any listing of blog entries was either "Site > User > Blogs" (for a user's blog entries) or "Site > Blogs" for the whole site's blog entries, optionally filtered by tag. With the new association features, we need a better way to display what type of blog listing we are looking at, based on the parameters passed to blog/index.php. The navigation should also reflect additional filters such as tag and search.

=== External blogs ===
A user can import blog entries into Moodle from external blogs. The external blog's entries are copied into Moodle when the external blog URL is entered, and a cron task periodically checks these external blogs to copy new entries not yet entered in Moodle. The period of time between checks can be adjusted as an admin setting.

These external blogs are a user preference, and two types of tags can be added to each of them: "External tags" and "Moodle tags":
*External tags are used to filter the external blog entries that get copied into Moodle. They must match the tags used by that external blog.
*Moodle tags are automatically added to each blog entry copied into Moodle from an external blog that uses such tags. This makes it easier to distinguish which of a user's blog entries come from an external blog.

This requires the creation of a new DB table.
Tracker issue: MDL-19683

Capabilities:
*moodle/blog:manageexternal

=== Search blog entries ===
It is now possible to search blog entries using a search box. The results maintain the current context, so that if you are viewing a list of blog entries for a particular user, entering a term in the search box will return only the blog entries for that user that match the search term. The search term also appears in the navigation breadcrumbs.

Tracker issue: MDL-19686

Capabilities:
*moodle/blog:search

=== Contextual blog menu ===
Previously, the "blog menu" block was the same on every page on which it appeared. In 2.0 it changes depending on which page you are. For example, if you are on course/view.php, it will include a link to blog entries associated with that course. Also, the link for adding a new entry will include the courseid, making the course association automatically pre-selected in the blog entry edit form.

Tracker issue: MDL-19687

=== File attachments ===
The [[Development:File_API|new file manager]] must be implemented to allow for multiple file attachments per blog entry.

Tracker issue: MDL-19744

=== Comments ===
The new [[Development:Comments_2.0|Comments API]] makes it possible for anyone having the correct capability to comment on blog entries.

Tracker issue: MDL-8776

=== New "Recent blog entries" block ===
This block can be configured to display the last N blog entries, filtered by context. For example, if you are viewing an assignment activity, this block would display the last N blog entries that are associated with that assignment.

Tracker issue: MDL-19688

== Potential problems and limitations ==

===Upgrade from "Users can only see blogs for people who share a course"===

This mode was always a slightly quirky and uncomfortable hack. It was mostly useful for sites with very distinct courses and users, such as those where each course consists of the employees from a separate company, and My Moodle was used to hide the companies from each other. However, for the general case, the main problem is that you see ALL blog entries from those people, not just ones that are about your courses.

This mode has no direct equivalent in Moodle 2.0 because we have resolved not to emulate "course-like" modes within a system that is at system level, and outside the courses. This helps understanding of the blog system, simplifies the implementation and improves performance.

However some people may be using that mode so we do need to provide an upgrade path for them.

Informationally, the idea of just seeing all the blogs from people who are in your course is the same as a course forum.

So a possible upgrade would be to do this:
If the mode is set to "Users can only see blogs for people who share a course" then
Set the new mode to "Users can only see their own blog"
Foreach user who has a blog
Foreach course that user is enrolled in
If a "Course blogs (recovered)" forum doesn't exist yet in the course (section 0) then create one
Foreach blog entry that the user created
Create a new discussion from the blog post with the same dates, attachments etc

This way no data is lost. The teachers can choose to delete the whole forum if they choose to. The original blog entries should not be touched.

== DB Structure ==
2 new tables need to be added: blog_external and blog_association

=== blog_external ===

{| class="nicetable"
|-
! Field
! Type
! Default
! Info
|-
| id
| int(10)
| auto-incrementing
| The unique ID for this external blog.
|-
| userid
| int(10)
|
| The owner of the external blog
|-
| name
| char(255)
|
| A descriptive name for the external blog. Automatically fetched during initial import, can be overridden.
|-
| description
| text(small)
|
| A long description of the external blog. Automatically fetched during initial import, can be overridden.
|-
| url
| text(small)
|
| The URL to the external blog (e.g. http://moodle.org/rss.xml)
|-
| timemodified
| int(10)
|
|
|-
| timefetched
| int(10)
|
| The last time the entries from this external blog were fetched by Moodle.
|}

=== blog_association ===

{| class="nicetable"
|-
! Field
! Type
! Default
! Info
|-
| id
| int(10)
| auto-incrementing
| The unique ID for this blog entry<->contextid association.
|-
| contextid
| int(10)
|
| The context id defined in context table - identifies the instance of the course or plugin associated with the blog entry.
|-
| blogid
| int(10)
|
| The id of the blog entry (from the post table) being associated with a course or module instance
|}

== Upgrade process ==
The only task required by the upgrade process is to install the new DB tables.

== See also ==
*[[Development:Blogs|Early wishlist]]
*[[Student_projects/Blog_improvements|2008 GSoC project addressing some of these improvements]]

Development:Blog 2.0

2009-09-30T07:12:00Z

Nicolasconnault: /* Search blog entries */

{{Work in progress}}{{Moodle 2.0}}

* '''PROJECT STATE: Coding'''
* '''MAIN TRACKER ISSUE''': MDL-19676 Blog 2.0 improvements
* '''DISCUSSION AND COMMENTS''': http://moodle.org/mod/forum/discuss.php?d=133348

== Description of improvements ==
=== Who can view blog entries? ===
Blog entries are either in draft mode (only the author can view it), or in public mode. In public mode, everyone on the entire site can view the blog entry.

At one stage in 2.0 development there was an attempt to restrict who can view certain blog entries, based on course enrolment and capabilities. However, after extensive discussion and feasibility testing it became clear that this would lead to serious performance and usability issues, and would turn the blog into something more akin to a forum. It was thus decided to make all blogs public. (See MDL-19676)

An admin setting can allow for blog entries to be accessible by non-logged-in users, for the purpose of publishing and RSS feed aggregation.

Capabilities:
*moodle/blog:view
*moodle/blog:viewdrafts

=== Associations ===
A blog entry can optionally be associated with a course. This makes it possible for a user to blog "about" that course. All blog entries associated in that way can be viewed on a page like blog/index.php?courseid=3. This type of filtering of blog entries does not take into account course enrolments.

Additionally, blog entries can be associated with activity modules, in which case the blog entry is automatically associated with the module's course.

This requires the creation of a new table, in which the associations are recorded.
Tracker issue: MDL-14408

Capabilities:
*moodle/blog:associatecourse
*moodle/blog:associatemodule

=== Improved navigation ===
Before 2.0, the navigation for any listing of blog entries was either "Site > User > Blogs" (for a user's blog entries) or "Site > Blogs" for the whole site's blog entries, optionally filtered by tag. With the new association features, we need a better way to display what type of blog listing we are looking at, based on the parameters passed to blog/index.php. The navigation should also reflect additional filters such as tag and search.

=== External blogs ===
A user can import blog entries into Moodle from external blogs. The external blog's entries are copied into Moodle when the external blog URL is entered, and a cron task periodically checks these external blogs to copy new entries not yet entered in Moodle. The period of time between checks can be adjusted as an admin setting.

These external blogs are a user preference, and two types of tags can be added to each of them: "External tags" and "Moodle tags":
*External tags are used to filter the external blog entries that get copied into Moodle. They must match the tags used by that external blog.
*Moodle tags are automatically added to each blog entry copied into Moodle from an external blog that uses such tags. This makes it easier to distinguish which of a user's blog entries come from an external blog.

This requires the creation of a new DB table.
Tracker issue: MDL-19683

Capabilities:
*moodle/blog:manageexternal

=== Search blog entries ===
It is now possible to search blog entries using a search box. The results maintain the current context, so that if you are viewing a list of blog entries for a particular user, entering a term in the search box will return only the blog entries for that user that match the search term. The search term also appears in the navigation breadcrumbs.

Tracker issue: MDL-19686

Capabilities:
*moodle/blog:search

=== Contextual blog menu ===
Previously, the "blog menu" block was the same on every page on which it appeared. In 2.0 it changes depending on which page you are. For example, if you are on course/view.php, it will include a link to blog entries associated with that course. Also, the link for adding a new entry will include the courseid, making the course association automatically pre-selected in the blog entry edit form.

Tracker issue: MDL-19687

=== File attachments ===
The [[Development:File_API|new file manager]] must be implemented to allow for multiple file attachments per blog entry.

Tracker issue: MDL-19744

=== Comments ===
The new [[Development:Comments_2.0|Comments API]] makes it possible for anyone having the correct capability to comment on blog entries.

Tracker issue: MDL-8776

=== New "Recent blog entries" block ===
This block can be configured to display the last N blog entries, filtered by context. For example, if you are viewing an assignment activity, this block would display the last N blog entries that are associated with that assignment.

Tracker issue: MDL-19688

== Potential problems and limitations ==

== DB Structure ==
2 new tables need to be added: blog_external and blog_association

=== blog_external ===

{| class="nicetable"
|-
! Field
! Type
! Default
! Info
|-
| id
| int(10)
| auto-incrementing
| The unique ID for this external blog.
|-
| userid
| int(10)
|
| The owner of the external blog
|-
| name
| char(255)
|
| A descriptive name for the external blog. Automatically fetched during initial import, can be overridden.
|-
| description
| text(small)
|
| A long description of the external blog. Automatically fetched during initial import, can be overridden.
|-
| url
| text(small)
|
| The URL to the external blog (e.g. http://moodle.org/rss.xml)
|-
| timemodified
| int(10)
|
|
|-
| timefetched
| int(10)
|
| The last time the entries from this external blog were fetched by Moodle.
|}

=== blog_association ===

{| class="nicetable"
|-
! Field
! Type
! Default
! Info
|-
| id
| int(10)
| auto-incrementing
| The unique ID for this blog entry<->contextid association.
|-
| contextid
| int(10)
|
| The context id defined in context table - identifies the instance of the course or plugin associated with the blog entry.
|-
| blogid
| int(10)
|
| The id of the blog entry (from the post table) being associated with a course or module instance
|}

== Upgrade process ==
The only task required by the upgrade process is to install the new DB tables.

== See also ==
*[[Development:Blogs|Early wishlist]]
*[[Student_projects/Blog_improvements|2008 GSoC project addressing some of these improvements]]

Development:Blog 2.0

2009-09-30T07:00:56Z

Nicolasconnault: /* Who can view blog entries? */

{{Work in progress}}{{Moodle 2.0}}

* '''PROJECT STATE: Coding'''
* '''MAIN TRACKER ISSUE''': MDL-19676 Blog 2.0 improvements
* '''DISCUSSION AND COMMENTS''': http://moodle.org/mod/forum/discuss.php?d=133348

== Description of improvements ==
=== Who can view blog entries? ===
Blog entries are either in draft mode (only the author can view it), or in public mode. In public mode, everyone on the entire site can view the blog entry.

At one stage in 2.0 development there was an attempt to restrict who can view certain blog entries, based on course enrolment and capabilities. However, after extensive discussion and feasibility testing it became clear that this would lead to serious performance and usability issues, and would turn the blog into something more akin to a forum. It was thus decided to make all blogs public. (See MDL-19676)

An admin setting can allow for blog entries to be accessible by non-logged-in users, for the purpose of publishing and RSS feed aggregation.

Capabilities:
*moodle/blog:view
*moodle/blog:viewdrafts

=== Associations ===
A blog entry can optionally be associated with a course. This makes it possible for a user to blog "about" that course. All blog entries associated in that way can be viewed on a page like blog/index.php?courseid=3. This type of filtering of blog entries does not take into account course enrolments.

Additionally, blog entries can be associated with activity modules, in which case the blog entry is automatically associated with the module's course.

This requires the creation of a new table, in which the associations are recorded.
Tracker issue: MDL-14408

Capabilities:
*moodle/blog:associatecourse
*moodle/blog:associatemodule

=== Improved navigation ===
Before 2.0, the navigation for any listing of blog entries was either "Site > User > Blogs" (for a user's blog entries) or "Site > Blogs" for the whole site's blog entries, optionally filtered by tag. With the new association features, we need a better way to display what type of blog listing we are looking at, based on the parameters passed to blog/index.php. The navigation should also reflect additional filters such as tag and search.

=== External blogs ===
A user can import blog entries into Moodle from external blogs. The external blog's entries are copied into Moodle when the external blog URL is entered, and a cron task periodically checks these external blogs to copy new entries not yet entered in Moodle. The period of time between checks can be adjusted as an admin setting.

These external blogs are a user preference, and two types of tags can be added to each of them: "External tags" and "Moodle tags":
*External tags are used to filter the external blog entries that get copied into Moodle. They must match the tags used by that external blog.
*Moodle tags are automatically added to each blog entry copied into Moodle from an external blog that uses such tags. This makes it easier to distinguish which of a user's blog entries come from an external blog.

This requires the creation of a new DB table.
Tracker issue: MDL-19683

Capabilities:
*moodle/blog:manageexternal

=== Search blog entries ===
It is now possible to search blog entries using a search box. The results maintain the current context, so that if you are viewing a list of blog entries for a particular user, entering a term in the search box will return only the blog entries for that user that match the search term. The search term also appears in the navigation breadcrumbs.

Tracker issue: MDL-19686

=== Contextual blog menu ===
Previously, the "blog menu" block was the same on every page on which it appeared. In 2.0 it changes depending on which page you are. For example, if you are on course/view.php, it will include a link to blog entries associated with that course. Also, the link for adding a new entry will include the courseid, making the course association automatically pre-selected in the blog entry edit form.

Tracker issue: MDL-19687

=== File attachments ===
The [[Development:File_API|new file manager]] must be implemented to allow for multiple file attachments per blog entry.

Tracker issue: MDL-19744

=== Comments ===
The new [[Development:Comments_2.0|Comments API]] makes it possible for anyone having the correct capability to comment on blog entries.

Tracker issue: MDL-8776

=== New "Recent blog entries" block ===
This block can be configured to display the last N blog entries, filtered by context. For example, if you are viewing an assignment activity, this block would display the last N blog entries that are associated with that assignment.

Tracker issue: MDL-19688

== Potential problems and limitations ==

== DB Structure ==
2 new tables need to be added: blog_external and blog_association

=== blog_external ===

{| class="nicetable"
|-
! Field
! Type
! Default
! Info
|-
| id
| int(10)
| auto-incrementing
| The unique ID for this external blog.
|-
| userid
| int(10)
|
| The owner of the external blog
|-
| name
| char(255)
|
| A descriptive name for the external blog. Automatically fetched during initial import, can be overridden.
|-
| description
| text(small)
|
| A long description of the external blog. Automatically fetched during initial import, can be overridden.
|-
| url
| text(small)
|
| The URL to the external blog (e.g. http://moodle.org/rss.xml)
|-
| timemodified
| int(10)
|
|
|-
| timefetched
| int(10)
|
| The last time the entries from this external blog were fetched by Moodle.
|}

=== blog_association ===

{| class="nicetable"
|-
! Field
! Type
! Default
! Info
|-
| id
| int(10)
| auto-incrementing
| The unique ID for this blog entry<->contextid association.
|-
| contextid
| int(10)
|
| The context id defined in context table - identifies the instance of the course or plugin associated with the blog entry.
|-
| blogid
| int(10)
|
| The id of the blog entry (from the post table) being associated with a course or module instance
|}

== Upgrade process ==
The only task required by the upgrade process is to install the new DB tables.

== See also ==
*[[Development:Blogs|Early wishlist]]
*[[Student_projects/Blog_improvements|2008 GSoC project addressing some of these improvements]]

Development:Blog 2.0

2009-09-30T07:00:03Z

Nicolasconnault: /* External blogs */

{{Work in progress}}{{Moodle 2.0}}

* '''PROJECT STATE: Coding'''
* '''MAIN TRACKER ISSUE''': MDL-19676 Blog 2.0 improvements
* '''DISCUSSION AND COMMENTS''': http://moodle.org/mod/forum/discuss.php?d=133348

== Description of improvements ==
=== Who can view blog entries? ===
Blog entries are either in draft mode (only the author can view it), or in public mode. In public mode, everyone on the entire site can view the blog entry.

At one stage in 2.0 development there was an attempt to restrict who can view certain blog entries, based on course enrolment and capabilities. However, after extensive discussion and feasibility testing it became clear that this would lead to serious performance and usability issues, and would turn the blog into something more akin to a forum. It was thus decided to make all blogs public. (See MDL-19676)

An admin setting can allow for blog entries to be accessible by non-logged-in users, for the purpose of publishing and RSS feed aggregation.

=== Associations ===
A blog entry can optionally be associated with a course. This makes it possible for a user to blog "about" that course. All blog entries associated in that way can be viewed on a page like blog/index.php?courseid=3. This type of filtering of blog entries does not take into account course enrolments.

Additionally, blog entries can be associated with activity modules, in which case the blog entry is automatically associated with the module's course.

This requires the creation of a new table, in which the associations are recorded.
Tracker issue: MDL-14408

Capabilities:
*moodle/blog:associatecourse
*moodle/blog:associatemodule

=== Improved navigation ===
Before 2.0, the navigation for any listing of blog entries was either "Site > User > Blogs" (for a user's blog entries) or "Site > Blogs" for the whole site's blog entries, optionally filtered by tag. With the new association features, we need a better way to display what type of blog listing we are looking at, based on the parameters passed to blog/index.php. The navigation should also reflect additional filters such as tag and search.

=== External blogs ===
A user can import blog entries into Moodle from external blogs. The external blog's entries are copied into Moodle when the external blog URL is entered, and a cron task periodically checks these external blogs to copy new entries not yet entered in Moodle. The period of time between checks can be adjusted as an admin setting.

These external blogs are a user preference, and two types of tags can be added to each of them: "External tags" and "Moodle tags":
*External tags are used to filter the external blog entries that get copied into Moodle. They must match the tags used by that external blog.
*Moodle tags are automatically added to each blog entry copied into Moodle from an external blog that uses such tags. This makes it easier to distinguish which of a user's blog entries come from an external blog.

This requires the creation of a new DB table.
Tracker issue: MDL-19683

Capabilities:
*moodle/blog:manageexternal

=== Search blog entries ===
It is now possible to search blog entries using a search box. The results maintain the current context, so that if you are viewing a list of blog entries for a particular user, entering a term in the search box will return only the blog entries for that user that match the search term. The search term also appears in the navigation breadcrumbs.

Tracker issue: MDL-19686

=== Contextual blog menu ===
Previously, the "blog menu" block was the same on every page on which it appeared. In 2.0 it changes depending on which page you are. For example, if you are on course/view.php, it will include a link to blog entries associated with that course. Also, the link for adding a new entry will include the courseid, making the course association automatically pre-selected in the blog entry edit form.

Tracker issue: MDL-19687

=== File attachments ===
The [[Development:File_API|new file manager]] must be implemented to allow for multiple file attachments per blog entry.

Tracker issue: MDL-19744

=== Comments ===
The new [[Development:Comments_2.0|Comments API]] makes it possible for anyone having the correct capability to comment on blog entries.

Tracker issue: MDL-8776

=== New "Recent blog entries" block ===
This block can be configured to display the last N blog entries, filtered by context. For example, if you are viewing an assignment activity, this block would display the last N blog entries that are associated with that assignment.

Tracker issue: MDL-19688

== Potential problems and limitations ==

== DB Structure ==
2 new tables need to be added: blog_external and blog_association

=== blog_external ===

{| class="nicetable"
|-
! Field
! Type
! Default
! Info
|-
| id
| int(10)
| auto-incrementing
| The unique ID for this external blog.
|-
| userid
| int(10)
|
| The owner of the external blog
|-
| name
| char(255)
|
| A descriptive name for the external blog. Automatically fetched during initial import, can be overridden.
|-
| description
| text(small)
|
| A long description of the external blog. Automatically fetched during initial import, can be overridden.
|-
| url
| text(small)
|
| The URL to the external blog (e.g. http://moodle.org/rss.xml)
|-
| timemodified
| int(10)
|
|
|-
| timefetched
| int(10)
|
| The last time the entries from this external blog were fetched by Moodle.
|}

=== blog_association ===

{| class="nicetable"
|-
! Field
! Type
! Default
! Info
|-
| id
| int(10)
| auto-incrementing
| The unique ID for this blog entry<->contextid association.
|-
| contextid
| int(10)
|
| The context id defined in context table - identifies the instance of the course or plugin associated with the blog entry.
|-
| blogid
| int(10)
|
| The id of the blog entry (from the post table) being associated with a course or module instance
|}

== Upgrade process ==
The only task required by the upgrade process is to install the new DB tables.

== See also ==
*[[Development:Blogs|Early wishlist]]
*[[Student_projects/Blog_improvements|2008 GSoC project addressing some of these improvements]]

Development:Blog 2.0

2009-09-30T06:59:11Z

Nicolasconnault: /* Associations */

{{Work in progress}}{{Moodle 2.0}}

* '''PROJECT STATE: Coding'''
* '''MAIN TRACKER ISSUE''': MDL-19676 Blog 2.0 improvements
* '''DISCUSSION AND COMMENTS''': http://moodle.org/mod/forum/discuss.php?d=133348

== Description of improvements ==
=== Who can view blog entries? ===
Blog entries are either in draft mode (only the author can view it), or in public mode. In public mode, everyone on the entire site can view the blog entry.

At one stage in 2.0 development there was an attempt to restrict who can view certain blog entries, based on course enrolment and capabilities. However, after extensive discussion and feasibility testing it became clear that this would lead to serious performance and usability issues, and would turn the blog into something more akin to a forum. It was thus decided to make all blogs public. (See MDL-19676)

An admin setting can allow for blog entries to be accessible by non-logged-in users, for the purpose of publishing and RSS feed aggregation.

=== Associations ===
A blog entry can optionally be associated with a course. This makes it possible for a user to blog "about" that course. All blog entries associated in that way can be viewed on a page like blog/index.php?courseid=3. This type of filtering of blog entries does not take into account course enrolments.

Additionally, blog entries can be associated with activity modules, in which case the blog entry is automatically associated with the module's course.

This requires the creation of a new table, in which the associations are recorded.
Tracker issue: MDL-14408

Capabilities:
*moodle/blog:associatecourse
*moodle/blog:associatemodule

=== Improved navigation ===
Before 2.0, the navigation for any listing of blog entries was either "Site > User > Blogs" (for a user's blog entries) or "Site > Blogs" for the whole site's blog entries, optionally filtered by tag. With the new association features, we need a better way to display what type of blog listing we are looking at, based on the parameters passed to blog/index.php. The navigation should also reflect additional filters such as tag and search.

=== External blogs ===
A user can import blog entries into Moodle from external blogs. The external blog's entries are copied into Moodle when the external blog URL is entered, and a cron task periodically checks these external blogs to copy new entries not yet entered in Moodle. The period of time between checks can be adjusted as an admin setting.

These external blogs are a user preference, and two types of tags can be added to each of them: "External tags" and "Moodle tags":
*External tags are used to filter the external blog entries that get copied into Moodle. They must match the tags used by that external blog.
*Moodle tags are automatically added to each blog entry copied into Moodle from an external blog that uses such tags. This makes it easier to distinguish which of a user's blog entries come from an external blog.

This requires the creation of a new DB table.
Tracker issue: MDL-19683

=== Search blog entries ===
It is now possible to search blog entries using a search box. The results maintain the current context, so that if you are viewing a list of blog entries for a particular user, entering a term in the search box will return only the blog entries for that user that match the search term. The search term also appears in the navigation breadcrumbs.

Tracker issue: MDL-19686

=== Contextual blog menu ===
Previously, the "blog menu" block was the same on every page on which it appeared. In 2.0 it changes depending on which page you are. For example, if you are on course/view.php, it will include a link to blog entries associated with that course. Also, the link for adding a new entry will include the courseid, making the course association automatically pre-selected in the blog entry edit form.

Tracker issue: MDL-19687

=== File attachments ===
The [[Development:File_API|new file manager]] must be implemented to allow for multiple file attachments per blog entry.

Tracker issue: MDL-19744

=== Comments ===
The new [[Development:Comments_2.0|Comments API]] makes it possible for anyone having the correct capability to comment on blog entries.

Tracker issue: MDL-8776

=== New "Recent blog entries" block ===
This block can be configured to display the last N blog entries, filtered by context. For example, if you are viewing an assignment activity, this block would display the last N blog entries that are associated with that assignment.

Tracker issue: MDL-19688

== Potential problems and limitations ==

== DB Structure ==
2 new tables need to be added: blog_external and blog_association

=== blog_external ===

{| class="nicetable"
|-
! Field
! Type
! Default
! Info
|-
| id
| int(10)
| auto-incrementing
| The unique ID for this external blog.
|-
| userid
| int(10)
|
| The owner of the external blog
|-
| name
| char(255)
|
| A descriptive name for the external blog. Automatically fetched during initial import, can be overridden.
|-
| description
| text(small)
|
| A long description of the external blog. Automatically fetched during initial import, can be overridden.
|-
| url
| text(small)
|
| The URL to the external blog (e.g. http://moodle.org/rss.xml)
|-
| timemodified
| int(10)
|
|
|-
| timefetched
| int(10)
|
| The last time the entries from this external blog were fetched by Moodle.
|}

=== blog_association ===

{| class="nicetable"
|-
! Field
! Type
! Default
! Info
|-
| id
| int(10)
| auto-incrementing
| The unique ID for this blog entry<->contextid association.
|-
| contextid
| int(10)
|
| The context id defined in context table - identifies the instance of the course or plugin associated with the blog entry.
|-
| blogid
| int(10)
|
| The id of the blog entry (from the post table) being associated with a course or module instance
|}

== Upgrade process ==
The only task required by the upgrade process is to install the new DB tables.

== See also ==
*[[Development:Blogs|Early wishlist]]
*[[Student_projects/Blog_improvements|2008 GSoC project addressing some of these improvements]]

Development:Using the File API in Moodle forms

2009-09-25T08:48:49Z

Nicolasconnault: Add section on gotchas

{{Moodle 2.0}}

This document shows you exactly how to use Moodle forms to get files from users in a standard and secure way.

==Overview==

In Moodle 2.0 all files are stored in a central database accessible via the [[Development:File API|File API]], and every file is associated with a "file area" in Moodle, such as a particular module.

A common use case is to provide a form (using Moodle's [[Development:lib/formslib.php|Forms API]]) which allows users to upload or import files as attachments or media embedded into HTML.

Normally this works like this:
# User starts creation or re-edits an existing item in Moodle (eg forum post, resource, glossary entry etc)
# User presses some sort of button to browse for new files to attach or embed
# User sees our "Choose file..." dialog, which contains one or more repository instances.
# User chooses a file, the [[Development:Repository API|Repository API]] takes care of copying the file into a "draft file area" within Moodle
# File appears in the text or as an attachment in the form.
# When the user hits save, the [[Development:File API|File API]] is invoked to move the file from the draft file area into a permanent file area associated with that data

This document shows you exactly how to use Moodle forms to interact with users in a standard and secure way.

If you just want to write code to manipulate Moodle files internally (without user input) then see [[Development:Using_the_File_API]].

==Form elements==

In Moodle 2.0 there are three file-related form elements for interacting with users:

# filemanager - the way to attach one or more files as a set
# editor - the way to specify a textarea with a HTML editor, and all the handling of images and movies within that HTML
# filepicker - a way to specify one file for the case when you want to process the file and throw it away

In Moodle 1.9 there were two other types which are now '''deprecated''' (they work, but please do not use these anymore)
# file - used to just allow a normal file upload from the desktop only.
# htmleditor - this old method of embedding a HTML editor in a textarea is not able to support repositories etc.

===filepicker===

File picker (''filepicker'') is a direct replacement of the older ''file'' formslib element.

It is intended for situations when you want the user to upload '''one''' file so you can process it and delete it, such as when you are importing data from a CSV file.

==== Using the filepicker element ====

<code php>
$mform->addElement('filepicker', 'userfile', get_string('file'), null, array('maxbytes' => $maxbytes, 'filetypes' => '*'));
</code>

==== Obtain the chosen file ====

The API for getting file contents is exactly the same as for ''file'' element.

<code php>
$content = $mform->get_file_content('userfile');
</code>

=== filemanager ===

The File Manager element improves on file picker by allowing you to manage more than one file. It is expected that the files will be stored permanently for future use (such as forum and glossary attachments).

==== Add file manager element ====

Example:
<code php>
$mform->addElement('filemanager', 'attachments', get_string('attachment', 'moodle'), null,
array('subdirs' => 0, 'maxbytes' => $maxbytes, 'maxfiles' => 50, 'filetypes' => array('document') ));
</code>

Here are the fields for filemanager:

;'filemanager':This is a filemanager element :)
;elementname:The unique name of the element in the form
;elementlabel:The label string that users see
;attributes:(leave it as null)
;options: an array of further options for the filepicker (see below)

The options array can contain:

;subdirs:(Default 0) Are subdirectories allowed? (true or false)
;maxbytes:(Default 0) Restricts the total size of all the files.
;maxfiles:(Default -1) Restricts the total number of files.
;filetypes:(Default *) You can specify what file types are accepted by filemanager. All current file types are listed in this file: [http://cvs.moodle.org/moodle/lib/file/file_types.mm moodle/lib/file/file_types.mm]. This is a [http://freemind.sourceforge.net/wiki/index.php/Main_Page freemind] file: if it is edited the changes will be immediately reflected in Moodle. Example usage: '''array('audio', 'video', 'documents')''', you can include file extensions as well, for example: '''array('*.txt', '*.jpg', 'audio')'''.

==== Load existing files into draft area ====

<code php>
if (empty($entry->id)) {
$entry = new object();
$entry->id = null;
}

$draftitemid = file_get_submitted_draft_itemid('attachments');
file_prepare_draft_area($draftitemid, $context->id, 'glossary_attachment', $entry->id, array('subdirs' => 0, 'maxbytes' => $maxbytes, 'maxfiles' => 50));
$entry->attachments = $draftitemid;

$mform->set_data($entry);

</code>

==== Store updated set of files ====

<code php>
if ($data = $mform->get_data()) {
// ... store or update $entry
file_save_draft_area_files($data->attachments, $context->id, 'glossary_attachment', $entry->id, array('subdirs' => 0, 'maxbytes' => $maxbytes, 'maxfiles' => 50));
}
</code>

===editor===
There are two way for using of editor element in code, the first one is easier but expects some standardized fields. The second method is more low level.

====Simple use====
# name database fields: ''textfield'', ''textfieldformat'' (and ''textfieldtrust'' if required)
# create options array <code php>$textfieldoptions = array('trusttext'=>true, 'subdirs'=>true, 'maxfiles'=>$maxfiles, 'maxbytes'=>$maxbytes);</code>
# add editor ''textfield_editor'' to moodle form, pass options through custom data in form constructor, set $data->id to null if data not exist yet <code php>$mform->addElement('editor', 'textfield_editor', get_string('fieldname', 'somemodule'), null, $textfieldoptions);</code>
# prepare data <code php>$data = file_prepare_standard_editor($data, 'textfield', $textfieldoptions, $context, 'somemodule_somearea', $data->id);</code>
# get submitted data and after inserting/updating of data <code php>$data = file_postupdate_standard_editor($data, 'textfield', $textfieldoptions, $context, 'somemodule_somearea', $data->id);</code>

Real world examples are in mod/glossary/edit.php and mod/glossary/comment.php

====Low level use====

When using editor element you need to preprocess and postprocess the data:
# detect if form was already submitted (usually means draft is area already exists) - ''file_get_submitted_draft_itemid()''
# prepare draft file area, temporary storage of all files attached to the text - ''file_prepare_draft_area()''
# convert encoded relative links to absolute links - ''file_prepare_draft_area()''
# create form and set current data
# after submission the changed files must be merged back into original area - ''file_save_draft_area_files()''
# absolute links have to be replaced by relative links - ''file_save_draft_area_files()''

=====Replace old htmleditor with editor=====

The file picker has been integrated with with TinyMCE to make the editor element. This new element should support all types on editors and should be able to switch them on-the-fly. Instances of the old htmleditor element in your forms should be replaced by the new editor element, this may need adding of new format and trusttext columns. For example:
<code php>
$mform->addElement('editor', 'entry', get_string('definition', 'glossary'), null,
array('maxfiles' => EDITOR_UNLIMITED_FILES, 'filearea' => 'glossary_entry'));
</code>
The editor element can take following options: maxfiles, maxbytes, filearea, subdirs and changeformat. Please note that the embedded files is optional feature and is not expected be used everywhere.

'''Note''': the editor element now includes text format option. You should no longer use the separate format element type.

=====Prepare current data - text and files=====

<code php>
if (empty($entry->id)) {
$entry = new object();
$entry->id = null;
$entry->definition = '';
$entry->format = FORMAT_HTML;
}

$draftid_editor = file_get_submitted_draft_itemid('entry');
$currenttext = file_prepare_draft_area($draftid_editor, $context->id, 'glossary_entry', $entry->id, array('subdirs'=>true), $entry->definition);
$entry->entry = array('text'=>$currenttext, 'format'=>$entry->format, 'itemid'=>$draftid_editor);

$mform->set_data($entry);
</code>

If there are multiple files, they will share the same itemid.

=====Obtain text, format and save draft files=====

To retrieve editor content, you need to use following code:

<code php>
if ($fromform = $mform->get_data()) {
// content of editor
$messagetext = $fromform->entry['text'];
// format of content
$messageformat = $fromform->entry['format'];
}
</code>

When a user selects a file using the file picker, the file is initially stored in a draft file area, and a URL is inserted into the HTML in the editor that lets the person editing the content (but no one else) see the file.

When the user submits the form, we then need to save the draft files to the correct place in permanent storage. (Just like you have to call $DB->update_record('tablename', $data); to have the other parts of the form submission stored correctly.)

The save_files_from_draft_area function and replace absolute links with internal relative links do:
<code php>
$messagetext = file_save_draft_area_files($draftid_editor, $context->id, 'glossary_entry', $entry->id, array('subdirs'=>true), $messagetext);
</code>
; $context->id, 'proper_file_area' and $entry->id : correspond to the contextid, filearea and itemid columns in the [[Development:File_API#Table:_files|files table]].
; $messagetext : this is the message text. As the files are saved to the real file area, the URLs in this content are rewritten.

All URLs in content that point to files managed to the File API are converted to a form that starts '@@PLUGINFILE@@/' before the content is stored in the database. That is what we mean by rewriting.

== File serving==

=== Convert internal relative links to absolute links ===

Before text content is displayed to the user, any URLs in the '@@PLUGINFILE@@/' form in the content need to be rewritten to the real URL where the user can access the files.
<code php>
$messagetext = file_rewrite_pluginfile_urls($messagetext, 'pluginfile.php',
"$context->id/proper_file_area/$itemid/");
</code>
; $messagetext : is the content containing the @@PLUGINFILE@@ URLs from the database.
; 'pluginfile.php' : there are a number of different scripts that can serve files with different permissions checks. You need to specify which one to use.
; "$context->id/proper_file_area/$itemid/" : uniquely identifies the file area, as before.

=== Implement file serving access control ===

Attachments and embedded images should have the same access control like the text itself, in majority of cases these files are served using pluginfile.php. Access control is defined in ''module/lib.php'' file in function ''module_pluginfile()''.

== File browsing support ==
Only owner of each file area is allowed to use low level File API function to access files, other parts of Moodle should use file browsing API.

Activities may specify browsing support in own module/lib.php file by implementing functions module_get_file_areas() and module_get_file_info().

== Upgrading your code ==
Here I will attempt to describe some simple steps you can take to upgrade your file-handling form elements from pre-2.0 code to 2.0. We will use the example of glossary, since it has been used above.

=== Preparing your options ===
Unless you are happy with the defaults, you will need to define an array of options for each file-handling form element. You could define it at different places, but it's best to put it in one place and make the array(s) available to other files if they need it. In the majority of cases, this will be in a file like edit.php

Previous code in mod/glossary/edit.php:
<code php>
$mform =& new mod_glossary_entry_form(null, compact('cm', 'glossary', 'hook', 'mode', 'e', 'context'));
</code>
New code:
<code php>
$maxbytes = $course->maxbytes; // Could also use $CFG->maxbytes if you are not coding within a course context
$definitionoptions = array('subdirs'=>false, 'maxfiles'=>99, 'maxbytes'=>$maxbytes, 'trusttext'=>true, 'context'=>$context);
$attachmentoptions = array('subdirs'=>false, 'maxfiles'=>99, 'maxbytes'=>$maxbytes);
$mform = new mod_glossary_entry_form(null, array(
'current'=>$entry,
'cm'=>$cm,
'glossary'=>$glossary,
'definitionoptions'=>$definitionoptions,
'attachmentoptions'=>$attachmentoptions));
</code>
Note that the data being passed to the form constructor have changed also, but this is not part of the file API changes, I just include them to avoid confusion.

These options are for the htmleditor (definition field) and the filemanager (attachment field). They are used by a file called edit_form.php.

=== Element preparation ===
Before we look at this, however, we need to "prepare" the elements so that they can correctly display existing embedded images and attached files when you are editing a record instead of just creating one. So, let's take the code we've got so far in edit.php and add to it:

Currently upgraded code in edit.php:
<code php>
$mform = new mod_glossary_entry_form(null, array(
'current'=>$entry,
'cm'=>$cm,
'glossary'=>$glossary,
'definitionoptions'=>$definitionoptions,
'attachmentoptions'=>$attachmentoptions));
</code>
New code with element preparation:
<code php>
$entry = file_prepare_standard_editor($entry, 'definition', $definitionoptions, $context, 'glossary_entry', $entry->id);
$entry = file_prepare_standard_filemanager($entry, 'attachment', $attachmentoptions, $context, 'glossary_attachment', $entry->id);
$mform = new mod_glossary_entry_form(null, array(
'current'=>$entry,
'cm'=>$cm,
'glossary'=>$glossary,
'definitionoptions'=>$definitionoptions,
'attachmentoptions'=>$attachmentoptions));
</code>
Things to note:
* $entry in this case is simply a stdClass object which may either represent a new glossary entry or an existing one.
* $entry->id must be the unique identifier for the current object. If we are creating a new entry, it will be null, but in all cases it must be defined.
* These two functions (file_prepare_standard_editor and file_prepare_standard_filemanager) are shortcuts functions that take care of some of the tedious setting up for you, but they make a couple of assumptions:
*# You '''must''' name the form element as {element}_editor or {element}_filemanager (see next section)
*# You '''must''' have at least the following fields in the database: {element} and {element}summary, as described earlier in this documentation

We can now look at the upgrades needed in the form definition file.

=== Form definition ===
Previous code in mod/glossary/edit_form.php:
<code php>
$mform->addElement('htmleditor', 'definition', get_string('definition', 'glossary'), array('rows'=>20));
$mform->setType('definition', PARAM_RAW);
$mform->addRule('definition', null, 'required', null, 'client');
$mform->setHelpButton('definition', array('writing', 'richtext'), false, 'editorhelpbutton');
$mform->addElement('format');
// a bit further...
$this->set_upload_manager(new upload_manager('attachment', true, false, $COURSE, false, 0, true, true, false));
$mform->addElement('file', 'attachment', get_string('attachment', 'forum'));
$mform->setHelpButton('attachment', array('attachment', get_string('attachment', 'glossary'), 'glossary'));
</code>
New code:
<code php>
$definitionoptions = $this->_customdata['definitionoptions'];
$attachmentoptions = $this->_customdata['attachmentoptions'];
// a bit further...
$mform->addElement('editor', 'definition_editor', get_string('definition', 'glossary'), null, $definitionoptions);
$mform->setType('definition_editor', PARAM_RAW);
$mform->addRule('definition_editor', get_string('required'), 'required', null, 'client');
// a bit further...
$mform->addElement('filemanager', 'attachment_filemanager', get_string('attachment', 'glossary'), null, $attachmentoptions);
$mform->setHelpButton('attachment_filemanager', array('attachment2', get_string('attachment', 'glossary'), 'glossary'));
</code>

Note the following:
* The format element and the help button are no longer required for the HTML editor element
* The name of the form element needs to be changed by adding '_editor' or '_manager' to the original name. This is a naming convention that is used by a couple of functions we will look at shortly

=== Handling submitted data ===
The final step is to handle the submitted data properly, i.e. retrieve the files and save them to disk, associating them with the record we have just created (a glossary entry in our example). This happens in edit.php:

Previous code in edit.php:
<code php>
// Section that updates an entry:
$todb->id = $e;
$dir = glossary_file_area_name($todb);
if ($mform->save_files($dir) and $newfilename = $mform->get_new_filename()) {
$todb->attachment = $newfilename;
}

// Section that adds an entry:
if ($todb->id = insert_record("glossary_entries", $todb)) {
$e = $todb->id;
$dir = glossary_file_area_name($todb);
if ($mform->save_files($dir) and $newfilename = $mform->get_new_filename()) {
set_field("glossary_entries", "attachment", $newfilename, "id", $todb->id);
}
}
</code>
New code:
<code php>
// $todb was renamed to $entry, and the code was refactored
// so that the file-handling code is only used once for either an add or an update action.
// If an entry is being added, $DB->insert() has already been called, so we have a valid $entry->id
$entry = file_postupdate_standard_editor($entry, 'definition', $definitionoptions, $context, 'glossary_entry', $entry->id);
$entry = file_postupdate_standard_filemanager($entry, 'attachment', $attachmentoptions, $context, 'glossary_attachment', $entry->id);
// store the updated value values
$DB->update_record('glossary_entries', $entry);
</code>
Things to note:
* If you are adding a new record, you will still need to call update_record after calling the file_postupdate* functions

=== Gotchas ===
A few things to keep in mind:
* Make sure that you instantiate the moodle form before any call to $OUTPUT->header()

== See also ==

* [[Development:File API]]
* [[Development:Using the file API]]
* [[Development:Repository API]]
* [[Development:Portfolio API]]
* MDL-14589 - File API Meta issue

{{CategoryDeveloper}}
[[Category:Files]]
[[Category:Repositories]]

Development:Using the File API in Moodle forms

2009-09-25T08:35:10Z

Nicolasconnault: /* Preparing your options */

{{Moodle 2.0}}

This document shows you exactly how to use Moodle forms to get files from users in a standard and secure way.

==Overview==

In Moodle 2.0 all files are stored in a central database accessible via the [[Development:File API|File API]], and every file is associated with a "file area" in Moodle, such as a particular module.

A common use case is to provide a form (using Moodle's [[Development:lib/formslib.php|Forms API]]) which allows users to upload or import files as attachments or media embedded into HTML.

Normally this works like this:
# User starts creation or re-edits an existing item in Moodle (eg forum post, resource, glossary entry etc)
# User presses some sort of button to browse for new files to attach or embed
# User sees our "Choose file..." dialog, which contains one or more repository instances.
# User chooses a file, the [[Development:Repository API|Repository API]] takes care of copying the file into a "draft file area" within Moodle
# File appears in the text or as an attachment in the form.
# When the user hits save, the [[Development:File API|File API]] is invoked to move the file from the draft file area into a permanent file area associated with that data

This document shows you exactly how to use Moodle forms to interact with users in a standard and secure way.

If you just want to write code to manipulate Moodle files internally (without user input) then see [[Development:Using_the_File_API]].

==Form elements==

In Moodle 2.0 there are three file-related form elements for interacting with users:

# filemanager - the way to attach one or more files as a set
# editor - the way to specify a textarea with a HTML editor, and all the handling of images and movies within that HTML
# filepicker - a way to specify one file for the case when you want to process the file and throw it away

In Moodle 1.9 there were two other types which are now '''deprecated''' (they work, but please do not use these anymore)
# file - used to just allow a normal file upload from the desktop only.
# htmleditor - this old method of embedding a HTML editor in a textarea is not able to support repositories etc.

===filepicker===

File picker (''filepicker'') is a direct replacement of the older ''file'' formslib element.

It is intended for situations when you want the user to upload '''one''' file so you can process it and delete it, such as when you are importing data from a CSV file.

==== Using the filepicker element ====

<code php>
$mform->addElement('filepicker', 'userfile', get_string('file'), null, array('maxbytes' => $maxbytes, 'filetypes' => '*'));
</code>

==== Obtain the chosen file ====

The API for getting file contents is exactly the same as for ''file'' element.

<code php>
$content = $mform->get_file_content('userfile');
</code>

=== filemanager ===

The File Manager element improves on file picker by allowing you to manage more than one file. It is expected that the files will be stored permanently for future use (such as forum and glossary attachments).

==== Add file manager element ====

Example:
<code php>
$mform->addElement('filemanager', 'attachments', get_string('attachment', 'moodle'), null,
array('subdirs' => 0, 'maxbytes' => $maxbytes, 'maxfiles' => 50, 'filetypes' => array('document') ));
</code>

Here are the fields for filemanager:

;'filemanager':This is a filemanager element :)
;elementname:The unique name of the element in the form
;elementlabel:The label string that users see
;attributes:(leave it as null)
;options: an array of further options for the filepicker (see below)

The options array can contain:

;subdirs:(Default 0) Are subdirectories allowed? (true or false)
;maxbytes:(Default 0) Restricts the total size of all the files.
;maxfiles:(Default -1) Restricts the total number of files.
;filetypes:(Default *) You can specify what file types are accepted by filemanager. All current file types are listed in this file: [http://cvs.moodle.org/moodle/lib/file/file_types.mm moodle/lib/file/file_types.mm]. This is a [http://freemind.sourceforge.net/wiki/index.php/Main_Page freemind] file: if it is edited the changes will be immediately reflected in Moodle. Example usage: '''array('audio', 'video', 'documents')''', you can include file extensions as well, for example: '''array('*.txt', '*.jpg', 'audio')'''.

==== Load existing files into draft area ====

<code php>
if (empty($entry->id)) {
$entry = new object();
$entry->id = null;
}

$draftitemid = file_get_submitted_draft_itemid('attachments');
file_prepare_draft_area($draftitemid, $context->id, 'glossary_attachment', $entry->id, array('subdirs' => 0, 'maxbytes' => $maxbytes, 'maxfiles' => 50));
$entry->attachments = $draftitemid;

$mform->set_data($entry);

</code>

==== Store updated set of files ====

<code php>
if ($data = $mform->get_data()) {
// ... store or update $entry
file_save_draft_area_files($data->attachments, $context->id, 'glossary_attachment', $entry->id, array('subdirs' => 0, 'maxbytes' => $maxbytes, 'maxfiles' => 50));
}
</code>

===editor===
There are two way for using of editor element in code, the first one is easier but expects some standardized fields. The second method is more low level.

====Simple use====
# name database fields: ''textfield'', ''textfieldformat'' (and ''textfieldtrust'' if required)
# create options array <code php>$textfieldoptions = array('trusttext'=>true, 'subdirs'=>true, 'maxfiles'=>$maxfiles, 'maxbytes'=>$maxbytes);</code>
# add editor ''textfield_editor'' to moodle form, pass options through custom data in form constructor, set $data->id to null if data not exist yet <code php>$mform->addElement('editor', 'textfield_editor', get_string('fieldname', 'somemodule'), null, $textfieldoptions);</code>
# prepare data <code php>$data = file_prepare_standard_editor($data, 'textfield', $textfieldoptions, $context, 'somemodule_somearea', $data->id);</code>
# get submitted data and after inserting/updating of data <code php>$data = file_postupdate_standard_editor($data, 'textfield', $textfieldoptions, $context, 'somemodule_somearea', $data->id);</code>

Real world examples are in mod/glossary/edit.php and mod/glossary/comment.php

====Low level use====

When using editor element you need to preprocess and postprocess the data:
# detect if form was already submitted (usually means draft is area already exists) - ''file_get_submitted_draft_itemid()''
# prepare draft file area, temporary storage of all files attached to the text - ''file_prepare_draft_area()''
# convert encoded relative links to absolute links - ''file_prepare_draft_area()''
# create form and set current data
# after submission the changed files must be merged back into original area - ''file_save_draft_area_files()''
# absolute links have to be replaced by relative links - ''file_save_draft_area_files()''

=====Replace old htmleditor with editor=====

The file picker has been integrated with with TinyMCE to make the editor element. This new element should support all types on editors and should be able to switch them on-the-fly. Instances of the old htmleditor element in your forms should be replaced by the new editor element, this may need adding of new format and trusttext columns. For example:
<code php>
$mform->addElement('editor', 'entry', get_string('definition', 'glossary'), null,
array('maxfiles' => EDITOR_UNLIMITED_FILES, 'filearea' => 'glossary_entry'));
</code>
The editor element can take following options: maxfiles, maxbytes, filearea, subdirs and changeformat. Please note that the embedded files is optional feature and is not expected be used everywhere.

'''Note''': the editor element now includes text format option. You should no longer use the separate format element type.

=====Prepare current data - text and files=====

<code php>
if (empty($entry->id)) {
$entry = new object();
$entry->id = null;
$entry->definition = '';
$entry->format = FORMAT_HTML;
}

$draftid_editor = file_get_submitted_draft_itemid('entry');
$currenttext = file_prepare_draft_area($draftid_editor, $context->id, 'glossary_entry', $entry->id, array('subdirs'=>true), $entry->definition);
$entry->entry = array('text'=>$currenttext, 'format'=>$entry->format, 'itemid'=>$draftid_editor);

$mform->set_data($entry);
</code>

If there are multiple files, they will share the same itemid.

=====Obtain text, format and save draft files=====

To retrieve editor content, you need to use following code:

<code php>
if ($fromform = $mform->get_data()) {
// content of editor
$messagetext = $fromform->entry['text'];
// format of content
$messageformat = $fromform->entry['format'];
}
</code>

When a user selects a file using the file picker, the file is initially stored in a draft file area, and a URL is inserted into the HTML in the editor that lets the person editing the content (but no one else) see the file.

When the user submits the form, we then need to save the draft files to the correct place in permanent storage. (Just like you have to call $DB->update_record('tablename', $data); to have the other parts of the form submission stored correctly.)

The save_files_from_draft_area function and replace absolute links with internal relative links do:
<code php>
$messagetext = file_save_draft_area_files($draftid_editor, $context->id, 'glossary_entry', $entry->id, array('subdirs'=>true), $messagetext);
</code>
; $context->id, 'proper_file_area' and $entry->id : correspond to the contextid, filearea and itemid columns in the [[Development:File_API#Table:_files|files table]].
; $messagetext : this is the message text. As the files are saved to the real file area, the URLs in this content are rewritten.

All URLs in content that point to files managed to the File API are converted to a form that starts '@@PLUGINFILE@@/' before the content is stored in the database. That is what we mean by rewriting.

== File serving==

=== Convert internal relative links to absolute links ===

Before text content is displayed to the user, any URLs in the '@@PLUGINFILE@@/' form in the content need to be rewritten to the real URL where the user can access the files.
<code php>
$messagetext = file_rewrite_pluginfile_urls($messagetext, 'pluginfile.php',
"$context->id/proper_file_area/$itemid/");
</code>
; $messagetext : is the content containing the @@PLUGINFILE@@ URLs from the database.
; 'pluginfile.php' : there are a number of different scripts that can serve files with different permissions checks. You need to specify which one to use.
; "$context->id/proper_file_area/$itemid/" : uniquely identifies the file area, as before.

=== Implement file serving access control ===

Attachments and embedded images should have the same access control like the text itself, in majority of cases these files are served using pluginfile.php. Access control is defined in ''module/lib.php'' file in function ''module_pluginfile()''.

== File browsing support ==
Only owner of each file area is allowed to use low level File API function to access files, other parts of Moodle should use file browsing API.

Activities may specify browsing support in own module/lib.php file by implementing functions module_get_file_areas() and module_get_file_info().

== Upgrading your code ==
Here I will attempt to describe some simple steps you can take to upgrade your file-handling form elements from pre-2.0 code to 2.0. We will use the example of glossary, since it has been used above.

=== Preparing your options ===
Unless you are happy with the defaults, you will need to define an array of options for each file-handling form element. You could define it at different places, but it's best to put it in one place and make the array(s) available to other files if they need it. In the majority of cases, this will be in a file like edit.php

Previous code in mod/glossary/edit.php:
<code php>
$mform =& new mod_glossary_entry_form(null, compact('cm', 'glossary', 'hook', 'mode', 'e', 'context'));
</code>
New code:
<code php>
$maxbytes = $course->maxbytes; // Could also use $CFG->maxbytes if you are not coding within a course context
$definitionoptions = array('subdirs'=>false, 'maxfiles'=>99, 'maxbytes'=>$maxbytes, 'trusttext'=>true, 'context'=>$context);
$attachmentoptions = array('subdirs'=>false, 'maxfiles'=>99, 'maxbytes'=>$maxbytes);
$mform = new mod_glossary_entry_form(null, array(
'current'=>$entry,
'cm'=>$cm,
'glossary'=>$glossary,
'definitionoptions'=>$definitionoptions,
'attachmentoptions'=>$attachmentoptions));
</code>
Note that the data being passed to the form constructor have changed also, but this is not part of the file API changes, I just include them to avoid confusion.

These options are for the htmleditor (definition field) and the filemanager (attachment field). They are used by a file called edit_form.php.

=== Element preparation ===
Before we look at this, however, we need to "prepare" the elements so that they can correctly display existing embedded images and attached files when you are editing a record instead of just creating one. So, let's take the code we've got so far in edit.php and add to it:

Currently upgraded code in edit.php:
<code php>
$mform = new mod_glossary_entry_form(null, array(
'current'=>$entry,
'cm'=>$cm,
'glossary'=>$glossary,
'definitionoptions'=>$definitionoptions,
'attachmentoptions'=>$attachmentoptions));
</code>
New code with element preparation:
<code php>
$entry = file_prepare_standard_editor($entry, 'definition', $definitionoptions, $context, 'glossary_entry', $entry->id);
$entry = file_prepare_standard_filemanager($entry, 'attachment', $attachmentoptions, $context, 'glossary_attachment', $entry->id);
$mform = new mod_glossary_entry_form(null, array(
'current'=>$entry,
'cm'=>$cm,
'glossary'=>$glossary,
'definitionoptions'=>$definitionoptions,
'attachmentoptions'=>$attachmentoptions));
</code>
Things to note:
* $entry in this case is simply a stdClass object which may either represent a new glossary entry or an existing one.
* $entry->id must be the unique identifier for the current object. If we are creating a new entry, it will be null, but in all cases it must be defined.
* These two functions (file_prepare_standard_editor and file_prepare_standard_filemanager) are shortcuts functions that take care of some of the tedious setting up for you, but they make a couple of assumptions:
*# You '''must''' name the form element as {element}_editor or {element}_filemanager (see next section)
*# You '''must''' have at least the following fields in the database: {element} and {element}summary, as described earlier in this documentation

We can now look at the upgrades needed in the form definition file.

=== Form definition ===
Previous code in mod/glossary/edit_form.php:
<code php>
$mform->addElement('htmleditor', 'definition', get_string('definition', 'glossary'), array('rows'=>20));
$mform->setType('definition', PARAM_RAW);
$mform->addRule('definition', null, 'required', null, 'client');
$mform->setHelpButton('definition', array('writing', 'richtext'), false, 'editorhelpbutton');
$mform->addElement('format');
// a bit further...
$this->set_upload_manager(new upload_manager('attachment', true, false, $COURSE, false, 0, true, true, false));
$mform->addElement('file', 'attachment', get_string('attachment', 'forum'));
$mform->setHelpButton('attachment', array('attachment', get_string('attachment', 'glossary'), 'glossary'));
</code>
New code:
<code php>
$definitionoptions = $this->_customdata['definitionoptions'];
$attachmentoptions = $this->_customdata['attachmentoptions'];
// a bit further...
$mform->addElement('editor', 'definition_editor', get_string('definition', 'glossary'), null, $definitionoptions);
$mform->setType('definition_editor', PARAM_RAW);
$mform->addRule('definition_editor', get_string('required'), 'required', null, 'client');
// a bit further...
$mform->addElement('filemanager', 'attachment_filemanager', get_string('attachment', 'glossary'), null, $attachmentoptions);
$mform->setHelpButton('attachment_filemanager', array('attachment2', get_string('attachment', 'glossary'), 'glossary'));
</code>

Note the following:
* The format element and the help button are no longer required for the HTML editor element
* The name of the form element needs to be changed by adding '_editor' or '_manager' to the original name. This is a naming convention that is used by a couple of functions we will look at shortly

=== Handling submitted data ===
The final step is to handle the submitted data properly, i.e. retrieve the files and save them to disk, associating them with the record we have just created (a glossary entry in our example). This happens in edit.php:

Previous code in edit.php:
<code php>
// Section that updates an entry:
$todb->id = $e;
$dir = glossary_file_area_name($todb);
if ($mform->save_files($dir) and $newfilename = $mform->get_new_filename()) {
$todb->attachment = $newfilename;
}

// Section that adds an entry:
if ($todb->id = insert_record("glossary_entries", $todb)) {
$e = $todb->id;
$dir = glossary_file_area_name($todb);
if ($mform->save_files($dir) and $newfilename = $mform->get_new_filename()) {
set_field("glossary_entries", "attachment", $newfilename, "id", $todb->id);
}
}
</code>
New code:
<code php>
// $todb was renamed to $entry, and the code was refactored
// so that the file-handling code is only used once for either an add or an update action.
// If an entry is being added, $DB->insert() has already been called, so we have a valid $entry->id
$entry = file_postupdate_standard_editor($entry, 'definition', $definitionoptions, $context, 'glossary_entry', $entry->id);
$entry = file_postupdate_standard_filemanager($entry, 'attachment', $attachmentoptions, $context, 'glossary_attachment', $entry->id);
// store the updated value values
$DB->update_record('glossary_entries', $entry);
</code>
Things to note:
* If you are adding a new record, you will still need to call update_record after calling the file_postupdate* functions

== See also ==

* [[Development:File API]]
* [[Development:Using the file API]]
* [[Development:Repository API]]
* [[Development:Portfolio API]]
* MDL-14589 - File API Meta issue

{{CategoryDeveloper}}
[[Category:Files]]
[[Category:Repositories]]

Development:Using the File API in Moodle forms

2009-09-25T07:42:02Z

Nicolasconnault: /* Submitted data handling */

{{Moodle 2.0}}

This document shows you exactly how to use Moodle forms to get files from users in a standard and secure way.

==Overview==

In Moodle 2.0 all files are stored in a central database accessible via the [[Development:File API|File API]], and every file is associated with a "file area" in Moodle, such as a particular module.

A common use case is to provide a form (using Moodle's [[Development:lib/formslib.php|Forms API]]) which allows users to upload or import files as attachments or media embedded into HTML.

Normally this works like this:
# User starts creation or re-edits an existing item in Moodle (eg forum post, resource, glossary entry etc)
# User presses some sort of button to browse for new files to attach or embed
# User sees our "Choose file..." dialog, which contains one or more repository instances.
# User chooses a file, the [[Development:Repository API|Repository API]] takes care of copying the file into a "draft file area" within Moodle
# File appears in the text or as an attachment in the form.
# When the user hits save, the [[Development:File API|File API]] is invoked to move the file from the draft file area into a permanent file area associated with that data

This document shows you exactly how to use Moodle forms to interact with users in a standard and secure way.

If you just want to write code to manipulate Moodle files internally (without user input) then see [[Development:Using_the_File_API]].

==Form elements==

In Moodle 2.0 there are three file-related form elements for interacting with users:

# filemanager - the way to attach one or more files as a set
# editor - the way to specify a textarea with a HTML editor, and all the handling of images and movies within that HTML
# filepicker - a way to specify one file for the case when you want to process the file and throw it away

In Moodle 1.9 there were two other types which are now '''deprecated''' (they work, but please do not use these anymore)
# file - used to just allow a normal file upload from the desktop only.
# htmleditor - this old method of embedding a HTML editor in a textarea is not able to support repositories etc.

===filepicker===

File picker (''filepicker'') is a direct replacement of the older ''file'' formslib element.

It is intended for situations when you want the user to upload '''one''' file so you can process it and delete it, such as when you are importing data from a CSV file.

==== Using the filepicker element ====

<code php>
$mform->addElement('filepicker', 'userfile', get_string('file'), null, array('maxbytes' => $maxbytes, 'filetypes' => '*'));
</code>

==== Obtain the chosen file ====

The API for getting file contents is exactly the same as for ''file'' element.

<code php>
$content = $mform->get_file_content('userfile');
</code>

=== filemanager ===

The File Manager element improves on file picker by allowing you to manage more than one file. It is expected that the files will be stored permanently for future use (such as forum and glossary attachments).

==== Add file manager element ====

Example:
<code php>
$mform->addElement('filemanager', 'attachments', get_string('attachment', 'moodle'), null,
array('subdirs' => 0, 'maxbytes' => $maxbytes, 'maxfiles' => 50, 'filetypes' => array('document') ));
</code>

Here are the fields for filemanager:

;'filemanager':This is a filemanager element :)
;elementname:The unique name of the element in the form
;elementlabel:The label string that users see
;attributes:(leave it as null)
;options: an array of further options for the filepicker (see below)

The options array can contain:

;subdirs:(Default 0) Are subdirectories allowed? (true or false)
;maxbytes:(Default 0) Restricts the total size of all the files.
;maxfiles:(Default -1) Restricts the total number of files.
;filetypes:(Default *) You can specify what file types are accepted by filemanager. All current file types are listed in this file: [http://cvs.moodle.org/moodle/lib/file/file_types.mm moodle/lib/file/file_types.mm]. This is a [http://freemind.sourceforge.net/wiki/index.php/Main_Page freemind] file: if it is edited the changes will be immediately reflected in Moodle. Example usage: '''array('audio', 'video', 'documents')''', you can include file extensions as well, for example: '''array('*.txt', '*.jpg', 'audio')'''.

==== Load existing files into draft area ====

<code php>
if (empty($entry->id)) {
$entry = new object();
$entry->id = null;
}

$draftitemid = file_get_submitted_draft_itemid('attachments');
file_prepare_draft_area($draftitemid, $context->id, 'glossary_attachment', $entry->id, array('subdirs' => 0, 'maxbytes' => $maxbytes, 'maxfiles' => 50));
$entry->attachments = $draftitemid;

$mform->set_data($entry);

</code>

==== Store updated set of files ====

<code php>
if ($data = $mform->get_data()) {
// ... store or update $entry
file_save_draft_area_files($data->attachments, $context->id, 'glossary_attachment', $entry->id, array('subdirs' => 0, 'maxbytes' => $maxbytes, 'maxfiles' => 50));
}
</code>

===editor===
There are two way for using of editor element in code, the first one is easier but expects some standardized fields. The second method is more low level.

====Simple use====
# name database fields: ''textfield'', ''textfieldformat'' (and ''textfieldtrust'' if required)
# create options array <code php>$textfieldoptions = array('trusttext'=>true, 'subdirs'=>true, 'maxfiles'=>$maxfiles, 'maxbytes'=>$maxbytes);</code>
# add editor ''textfield_editor'' to moodle form, pass options through custom data in form constructor, set $data->id to null if data not exist yet <code php>$mform->addElement('editor', 'textfield_editor', get_string('fieldname', 'somemodule'), null, $textfieldoptions);</code>
# prepare data <code php>$data = file_prepare_standard_editor($data, 'textfield', $textfieldoptions, $context, 'somemodule_somearea', $data->id);</code>
# get submitted data and after inserting/updating of data <code php>$data = file_postupdate_standard_editor($data, 'textfield', $textfieldoptions, $context, 'somemodule_somearea', $data->id);</code>

Real world examples are in mod/glossary/edit.php and mod/glossary/comment.php

====Low level use====

When using editor element you need to preprocess and postprocess the data:
# detect if form was already submitted (usually means draft is area already exists) - ''file_get_submitted_draft_itemid()''
# prepare draft file area, temporary storage of all files attached to the text - ''file_prepare_draft_area()''
# convert encoded relative links to absolute links - ''file_prepare_draft_area()''
# create form and set current data
# after submission the changed files must be merged back into original area - ''file_save_draft_area_files()''
# absolute links have to be replaced by relative links - ''file_save_draft_area_files()''

=====Replace old htmleditor with editor=====

The file picker has been integrated with with TinyMCE to make the editor element. This new element should support all types on editors and should be able to switch them on-the-fly. Instances of the old htmleditor element in your forms should be replaced by the new editor element, this may need adding of new format and trusttext columns. For example:
<code php>
$mform->addElement('editor', 'entry', get_string('definition', 'glossary'), null,
array('maxfiles' => EDITOR_UNLIMITED_FILES, 'filearea' => 'glossary_entry'));
</code>
The editor element can take following options: maxfiles, maxbytes, filearea, subdirs and changeformat. Please note that the embedded files is optional feature and is not expected be used everywhere.

'''Note''': the editor element now includes text format option. You should no longer use the separate format element type.

=====Prepare current data - text and files=====

<code php>
if (empty($entry->id)) {
$entry = new object();
$entry->id = null;
$entry->definition = '';
$entry->format = FORMAT_HTML;
}

$draftid_editor = file_get_submitted_draft_itemid('entry');
$currenttext = file_prepare_draft_area($draftid_editor, $context->id, 'glossary_entry', $entry->id, array('subdirs'=>true), $entry->definition);
$entry->entry = array('text'=>$currenttext, 'format'=>$entry->format, 'itemid'=>$draftid_editor);

$mform->set_data($entry);
</code>

If there are multiple files, they will share the same itemid.

=====Obtain text, format and save draft files=====

To retrieve editor content, you need to use following code:

<code php>
if ($fromform = $mform->get_data()) {
// content of editor
$messagetext = $fromform->entry['text'];
// format of content
$messageformat = $fromform->entry['format'];
}
</code>

When a user selects a file using the file picker, the file is initially stored in a draft file area, and a URL is inserted into the HTML in the editor that lets the person editing the content (but no one else) see the file.

When the user submits the form, we then need to save the draft files to the correct place in permanent storage. (Just like you have to call $DB->update_record('tablename', $data); to have the other parts of the form submission stored correctly.)

The save_files_from_draft_area function and replace absolute links with internal relative links do:
<code php>
$messagetext = file_save_draft_area_files($draftid_editor, $context->id, 'glossary_entry', $entry->id, array('subdirs'=>true), $messagetext);
</code>
; $context->id, 'proper_file_area' and $entry->id : correspond to the contextid, filearea and itemid columns in the [[Development:File_API#Table:_files|files table]].
; $messagetext : this is the message text. As the files are saved to the real file area, the URLs in this content are rewritten.

All URLs in content that point to files managed to the File API are converted to a form that starts '@@PLUGINFILE@@/' before the content is stored in the database. That is what we mean by rewriting.

== File serving==

=== Convert internal relative links to absolute links ===

Before text content is displayed to the user, any URLs in the '@@PLUGINFILE@@/' form in the content need to be rewritten to the real URL where the user can access the files.
<code php>
$messagetext = file_rewrite_pluginfile_urls($messagetext, 'pluginfile.php',
"$context->id/proper_file_area/$itemid/");
</code>
; $messagetext : is the content containing the @@PLUGINFILE@@ URLs from the database.
; 'pluginfile.php' : there are a number of different scripts that can serve files with different permissions checks. You need to specify which one to use.
; "$context->id/proper_file_area/$itemid/" : uniquely identifies the file area, as before.

=== Implement file serving access control ===

Attachments and embedded images should have the same access control like the text itself, in majority of cases these files are served using pluginfile.php. Access control is defined in ''module/lib.php'' file in function ''module_pluginfile()''.

== File browsing support ==
Only owner of each file area is allowed to use low level File API function to access files, other parts of Moodle should use file browsing API.

Activities may specify browsing support in own module/lib.php file by implementing functions module_get_file_areas() and module_get_file_info().

== Upgrading your code ==
Here I will attempt to describe some simple steps you can take to upgrade your file-handling form elements from pre-2.0 code to 2.0. We will use the example of glossary, since it has been used above.

=== Preparing your options ===
Unless you are happy with the defaults, you will need to define an array of options for each file-handling form element. You could define it at different places, but it's best to put it in one place and make the array(s) available to other files if they need it. In the majority of cases, this will be in a file like edit.php

Previous code in mod/glossary/edit.php:
<code php>
$mform =& new mod_glossary_entry_form(null, compact('cm', 'glossary', 'hook', 'mode', 'e', 'context'));
</code>
New code:
<code php>
$maxbytes = $course->maxbytes; // Could also use $CFG->maxbytes if you are not coding within a course context
$definitionoptions = array('trusttext'=>true, 'subdirs'=>false, 'maxfiles'=>99, 'maxbytes'=>$maxbytes, 'trusttext'=>true, 'context'=>$context);
$attachmentoptions = array('subdirs'=>false, 'maxfiles'=>99, 'maxbytes'=>$maxbytes);
$mform = new mod_glossary_entry_form(null, array(
'current'=>$entry,
'cm'=>$cm,
'glossary'=>$glossary,
'definitionoptions'=>$definitionoptions,
'attachmentoptions'=>$attachmentoptions));
</code>
Note that the data being passed to the form constructor have changed also, but this is not part of the file API changes, I just include them to avoid confusion.

These options are for the htmleditor (definition field) and the filemanager (attachment field). They are used by a file called edit_form.php.

=== Element preparation ===
Before we look at this, however, we need to "prepare" the elements so that they can correctly display existing embedded images and attached files when you are editing a record instead of just creating one. So, let's take the code we've got so far in edit.php and add to it:

Currently upgraded code in edit.php:
<code php>
$mform = new mod_glossary_entry_form(null, array(
'current'=>$entry,
'cm'=>$cm,
'glossary'=>$glossary,
'definitionoptions'=>$definitionoptions,
'attachmentoptions'=>$attachmentoptions));
</code>
New code with element preparation:
<code php>
$entry = file_prepare_standard_editor($entry, 'definition', $definitionoptions, $context, 'glossary_entry', $entry->id);
$entry = file_prepare_standard_filemanager($entry, 'attachment', $attachmentoptions, $context, 'glossary_attachment', $entry->id);
$mform = new mod_glossary_entry_form(null, array(
'current'=>$entry,
'cm'=>$cm,
'glossary'=>$glossary,
'definitionoptions'=>$definitionoptions,
'attachmentoptions'=>$attachmentoptions));
</code>
Things to note:
* $entry in this case is simply a stdClass object which may either represent a new glossary entry or an existing one.
* $entry->id must be the unique identifier for the current object. If we are creating a new entry, it will be null, but in all cases it must be defined.
* These two functions (file_prepare_standard_editor and file_prepare_standard_filemanager) are shortcuts functions that take care of some of the tedious setting up for you, but they make a couple of assumptions:
*# You '''must''' name the form element as {element}_editor or {element}_filemanager (see next section)
*# You '''must''' have at least the following fields in the database: {element} and {element}summary, as described earlier in this documentation

We can now look at the upgrades needed in the form definition file.

=== Form definition ===
Previous code in mod/glossary/edit_form.php:
<code php>
$mform->addElement('htmleditor', 'definition', get_string('definition', 'glossary'), array('rows'=>20));
$mform->setType('definition', PARAM_RAW);
$mform->addRule('definition', null, 'required', null, 'client');
$mform->setHelpButton('definition', array('writing', 'richtext'), false, 'editorhelpbutton');
$mform->addElement('format');
// a bit further...
$this->set_upload_manager(new upload_manager('attachment', true, false, $COURSE, false, 0, true, true, false));
$mform->addElement('file', 'attachment', get_string('attachment', 'forum'));
$mform->setHelpButton('attachment', array('attachment', get_string('attachment', 'glossary'), 'glossary'));
</code>
New code:
<code php>
$definitionoptions = $this->_customdata['definitionoptions'];
$attachmentoptions = $this->_customdata['attachmentoptions'];
// a bit further...
$mform->addElement('editor', 'definition_editor', get_string('definition', 'glossary'), null, $definitionoptions);
$mform->setType('definition_editor', PARAM_RAW);
$mform->addRule('definition_editor', get_string('required'), 'required', null, 'client');
// a bit further...
$mform->addElement('filemanager', 'attachment_filemanager', get_string('attachment', 'glossary'), null, $attachmentoptions);
$mform->setHelpButton('attachment_filemanager', array('attachment2', get_string('attachment', 'glossary'), 'glossary'));
</code>

Note the following:
* The format element and the help button are no longer required for the HTML editor element
* The name of the form element needs to be changed by adding '_editor' or '_manager' to the original name. This is a naming convention that is used by a couple of functions we will look at shortly

=== Handling submitted data ===
The final step is to handle the submitted data properly, i.e. retrieve the files and save them to disk, associating them with the record we have just created (a glossary entry in our example). This happens in edit.php:

Previous code in edit.php:
<code php>
// Section that updates an entry:
$todb->id = $e;
$dir = glossary_file_area_name($todb);
if ($mform->save_files($dir) and $newfilename = $mform->get_new_filename()) {
$todb->attachment = $newfilename;
}

// Section that adds an entry:
if ($todb->id = insert_record("glossary_entries", $todb)) {
$e = $todb->id;
$dir = glossary_file_area_name($todb);
if ($mform->save_files($dir) and $newfilename = $mform->get_new_filename()) {
set_field("glossary_entries", "attachment", $newfilename, "id", $todb->id);
}
}
</code>
New code:
<code php>
// $todb was renamed to $entry, and the code was refactored
// so that the file-handling code is only used once for either an add or an update action.
// If an entry is being added, $DB->insert() has already been called, so we have a valid $entry->id
$entry = file_postupdate_standard_editor($entry, 'definition', $definitionoptions, $context, 'glossary_entry', $entry->id);
$entry = file_postupdate_standard_filemanager($entry, 'attachment', $attachmentoptions, $context, 'glossary_attachment', $entry->id);
// store the updated value values
$DB->update_record('glossary_entries', $entry);
</code>
Things to note:
* If you are adding a new record, you will still need to call update_record after calling the file_postupdate* functions

== See also ==

* [[Development:File API]]
* [[Development:Using the file API]]
* [[Development:Repository API]]
* [[Development:Portfolio API]]
* MDL-14589 - File API Meta issue

{{CategoryDeveloper}}
[[Category:Files]]
[[Category:Repositories]]

Development:Using the File API in Moodle forms

2009-09-25T07:38:14Z

Nicolasconnault: /* Element preparation */

{{Moodle 2.0}}

This document shows you exactly how to use Moodle forms to get files from users in a standard and secure way.

==Overview==

In Moodle 2.0 all files are stored in a central database accessible via the [[Development:File API|File API]], and every file is associated with a "file area" in Moodle, such as a particular module.

A common use case is to provide a form (using Moodle's [[Development:lib/formslib.php|Forms API]]) which allows users to upload or import files as attachments or media embedded into HTML.

Normally this works like this:
# User starts creation or re-edits an existing item in Moodle (eg forum post, resource, glossary entry etc)
# User presses some sort of button to browse for new files to attach or embed
# User sees our "Choose file..." dialog, which contains one or more repository instances.
# User chooses a file, the [[Development:Repository API|Repository API]] takes care of copying the file into a "draft file area" within Moodle
# File appears in the text or as an attachment in the form.
# When the user hits save, the [[Development:File API|File API]] is invoked to move the file from the draft file area into a permanent file area associated with that data

This document shows you exactly how to use Moodle forms to interact with users in a standard and secure way.

If you just want to write code to manipulate Moodle files internally (without user input) then see [[Development:Using_the_File_API]].

==Form elements==

In Moodle 2.0 there are three file-related form elements for interacting with users:

# filemanager - the way to attach one or more files as a set
# editor - the way to specify a textarea with a HTML editor, and all the handling of images and movies within that HTML
# filepicker - a way to specify one file for the case when you want to process the file and throw it away

In Moodle 1.9 there were two other types which are now '''deprecated''' (they work, but please do not use these anymore)
# file - used to just allow a normal file upload from the desktop only.
# htmleditor - this old method of embedding a HTML editor in a textarea is not able to support repositories etc.

===filepicker===

File picker (''filepicker'') is a direct replacement of the older ''file'' formslib element.

It is intended for situations when you want the user to upload '''one''' file so you can process it and delete it, such as when you are importing data from a CSV file.

==== Using the filepicker element ====

<code php>
$mform->addElement('filepicker', 'userfile', get_string('file'), null, array('maxbytes' => $maxbytes, 'filetypes' => '*'));
</code>

==== Obtain the chosen file ====

The API for getting file contents is exactly the same as for ''file'' element.

<code php>
$content = $mform->get_file_content('userfile');
</code>

=== filemanager ===

The File Manager element improves on file picker by allowing you to manage more than one file. It is expected that the files will be stored permanently for future use (such as forum and glossary attachments).

==== Add file manager element ====

Example:
<code php>
$mform->addElement('filemanager', 'attachments', get_string('attachment', 'moodle'), null,
array('subdirs' => 0, 'maxbytes' => $maxbytes, 'maxfiles' => 50, 'filetypes' => array('document') ));
</code>

Here are the fields for filemanager:

;'filemanager':This is a filemanager element :)
;elementname:The unique name of the element in the form
;elementlabel:The label string that users see
;attributes:(leave it as null)
;options: an array of further options for the filepicker (see below)

The options array can contain:

;subdirs:(Default 0) Are subdirectories allowed? (true or false)
;maxbytes:(Default 0) Restricts the total size of all the files.
;maxfiles:(Default -1) Restricts the total number of files.
;filetypes:(Default *) You can specify what file types are accepted by filemanager. All current file types are listed in this file: [http://cvs.moodle.org/moodle/lib/file/file_types.mm moodle/lib/file/file_types.mm]. This is a [http://freemind.sourceforge.net/wiki/index.php/Main_Page freemind] file: if it is edited the changes will be immediately reflected in Moodle. Example usage: '''array('audio', 'video', 'documents')''', you can include file extensions as well, for example: '''array('*.txt', '*.jpg', 'audio')'''.

==== Load existing files into draft area ====

<code php>
if (empty($entry->id)) {
$entry = new object();
$entry->id = null;
}

$draftitemid = file_get_submitted_draft_itemid('attachments');
file_prepare_draft_area($draftitemid, $context->id, 'glossary_attachment', $entry->id, array('subdirs' => 0, 'maxbytes' => $maxbytes, 'maxfiles' => 50));
$entry->attachments = $draftitemid;

$mform->set_data($entry);

</code>

==== Store updated set of files ====

<code php>
if ($data = $mform->get_data()) {
// ... store or update $entry
file_save_draft_area_files($data->attachments, $context->id, 'glossary_attachment', $entry->id, array('subdirs' => 0, 'maxbytes' => $maxbytes, 'maxfiles' => 50));
}
</code>

===editor===
There are two way for using of editor element in code, the first one is easier but expects some standardized fields. The second method is more low level.

====Simple use====
# name database fields: ''textfield'', ''textfieldformat'' (and ''textfieldtrust'' if required)
# create options array <code php>$textfieldoptions = array('trusttext'=>true, 'subdirs'=>true, 'maxfiles'=>$maxfiles, 'maxbytes'=>$maxbytes);</code>
# add editor ''textfield_editor'' to moodle form, pass options through custom data in form constructor, set $data->id to null if data not exist yet <code php>$mform->addElement('editor', 'textfield_editor', get_string('fieldname', 'somemodule'), null, $textfieldoptions);</code>
# prepare data <code php>$data = file_prepare_standard_editor($data, 'textfield', $textfieldoptions, $context, 'somemodule_somearea', $data->id);</code>
# get submitted data and after inserting/updating of data <code php>$data = file_postupdate_standard_editor($data, 'textfield', $textfieldoptions, $context, 'somemodule_somearea', $data->id);</code>

Real world examples are in mod/glossary/edit.php and mod/glossary/comment.php

====Low level use====

When using editor element you need to preprocess and postprocess the data:
# detect if form was already submitted (usually means draft is area already exists) - ''file_get_submitted_draft_itemid()''
# prepare draft file area, temporary storage of all files attached to the text - ''file_prepare_draft_area()''
# convert encoded relative links to absolute links - ''file_prepare_draft_area()''
# create form and set current data
# after submission the changed files must be merged back into original area - ''file_save_draft_area_files()''
# absolute links have to be replaced by relative links - ''file_save_draft_area_files()''

=====Replace old htmleditor with editor=====

The file picker has been integrated with with TinyMCE to make the editor element. This new element should support all types on editors and should be able to switch them on-the-fly. Instances of the old htmleditor element in your forms should be replaced by the new editor element, this may need adding of new format and trusttext columns. For example:
<code php>
$mform->addElement('editor', 'entry', get_string('definition', 'glossary'), null,
array('maxfiles' => EDITOR_UNLIMITED_FILES, 'filearea' => 'glossary_entry'));
</code>
The editor element can take following options: maxfiles, maxbytes, filearea, subdirs and changeformat. Please note that the embedded files is optional feature and is not expected be used everywhere.

'''Note''': the editor element now includes text format option. You should no longer use the separate format element type.

=====Prepare current data - text and files=====

<code php>
if (empty($entry->id)) {
$entry = new object();
$entry->id = null;
$entry->definition = '';
$entry->format = FORMAT_HTML;
}

$draftid_editor = file_get_submitted_draft_itemid('entry');
$currenttext = file_prepare_draft_area($draftid_editor, $context->id, 'glossary_entry', $entry->id, array('subdirs'=>true), $entry->definition);
$entry->entry = array('text'=>$currenttext, 'format'=>$entry->format, 'itemid'=>$draftid_editor);

$mform->set_data($entry);
</code>

If there are multiple files, they will share the same itemid.

=====Obtain text, format and save draft files=====

To retrieve editor content, you need to use following code:

<code php>
if ($fromform = $mform->get_data()) {
// content of editor
$messagetext = $fromform->entry['text'];
// format of content
$messageformat = $fromform->entry['format'];
}
</code>

When a user selects a file using the file picker, the file is initially stored in a draft file area, and a URL is inserted into the HTML in the editor that lets the person editing the content (but no one else) see the file.

When the user submits the form, we then need to save the draft files to the correct place in permanent storage. (Just like you have to call $DB->update_record('tablename', $data); to have the other parts of the form submission stored correctly.)

The save_files_from_draft_area function and replace absolute links with internal relative links do:
<code php>
$messagetext = file_save_draft_area_files($draftid_editor, $context->id, 'glossary_entry', $entry->id, array('subdirs'=>true), $messagetext);
</code>
; $context->id, 'proper_file_area' and $entry->id : correspond to the contextid, filearea and itemid columns in the [[Development:File_API#Table:_files|files table]].
; $messagetext : this is the message text. As the files are saved to the real file area, the URLs in this content are rewritten.

All URLs in content that point to files managed to the File API are converted to a form that starts '@@PLUGINFILE@@/' before the content is stored in the database. That is what we mean by rewriting.

== File serving==

=== Convert internal relative links to absolute links ===

Before text content is displayed to the user, any URLs in the '@@PLUGINFILE@@/' form in the content need to be rewritten to the real URL where the user can access the files.
<code php>
$messagetext = file_rewrite_pluginfile_urls($messagetext, 'pluginfile.php',
"$context->id/proper_file_area/$itemid/");
</code>
; $messagetext : is the content containing the @@PLUGINFILE@@ URLs from the database.
; 'pluginfile.php' : there are a number of different scripts that can serve files with different permissions checks. You need to specify which one to use.
; "$context->id/proper_file_area/$itemid/" : uniquely identifies the file area, as before.

=== Implement file serving access control ===

Attachments and embedded images should have the same access control like the text itself, in majority of cases these files are served using pluginfile.php. Access control is defined in ''module/lib.php'' file in function ''module_pluginfile()''.

== File browsing support ==
Only owner of each file area is allowed to use low level File API function to access files, other parts of Moodle should use file browsing API.

Activities may specify browsing support in own module/lib.php file by implementing functions module_get_file_areas() and module_get_file_info().

== Upgrading your code ==
Here I will attempt to describe some simple steps you can take to upgrade your file-handling form elements from pre-2.0 code to 2.0. We will use the example of glossary, since it has been used above.

=== Preparing your options ===
Unless you are happy with the defaults, you will need to define an array of options for each file-handling form element. You could define it at different places, but it's best to put it in one place and make the array(s) available to other files if they need it. In the majority of cases, this will be in a file like edit.php

Previous code in mod/glossary/edit.php:
<code php>
$mform =& new mod_glossary_entry_form(null, compact('cm', 'glossary', 'hook', 'mode', 'e', 'context'));
</code>
New code:
<code php>
$maxbytes = $course->maxbytes; // Could also use $CFG->maxbytes if you are not coding within a course context
$definitionoptions = array('trusttext'=>true, 'subdirs'=>false, 'maxfiles'=>99, 'maxbytes'=>$maxbytes, 'trusttext'=>true, 'context'=>$context);
$attachmentoptions = array('subdirs'=>false, 'maxfiles'=>99, 'maxbytes'=>$maxbytes);
$mform = new mod_glossary_entry_form(null, array(
'current'=>$entry,
'cm'=>$cm,
'glossary'=>$glossary,
'definitionoptions'=>$definitionoptions,
'attachmentoptions'=>$attachmentoptions));
</code>
Note that the data being passed to the form constructor have changed also, but this is not part of the file API changes, I just include them to avoid confusion.

These options are for the htmleditor (definition field) and the filemanager (attachment field). They are used by a file called edit_form.php.

=== Element preparation ===
Before we look at this, however, we need to "prepare" the elements so that they can correctly display existing embedded images and attached files when you are editing a record instead of just creating one. So, let's take the code we've got so far in edit.php and add to it:

Currently upgraded code in edit.php:
<code php>
$mform = new mod_glossary_entry_form(null, array(
'current'=>$entry,
'cm'=>$cm,
'glossary'=>$glossary,
'definitionoptions'=>$definitionoptions,
'attachmentoptions'=>$attachmentoptions));
</code>
New code with element preparation:
<code php>
$entry = file_prepare_standard_editor($entry, 'definition', $definitionoptions, $context, 'glossary_entry', $entry->id);
$entry = file_prepare_standard_filemanager($entry, 'attachment', $attachmentoptions, $context, 'glossary_attachment', $entry->id);
$mform = new mod_glossary_entry_form(null, array(
'current'=>$entry,
'cm'=>$cm,
'glossary'=>$glossary,
'definitionoptions'=>$definitionoptions,
'attachmentoptions'=>$attachmentoptions));
</code>
Things to note:
* $entry in this case is simply a stdClass object which may either represent a new glossary entry or an existing one.
* $entry->id must be the unique identifier for the current object. If we are creating a new entry, it will be null, but in all cases it must be defined.
* These two functions (file_prepare_standard_editor and file_prepare_standard_filemanager) are shortcuts functions that take care of some of the tedious setting up for you, but they make a couple of assumptions:
*# You '''must''' name the form element as {element}_editor or {element}_filemanager (see next section)
*# You '''must''' have at least the following fields in the database: {element} and {element}summary, as described earlier in this documentation

We can now look at the upgrades needed in the form definition file.

=== Form definition ===
Previous code in mod/glossary/edit_form.php:
<code php>
$mform->addElement('htmleditor', 'definition', get_string('definition', 'glossary'), array('rows'=>20));
$mform->setType('definition', PARAM_RAW);
$mform->addRule('definition', null, 'required', null, 'client');
$mform->setHelpButton('definition', array('writing', 'richtext'), false, 'editorhelpbutton');
$mform->addElement('format');
// a bit further...
$this->set_upload_manager(new upload_manager('attachment', true, false, $COURSE, false, 0, true, true, false));
$mform->addElement('file', 'attachment', get_string('attachment', 'forum'));
$mform->setHelpButton('attachment', array('attachment', get_string('attachment', 'glossary'), 'glossary'));
</code>
New code:
<code php>
$definitionoptions = $this->_customdata['definitionoptions'];
$attachmentoptions = $this->_customdata['attachmentoptions'];
// a bit further...
$mform->addElement('editor', 'definition_editor', get_string('definition', 'glossary'), null, $definitionoptions);
$mform->setType('definition_editor', PARAM_RAW);
$mform->addRule('definition_editor', get_string('required'), 'required', null, 'client');
// a bit further...
$mform->addElement('filemanager', 'attachment_filemanager', get_string('attachment', 'glossary'), null, $attachmentoptions);
$mform->setHelpButton('attachment_filemanager', array('attachment2', get_string('attachment', 'glossary'), 'glossary'));
</code>

Note the following:
* The format element and the help button are no longer required for the HTML editor element
* The name of the form element needs to be changed by adding '_editor' or '_manager' to the original name. This is a naming convention that is used by a couple of functions we will look at shortly

=== Submitted data handling ===
The final step is to handle the submitted data properly, i.e. retrieve the files and save them to disk, associating them with the record we have just created (a glossary entry in our example). This happens in edit.php:

Previous code in edit.php:
<code php>
// Section that updates an entry:
$todb->id = $e;
$dir = glossary_file_area_name($todb);
if ($mform->save_files($dir) and $newfilename = $mform->get_new_filename()) {
$todb->attachment = $newfilename;
}

// Section that adds an entry:
if ($todb->id = insert_record("glossary_entries", $todb)) {
$e = $todb->id;
$dir = glossary_file_area_name($todb);
if ($mform->save_files($dir) and $newfilename = $mform->get_new_filename()) {
set_field("glossary_entries", "attachment", $newfilename, "id", $todb->id);
}
}
</code>
New code:
<code php>
// $todb was renamed to $entry, and the code was refactored
// so that the file-handling code is only used once for either an add or an update action.
// If an entry is being added, $DB->insert() has already been called, so we have a valid $entry->id
$entry = file_postupdate_standard_editor($entry, 'definition', $definitionoptions, $context, 'glossary_entry', $entry->id);
$entry = file_postupdate_standard_filemanager($entry, 'attachment', $attachmentoptions, $context, 'glossary_attachment', $entry->id);
// store the updated value values
$DB->update_record('glossary_entries', $entry);
</code>
Things to note:
* If you are adding a new record, you will still need to call update_record after calling the file_postupdate* functions

== See also ==

* [[Development:File API]]
* [[Development:Using the file API]]
* [[Development:Repository API]]
* [[Development:Portfolio API]]
* MDL-14589 - File API Meta issue

{{CategoryDeveloper}}
[[Category:Files]]
[[Category:Repositories]]

Development:Using the File API in Moodle forms

2009-09-25T07:37:02Z

Nicolasconnault: Adding a conversion tutorial

{{Moodle 2.0}}

This document shows you exactly how to use Moodle forms to get files from users in a standard and secure way.

==Overview==

In Moodle 2.0 all files are stored in a central database accessible via the [[Development:File API|File API]], and every file is associated with a "file area" in Moodle, such as a particular module.

A common use case is to provide a form (using Moodle's [[Development:lib/formslib.php|Forms API]]) which allows users to upload or import files as attachments or media embedded into HTML.

Normally this works like this:
# User starts creation or re-edits an existing item in Moodle (eg forum post, resource, glossary entry etc)
# User presses some sort of button to browse for new files to attach or embed
# User sees our "Choose file..." dialog, which contains one or more repository instances.
# User chooses a file, the [[Development:Repository API|Repository API]] takes care of copying the file into a "draft file area" within Moodle
# File appears in the text or as an attachment in the form.
# When the user hits save, the [[Development:File API|File API]] is invoked to move the file from the draft file area into a permanent file area associated with that data

This document shows you exactly how to use Moodle forms to interact with users in a standard and secure way.

If you just want to write code to manipulate Moodle files internally (without user input) then see [[Development:Using_the_File_API]].

==Form elements==

In Moodle 2.0 there are three file-related form elements for interacting with users:

# filemanager - the way to attach one or more files as a set
# editor - the way to specify a textarea with a HTML editor, and all the handling of images and movies within that HTML
# filepicker - a way to specify one file for the case when you want to process the file and throw it away

In Moodle 1.9 there were two other types which are now '''deprecated''' (they work, but please do not use these anymore)
# file - used to just allow a normal file upload from the desktop only.
# htmleditor - this old method of embedding a HTML editor in a textarea is not able to support repositories etc.

===filepicker===

File picker (''filepicker'') is a direct replacement of the older ''file'' formslib element.

It is intended for situations when you want the user to upload '''one''' file so you can process it and delete it, such as when you are importing data from a CSV file.

==== Using the filepicker element ====

<code php>
$mform->addElement('filepicker', 'userfile', get_string('file'), null, array('maxbytes' => $maxbytes, 'filetypes' => '*'));
</code>

==== Obtain the chosen file ====

The API for getting file contents is exactly the same as for ''file'' element.

<code php>
$content = $mform->get_file_content('userfile');
</code>

=== filemanager ===

The File Manager element improves on file picker by allowing you to manage more than one file. It is expected that the files will be stored permanently for future use (such as forum and glossary attachments).

==== Add file manager element ====

Example:
<code php>
$mform->addElement('filemanager', 'attachments', get_string('attachment', 'moodle'), null,
array('subdirs' => 0, 'maxbytes' => $maxbytes, 'maxfiles' => 50, 'filetypes' => array('document') ));
</code>

Here are the fields for filemanager:

;'filemanager':This is a filemanager element :)
;elementname:The unique name of the element in the form
;elementlabel:The label string that users see
;attributes:(leave it as null)
;options: an array of further options for the filepicker (see below)

The options array can contain:

;subdirs:(Default 0) Are subdirectories allowed? (true or false)
;maxbytes:(Default 0) Restricts the total size of all the files.
;maxfiles:(Default -1) Restricts the total number of files.
;filetypes:(Default *) You can specify what file types are accepted by filemanager. All current file types are listed in this file: [http://cvs.moodle.org/moodle/lib/file/file_types.mm moodle/lib/file/file_types.mm]. This is a [http://freemind.sourceforge.net/wiki/index.php/Main_Page freemind] file: if it is edited the changes will be immediately reflected in Moodle. Example usage: '''array('audio', 'video', 'documents')''', you can include file extensions as well, for example: '''array('*.txt', '*.jpg', 'audio')'''.

==== Load existing files into draft area ====

<code php>
if (empty($entry->id)) {
$entry = new object();
$entry->id = null;
}

$draftitemid = file_get_submitted_draft_itemid('attachments');
file_prepare_draft_area($draftitemid, $context->id, 'glossary_attachment', $entry->id, array('subdirs' => 0, 'maxbytes' => $maxbytes, 'maxfiles' => 50));
$entry->attachments = $draftitemid;

$mform->set_data($entry);

</code>

==== Store updated set of files ====

<code php>
if ($data = $mform->get_data()) {
// ... store or update $entry
file_save_draft_area_files($data->attachments, $context->id, 'glossary_attachment', $entry->id, array('subdirs' => 0, 'maxbytes' => $maxbytes, 'maxfiles' => 50));
}
</code>

===editor===
There are two way for using of editor element in code, the first one is easier but expects some standardized fields. The second method is more low level.

====Simple use====
# name database fields: ''textfield'', ''textfieldformat'' (and ''textfieldtrust'' if required)
# create options array <code php>$textfieldoptions = array('trusttext'=>true, 'subdirs'=>true, 'maxfiles'=>$maxfiles, 'maxbytes'=>$maxbytes);</code>
# add editor ''textfield_editor'' to moodle form, pass options through custom data in form constructor, set $data->id to null if data not exist yet <code php>$mform->addElement('editor', 'textfield_editor', get_string('fieldname', 'somemodule'), null, $textfieldoptions);</code>
# prepare data <code php>$data = file_prepare_standard_editor($data, 'textfield', $textfieldoptions, $context, 'somemodule_somearea', $data->id);</code>
# get submitted data and after inserting/updating of data <code php>$data = file_postupdate_standard_editor($data, 'textfield', $textfieldoptions, $context, 'somemodule_somearea', $data->id);</code>

Real world examples are in mod/glossary/edit.php and mod/glossary/comment.php

====Low level use====

When using editor element you need to preprocess and postprocess the data:
# detect if form was already submitted (usually means draft is area already exists) - ''file_get_submitted_draft_itemid()''
# prepare draft file area, temporary storage of all files attached to the text - ''file_prepare_draft_area()''
# convert encoded relative links to absolute links - ''file_prepare_draft_area()''
# create form and set current data
# after submission the changed files must be merged back into original area - ''file_save_draft_area_files()''
# absolute links have to be replaced by relative links - ''file_save_draft_area_files()''

=====Replace old htmleditor with editor=====

The file picker has been integrated with with TinyMCE to make the editor element. This new element should support all types on editors and should be able to switch them on-the-fly. Instances of the old htmleditor element in your forms should be replaced by the new editor element, this may need adding of new format and trusttext columns. For example:
<code php>
$mform->addElement('editor', 'entry', get_string('definition', 'glossary'), null,
array('maxfiles' => EDITOR_UNLIMITED_FILES, 'filearea' => 'glossary_entry'));
</code>
The editor element can take following options: maxfiles, maxbytes, filearea, subdirs and changeformat. Please note that the embedded files is optional feature and is not expected be used everywhere.

'''Note''': the editor element now includes text format option. You should no longer use the separate format element type.

=====Prepare current data - text and files=====

<code php>
if (empty($entry->id)) {
$entry = new object();
$entry->id = null;
$entry->definition = '';
$entry->format = FORMAT_HTML;
}

$draftid_editor = file_get_submitted_draft_itemid('entry');
$currenttext = file_prepare_draft_area($draftid_editor, $context->id, 'glossary_entry', $entry->id, array('subdirs'=>true), $entry->definition);
$entry->entry = array('text'=>$currenttext, 'format'=>$entry->format, 'itemid'=>$draftid_editor);

$mform->set_data($entry);
</code>

If there are multiple files, they will share the same itemid.

=====Obtain text, format and save draft files=====

To retrieve editor content, you need to use following code:

<code php>
if ($fromform = $mform->get_data()) {
// content of editor
$messagetext = $fromform->entry['text'];
// format of content
$messageformat = $fromform->entry['format'];
}
</code>

When a user selects a file using the file picker, the file is initially stored in a draft file area, and a URL is inserted into the HTML in the editor that lets the person editing the content (but no one else) see the file.

When the user submits the form, we then need to save the draft files to the correct place in permanent storage. (Just like you have to call $DB->update_record('tablename', $data); to have the other parts of the form submission stored correctly.)

The save_files_from_draft_area function and replace absolute links with internal relative links do:
<code php>
$messagetext = file_save_draft_area_files($draftid_editor, $context->id, 'glossary_entry', $entry->id, array('subdirs'=>true), $messagetext);
</code>
; $context->id, 'proper_file_area' and $entry->id : correspond to the contextid, filearea and itemid columns in the [[Development:File_API#Table:_files|files table]].
; $messagetext : this is the message text. As the files are saved to the real file area, the URLs in this content are rewritten.

All URLs in content that point to files managed to the File API are converted to a form that starts '@@PLUGINFILE@@/' before the content is stored in the database. That is what we mean by rewriting.

== File serving==

=== Convert internal relative links to absolute links ===

Before text content is displayed to the user, any URLs in the '@@PLUGINFILE@@/' form in the content need to be rewritten to the real URL where the user can access the files.
<code php>
$messagetext = file_rewrite_pluginfile_urls($messagetext, 'pluginfile.php',
"$context->id/proper_file_area/$itemid/");
</code>
; $messagetext : is the content containing the @@PLUGINFILE@@ URLs from the database.
; 'pluginfile.php' : there are a number of different scripts that can serve files with different permissions checks. You need to specify which one to use.
; "$context->id/proper_file_area/$itemid/" : uniquely identifies the file area, as before.

=== Implement file serving access control ===

Attachments and embedded images should have the same access control like the text itself, in majority of cases these files are served using pluginfile.php. Access control is defined in ''module/lib.php'' file in function ''module_pluginfile()''.

== File browsing support ==
Only owner of each file area is allowed to use low level File API function to access files, other parts of Moodle should use file browsing API.

Activities may specify browsing support in own module/lib.php file by implementing functions module_get_file_areas() and module_get_file_info().

== Upgrading your code ==
Here I will attempt to describe some simple steps you can take to upgrade your file-handling form elements from pre-2.0 code to 2.0. We will use the example of glossary, since it has been used above.

=== Preparing your options ===
Unless you are happy with the defaults, you will need to define an array of options for each file-handling form element. You could define it at different places, but it's best to put it in one place and make the array(s) available to other files if they need it. In the majority of cases, this will be in a file like edit.php

Previous code in mod/glossary/edit.php:
<code php>
$mform =& new mod_glossary_entry_form(null, compact('cm', 'glossary', 'hook', 'mode', 'e', 'context'));
</code>
New code:
<code php>
$maxbytes = $course->maxbytes; // Could also use $CFG->maxbytes if you are not coding within a course context
$definitionoptions = array('trusttext'=>true, 'subdirs'=>false, 'maxfiles'=>99, 'maxbytes'=>$maxbytes, 'trusttext'=>true, 'context'=>$context);
$attachmentoptions = array('subdirs'=>false, 'maxfiles'=>99, 'maxbytes'=>$maxbytes);
$mform = new mod_glossary_entry_form(null, array(
'current'=>$entry,
'cm'=>$cm,
'glossary'=>$glossary,
'definitionoptions'=>$definitionoptions,
'attachmentoptions'=>$attachmentoptions));
</code>
Note that the data being passed to the form constructor have changed also, but this is not part of the file API changes, I just include them to avoid confusion.

These options are for the htmleditor (definition field) and the filemanager (attachment field). They are used by a file called edit_form.php.

=== Element preparation ===
Before we look at this, however, we need to "prepare" the elements so that they can correctly display existing embedded images and attached files when you are editing a record instead of just creating one. So, let's take the code we've got so far in edit.php and add to it:

Currently upgraded code in edit.php:
<code php>
$mform = new mod_glossary_entry_form(null, array(
'current'=>$entry,
'cm'=>$cm,
'glossary'=>$glossary,
'definitionoptions'=>$definitionoptions,
'attachmentoptions'=>$attachmentoptions));
</code>
New code with element preparation:
<code php>
$entry = file_prepare_standard_editor($entry, 'definition', $definitionoptions, $context, 'glossary_entry', $entry->id);
$entry = file_prepare_standard_filemanager($entry, 'attachment', $attachmentoptions, $context, 'glossary_attachment', $entry->id);
$mform = new mod_glossary_entry_form(null, array(
'current'=>$entry,
'cm'=>$cm,
'glossary'=>$glossary,
'definitionoptions'=>$definitionoptions,
'attachmentoptions'=>$attachmentoptions));
</code>
Things to note:
* $entry in this case is simply a stdClass object which may either represent a new glossary entry or an existing one.
* $entry->id must be the unique identifier for the current object. If we are creating a new entry, it will be null, but in all cases it must be defined.
* These two functions (file_prepare_standard_editor and file_prepare_standard_filemanager) are shortcuts functions that take care of some of the tedious setting up for you, but they make a couple of assumptions:
## You '''must''' name the form element as {element}_editor or {element}_filemanager (see next section)
## You '''must''' have at least the following fields in the database: {element} and {element}summary, as described earlier in this documentation

We can now look at the upgrades needed in the form definition file.

=== Form definition ===
Previous code in mod/glossary/edit_form.php:
<code php>
$mform->addElement('htmleditor', 'definition', get_string('definition', 'glossary'), array('rows'=>20));
$mform->setType('definition', PARAM_RAW);
$mform->addRule('definition', null, 'required', null, 'client');
$mform->setHelpButton('definition', array('writing', 'richtext'), false, 'editorhelpbutton');
$mform->addElement('format');
// a bit further...
$this->set_upload_manager(new upload_manager('attachment', true, false, $COURSE, false, 0, true, true, false));
$mform->addElement('file', 'attachment', get_string('attachment', 'forum'));
$mform->setHelpButton('attachment', array('attachment', get_string('attachment', 'glossary'), 'glossary'));
</code>
New code:
<code php>
$definitionoptions = $this->_customdata['definitionoptions'];
$attachmentoptions = $this->_customdata['attachmentoptions'];
// a bit further...
$mform->addElement('editor', 'definition_editor', get_string('definition', 'glossary'), null, $definitionoptions);
$mform->setType('definition_editor', PARAM_RAW);
$mform->addRule('definition_editor', get_string('required'), 'required', null, 'client');
// a bit further...
$mform->addElement('filemanager', 'attachment_filemanager', get_string('attachment', 'glossary'), null, $attachmentoptions);
$mform->setHelpButton('attachment_filemanager', array('attachment2', get_string('attachment', 'glossary'), 'glossary'));
</code>

Note the following:
* The format element and the help button are no longer required for the HTML editor element
* The name of the form element needs to be changed by adding '_editor' or '_manager' to the original name. This is a naming convention that is used by a couple of functions we will look at shortly

=== Submitted data handling ===
The final step is to handle the submitted data properly, i.e. retrieve the files and save them to disk, associating them with the record we have just created (a glossary entry in our example). This happens in edit.php:

Previous code in edit.php:
<code php>
// Section that updates an entry:
$todb->id = $e;
$dir = glossary_file_area_name($todb);
if ($mform->save_files($dir) and $newfilename = $mform->get_new_filename()) {
$todb->attachment = $newfilename;
}

// Section that adds an entry:
if ($todb->id = insert_record("glossary_entries", $todb)) {
$e = $todb->id;
$dir = glossary_file_area_name($todb);
if ($mform->save_files($dir) and $newfilename = $mform->get_new_filename()) {
set_field("glossary_entries", "attachment", $newfilename, "id", $todb->id);
}
}
</code>
New code:
<code php>
// $todb was renamed to $entry, and the code was refactored
// so that the file-handling code is only used once for either an add or an update action.
// If an entry is being added, $DB->insert() has already been called, so we have a valid $entry->id
$entry = file_postupdate_standard_editor($entry, 'definition', $definitionoptions, $context, 'glossary_entry', $entry->id);
$entry = file_postupdate_standard_filemanager($entry, 'attachment', $attachmentoptions, $context, 'glossary_attachment', $entry->id);
// store the updated value values
$DB->update_record('glossary_entries', $entry);
</code>
Things to note:
* If you are adding a new record, you will still need to call update_record after calling the file_postupdate* functions

== See also ==

* [[Development:File API]]
* [[Development:Using the file API]]
* [[Development:Repository API]]
* [[Development:Portfolio API]]
* MDL-14589 - File API Meta issue

{{CategoryDeveloper}}
[[Category:Files]]
[[Category:Repositories]]

Development:Using the File API

2009-09-25T06:34:57Z

Nicolasconnault: Putting link to more useful doc

{{Moodle 2.0}}
The File API is for managing all the files stored by Moodle. If you are interested in how the file API works internally, see [[Development:File API]]. The page is just about what you need to know to use the file API. Related is the [[Development:Repository API]], which lets users get files into Moodle.

If you are looking for an explanation on how to upgrade pre-2.0 code to using the file API, you most likely need to read [[Development:Using_the_File_API_in_Moodle_forms|Using the File API in Moodle forms]].

==File areas==

Files are conceptually stored in '''file areas'''. A file area is uniquely identified by:
* A context id.
* A file area type, for example 'course_intro' or 'forum_post'.
* A unique itemid. Normally, the itemid relates to something depending on the file area type. For example, for a 'course_intro' file area, the itemid is is the course id. For forum post, it is the post id.

File areas are not listed separately anywhere, they are stored implicitly in the files table. Please note that each subsystem is allowed to access only own file areas, for example core code must not access module or block files directly.

===Naming file areas===

It is important that file areas are named consistently so we do not get name collisions, and so the names are easy to understand. Please follow the following guidelines:

====start of the name====

If the file area belongs to a plugin, please use the plugin name as the start of the file area name.

This is the same plugin name that you would use for get_string calls. Some examples:
* All file areas that belong to the forum modules should have a name beginning with 'forum'. For example 'forum_post', 'forum_intro'.
* A file area belonging to the HTML block would start 'block_html_'.
* A file area belonging to a question type would start 'qtype_myqtype_', except this is probably not necessary, because question type images should probably be stored in the core 'question_text' file area.
* If the file area is used by a local hack, the file area name should start 'local_'.

If the file area belongs to core code, the file area name should start with a prefix that indicates what part of Moodle it belongs to.

But try to avoid clashing with prefixes that a plugin might use. Some examples:
* 'course_intro'
* 'question_text'
* 'user_draft' (although draft file areas are a special case).

====rest of the name====

Like naming variables or functions, try to find a name that is short, but says exactly what the file area is for.

If possible use the name of the file area to give a clue as to which database table the itemid relates to. For example:

* For the 'forum_post' file area, the itemid links to forum_post.id.
* For 'question_text' file area, the itemid links to question.id. (Would it be permissible to call this file area just question?)

==Serving files to users==

You must refer to the file with a URL that includes a file-serving script, often pluginfile.php. For example
<code php>
$url = $CFG->wwwroot/pluginfile.php/$contextid/$filearea/$itemid/file/path.ext;
</code>
Often you get these URLs generated automatically for you using the function file_rewrite_pluginfile_urls.

==Getting files from the user==

* See [[Development:Using_the_File_API_in_Moodle_forms|Using the File API in Moodle forms]]
==Examples==
Please note that in reality developers outside of core will not deal with file api directly in majority of cases, instead use formslib elements which are doing all this automatically.

===Browsing files===
<code php>
$browser = get_file_browser();
$context = get_system_context();

$filearea = null;
$itemid = null;
$filename = null;
if ($fileinfo = $browser->get_file_info($context, $filearea, $itemid, '/', $filename)) {
// build a Breadcrumb trail
$level = $fileinfo->get_parent();
while ($level) {
$params = base64_encode(serialize($level->get_params()));
$path[] = array('name'=>$level->get_visible_name(), 'path'=>$params);
$level = $level->get_parent();
}
$path = array_reverse($path);
$children = $fileinfo->get_children();
foreach ($children as $child) {
if ($child->is_directory()) {
echo $child->get_visible_name();
// display contextid, itemid, filepath and filename
var_dump($child->get_params());
}
}
}

</code>
===Moving files around===

For example, if you have just built a file at the path
<code php>
$from_zip_file = $CFG->dataroot . '/temp/backup/' . $preferences->backup_unique_code .
'/' . $preferences->backup_name;
</code>
And you want to move it into the course_backup file area, do
<code php>
$context = get_context_instance(CONTEXT_COURSE, $preferences->backup_course);
$fs = get_file_storage();
$file_record = array('contextid'=>$context->id, 'filearea'=>'course_backup',
'itemid'=>0, 'filepath'=>'/', 'filename'=>$preferences->backup_name,
'timecreated'=>time(), 'timemodified'=>time());
$fs->create_file_from_pathname($file_record, $from_zip_file);
</code>
===Create a copy of stored file===
If you need to create a copy of stored file (actually, it add a new record in database):
<code php>
$context = get_context_instance_by_id($contextid);
$file_info = $browser->get_file_info($context, $filearea, $fileitemid, $filepath, $filename);
// copy this file to draft area
$file_info->copy_to_storage($user_context->id, 'user_draft', $newitemid, '/', $title);
</code>

=== List area files ===
<code php>
$fs = get_file_storage();
$files = $fs->get_area_files($contextid, 'user_draft');
foreach ($files as $f) {
// $f is an instance of stored_file
echo $f->get_filename();
}
</code>

==See also==

* [[Development:File API]] how the File API works internally.
* [[Roadmap|Moodle 2.0 roadmap]]

[[Category:Developer]]
[[Category:Files]]

Development:File API

2009-09-25T06:15:55Z

Nicolasconnault: Updated name of fileareas

{{Moodle_2.0}}
This specification has now largely been implemented in Moodle 2.0. Inevitably, in the implementation, some details may have changed. If in doubt, read the code. (Then come back and correct this page ;-))

The implementation of this specification is being tracked at MDL-14589.

Please see [[Development:Using the file API]] if you just want to know how to use the File API in your code, rather than how it works internally.

==Objectives==

The goals of these changes are to:

* allow files to be stored within Moodle, as part of the content (as we do now).
* use a consistent and simple approach for all file handling throughout Moodle.
* give modules control over which users can access a file, using capabilities and other local rules.
* make it easy to determine which parts of Moodle use which files, to simplify operations like backup and restore.
* track where files originally came from.
* avoid redundant storage, when the same file is used twice.
* fully support Unicode file names, irrespective of the capabilities of the underlying file system.

==Overview==

The File API is a set of core interfaces to allow the rest of Moodle to:
# store files, and
# display files to users.
It applies only to files that are part of the Moodle site's content. It is not used for internal files, such as those in the following subdirectories of dataroot: temp, lang, cache, environment, filter, search, sessions, upgradelogs, ...

The API can be subdivided into the following parts:
; Serving files
: Lets users accessing a Moodle site get the files (file.php, draftfile.php, pluginfile.php, userfile.php, etc.)
:* Serve the files on request
:* with appropriate security checks
; File API internals
: Stores the files on disc, with metadata in associated database tables.
:* Content-addressed storage.
; File management API
: Allows code to manipulate the stored files (lib/filelib.php)
:* find information about stored files.
:* print links to files.
:* move/rename/copy/delete/etc.
:* keep a file synchronised with an external repository.
; File management user interface
: Provides the interface for (lib/form/file.php, filemanager.php, filepicker.php and files/index.php, draftfiles.php)
:* Form elements allowing users to select a file using the Repository API, and have it stored within Moodle.
:* UI for users to manage their files, replacing the old course files UI

== Serving files ==

TODO revise this section.

Deals with serving of files - browser requests file, Moodle sends it back. We have three main files. It is important to setup slasharguments on server (file.php/some/thing/xxx.jpg), any content that relies on relative links can not work without it (scorm, uploaded html pages, etc.).

=== file.php ===

Serves course files.

Implements basic file access. Ideally only images and files linked from course sections should be there, no XSS protection required - we expect javascript, sw, etc. there, no way to make it "secure". The access control is not critical any more if we move most of the files into modules

The file name and parameter structure is critical for backwards compatibility of existing course content.

/file.php/courseid/dir/dir/filename.ext

Internally the files would be stored in <code>array('contextid'=>$coursecontextid, 'filearea'=>'coursefiles', 'itemid'=>0)</code>

=== pluginfile.php ===

(aka modfile.php)
Sends module, block, question files.
* modules decide about access control
* optional XSS protection - student submitted files must not be served with normal headers, we have to force download instead; ideally there should be second wwwroot for serving of untrusted files
* only internal links to selected areas are supported - you can link images in summary area, but not the assignment submissions

Absolute file links need to be rewritten if html editing allowed in module. The links are stored internally as relative links. Before editing or display the internal link representation is converted to absolute links using simple str_replace() @@thipluginlink/summary@@/image.jpg --> /pluginfile.php/assignmentcontextid/intro/image.jpg, it is converted back to internal links before saving.

::Can the distinct file areas supported by one plugin be declared somehow in order add some information about them? For example, I think it can be interesting to declare:
::* assignment_summary:
::** relpath='intro'
::** userdata=false
::** anotherproperty=anothervalue
::* assignment_submission:
::** relpath='submission/@@USERID@@'
::** userdata=false
::** anotherproperty=anothervalue
::* and so on...
::And then, when the editor "receives" one "assignment_summary" areaname, if knows what to show and so on? Also that info could be useful to know, in backup & restore if some fileareas have to be processed or no (userdata=false). Or also, when reconstructing the links (str_replace() above). And will cause to have a well defined list of fileareas by module, instead of coding them in a free way (prone to errors). [[User:Eloy Lafuente (stronk7)|Eloy Lafuente (stronk7)]] 16:35, 28 June 2008 (CDT)

::Something like this will be part of file management API, hardcoding this in file storage would make it less flexible imo [[User:Skodak|Skodak]]

::Yup, yup. Storage doesn't know anything but get/put files (nothing else). It's part of management, absolutely. [[User:Eloy Lafuente (stronk7)|Eloy Lafuente (stronk7)]] 11:21, 29 June 2008 (CDT)

/pluginfile.php/contextid/areaname/arbitrary/params/or/dirs/filename.ext

pluginfile.php detects the type of plugin from context table, fetches basic info (like $course or $cm if appropriate) and calls plugin function (or later method) which does the access control and finally sends the file to user. ''areaname'' separates files by type and divides the context into several subtrees - for example ''summary'' files (images used in module intros), post attachments, etc.

==== Assignment example ====

/pluginfile.php/assignmentcontextid/intro/someimage.jpg
/pluginfile.php/assignmentcontextid/submission/submissionid/attachmentname.ext
/pluginfile.php/assignmentcontextid/extra/allsubmissionfiles.zip

::Uhm... all those files together? What's going to differentiate the "submission" path in the example above from the "summary" path? Is it supposed that the editor, or the filemanager won't allow , for example to pick-up one file from the "submission" area to be used in the summary of one assignment and only the "summary" area will be showed? That means multiple file managers by context and it's against the clean "one file manager per context" agreed below [[User:Eloy Lafuente (stronk7)|Eloy Lafuente (stronk7)]] 21:28, 26 June 2008 (CDT)
::Yes Eloy, the different areas (summary, submission) etc. have different uses, different access control. There are two types of file manager - the two pane file manager which lists all contexts+areas user may access, and minimalistic manager in html editor which shows only subset of areas from current plugin (because you can not link anything else).

====scorm example====

/pluginfile.php/scormcontextid/intro/someimage.jpg
/pluginfile.php/scormcontextid/content/revisionnumber/dir/somescormfile.js

The revision counter is incremented when any file changes in order to prevent caching problems. The lifetime should be adjustable in module settings.

====quiz example====

pluginfile.php/quizcontextid/intro/niceimage.jpg
pluginfile.php/quizcontextid/report/type/export.ods

====questions example====

pluginfile.php/SYSCONTEXTID/question/questionid/file.jpg

====blog example====
Blog entries or notes in general do not have context id (because they live in system context, SYSCONTEXTID below is the id of system context).
The note attachments are always served with XSS protection on, ideally we should use separate wwwroot for this. Access control can be hardcoded.

/pluginfile.php/SYSCONTEXTID/blog_attachment/blogentryid/attachmentname.ext

Internally stored in <code>array('contextid'=>SYSCONTEXTID, 'filearea'=>'blog_attachment', 'itemid'=>$blogentryid)</code>

/pluginfile.php/SYSCONTEXTID/blog_post/blogentryid/embeddedimage.ext

Internally stored in <code>array('contextid'=>SYSCONTEXTID, 'filearea'=>'blog_post', 'itemid'=>$blogentryid)</code>

====backup example====
It would be nice to have some special protection of backup files - new capabilities for backup file download, upload. Backups contain a lot of personal info, we could block restoring of backups from other sites too.

/pluginfile.php/coursecontextid/backup/backupfile.zip

Internally stored in <code>array('contextid'=>$coursecontextid, 'filearea'=>'backup', 'itemid'=>0)</code>

===userfile.php===
Personal file storage, intended as an online storage of work in progress like assignments before the submission.
* read/write own files only for now
* option to share with others later
* personal "websites" will not be supported (security)

/userfile.php/userid/dir/dir/filename.ext

===rssfile.php===
Replaces rss/file.php which is kept only for backwards compatibility.
RSS files should not require sessions/cookies, URLs should contain some sort of security token/key.
Internally the files may be stored in database or together with other files.
Performance improvements - we should support both Etag (cool) and Last-Modified (more used), when we receive If-None-Match/If-Modified-Since => 304

/rssfile.php/contextid/any/parameters/module/wants/rss.xml
/rssfile.php/SYSCONTEXTID/blog/userid/rss.xml

Again modules and plugins decide what gets sent to user.

=== Temporary files ===
Temporary files are usually used during the lifetime of one script only.
uses:
* exports
* imports
* zipping/unzipping
* processing by executable files (latex, mimetex)

Ideally these files should never use utf-8 (which is a major problem for zipping at the moment).
Proposed new sha1 based file storage is not suitable both for performance and technical reasons.

=== Legacy file storage and serving ===
Going to use good-old separate directories in $CFG->dataroot.

file serving and storage:
# user avatars - user/pix.php
# group avatars - user/pixgroup.php
# tex, algebra - filter/tex/* and filter/algebra/*
# rss cache (?full rss rewrite soon?) - backwards compatibility only rss/file.php

only storage:
#sessions

== File API internals ==

=== File storage on disk ===

Files are stored in $CFG->dataroot (also known as moodledata) in the filedir subfolder.

Files are stored according to the SHA1 hash of their content. This means each file with particular contents is stored once, irrespective of how many times it is included in different places, even if it is referred to by different names. (This idea comes from the git version control system.) To relate a file on disc to a user-comprehensible path or filename, you need to use the file database tables. See the next section.

Suppose a file has SHA1 hash 081371cb102fa559e81993fddc230c79205232ce. Then it will be stored in on disc as moodledata/filedir/08/13/71/081371cb102fa559e81993fddc230c79205232ce.

If you were wondering, in PHP, SHA1 hashes can be computed with either the [http://php.net/sha1 sha1] or [http://php.net/sha1_file sha1_file] functions.

The information in this section should be considered completely internal to the file API. Other parts of the Moodle code should manipulate files using the higher level functions of the file API. For example, they should refer to files by file id in the file table, not the SHA1 hash.

=== Files database tables ===

==== Table: files ====

This table contains one entry for each usage of a file. Enough information is kept here so that the file can be fully identified and retrieved again if necessary.

If, for example, the same image is used in a user's profile, and a forum post, then there will be two rows in this table, one for each use of the file, and Moodle will treat the two as separate files, even though the file is only stored once on disc.

{| class="nicetable"
! Field
! Type
! Default
! Info
|-
| '''id'''
| int(10)
| auto-incrementing
| The unique ID for this file.
|-
| contenthash
| varchar(40)
|
| The sha1 hash of content.
|-
| pathnamehash
| varchar(40)
|
| The sha1 hash of contextid+filearea+itemid+filepath+filename - prevents file duplicates and allows fast lookup
|-
| '''contextid'''
| int(10)
|
| The context id defined in context table - identifies the instance of plugin owning the file.
|-
| filearea
| varchar(50)
|
| Like "submissions", "intro" and "content" (images and swf linked from summaries), etc.; "blogs" and "userfiles" are special case that live at the system context.
|-
| '''itemid'''
| int(10)
|
| Some plugin specific item id (eg. forum post, blog entry or assignment submission or user id for user files)
|-
| filepath
| text
|
| relative path to file from module content root, useful in Scorm and Resource mod - most of the mods do not need this
|-
| filename
| varchar(255)
|
| The full Unicode name of this file (case sensitive)
|-
| '''filesize'''
| int(10)
|
| size of file - bytes
|-
| mimetype
| varchar(100)
| NULL
| type of file
|-
| '''userid'''
| int(10)
| NULL
| Optional - general user id field - meaning depending on plugin
|-
| '''timecreated'''
| int(10)
|
| The time this file was created
|-
| '''timemodified'''
| int(10)
|
| The last time the file was last modified
|}

Indexes:
* non-unique index on (contextid, filearea, itemid)
* non-unique index on (contenthash)
* unique index on (pathnamehash).

The plugin type does not need to be specified because it can be derived from the context. Items like blog that do not have their own context will use their own file area inside a suitable context. In this case, the user context.

Entries with filename = '.' represent directories. Directory entries like this are created automatically when a file is added within them.

Note: 'files' plural used even thought that goes against the [[Development:Database|coding guidelines]] because 'file' is a reserved word.

==== Table: files_metadata ====

This table contains extra metadata about files. Repositories could provide this, or it could be manually edited in the local copy.

{| class="nicetable"
! Field
! Type
! Default
! Info
|-
| '''id'''
| int(10)
| auto-incrementing
|
|-
| '''fileid'''
| int(10)
|
| Foreign key, references files.id
|-
| '''name'''
| varchar(255)
|
| The name of the metadata field
|-
| value
| text
|
| The value of this metadata field
|}

Note: this is not implemented yet.

==== Table: files_sync ====

This table contains information on how to synchronise data with repositories. Data would be synchronised from cron.php or on demand from file manager. The sync would be one way only (repository -> local file).

{| class="nicetable"
! Field
! Type
! Default
! Info
|-
| '''id'''
| int(10)
| auto-incrementing
|
|-
| '''fileid'''
| int(10)
|
| Foreign key, references files.id
|-
| '''repositoryid'''
| int(10)
|
| The repository instance this is associated with, see [[Development:Repository_API]]
|-
| updates
| int(10)
|
| Specifies the update schedule (0 = none, 1 = on demand, other = some period in seconds)
|-
| repositorypath
| text
|
| The full path to the original file on the repository
|-
| timeimportfirst
| int(10)
|
| The first time this file was imported into Moodle
|-
| timeimportlast
| int(10)
|
| The most recent time that this file was imported into Moodle
|}

Note: this is not implemented yet. It may end up being implemented within the Repository API istead. That is, this table may end up being called repository_sync.

==== Table: files_cleanup ====

This table contains candidates for deletion from the file pool. Files are not deleted immediately because there may be multiple references to the same file. Therefore, it is better for performance to simply add a row to this table, and later, on cron, clean the files off disc if they are really no longer used. Also, batch deletion on cron makes it easier to avoid concurrency issues when one user deletes what was the last reference to the file as another user adds a new reference. (The cron cleanup code should be doing appropriate locking.)

{| class="nicetable"
! Field
! Type
! Default
! Info
|-
| '''id'''
| int(10)
| auto-incrementing
|
|-
| contenthash
| varchar(40)
|
|
|}

===Implementation of basic operations===

This is just an overview. See the external API description below for how to do this from client code.

====Storing a file====

# Calculate the SHA1 hash of the file contents.
# Check if a file with this SHA1 hash already exists on disc. If not, store the file there.
# Remove this SHA1 hash from list of deleted files, if present.
# Add the record for this file to the files table.

====Reading a file====

# Fetch the record (which includes the SHA1 hash) for the file you want from the files table.
# Retrieve the contents using the SHA1 hash.

====Deleting a file====

# Store the SHA1 hash of the file being deleted in the files_cleanup table.
# Delete the record from the files table.
# Later, admin/cron.php will actually delete the file from disc if it is no longer used (with proper table locking to prevent race conditions when adding/deleting files simultaneously).

== File browsing and management API ==

This is what other parts of Moodle use to access and manage files. The code is in lib/file/.

These section documents both the public facing parts of this code, and also the inner workings. Hopefully it makes it sufficiently clear which is which. For more information, see the API documentation in the code, and [[Development:Using_the_file_API]].

TODO write the rest of this section.

=== lib/filelib.php ===

Including this file includes all of the other library files.

=== Class: file_browser ===

=== Class: file_info and subclasses ===

=== Class: file_storage ===

=== Class: stored_file ===

=== File exceptions===

== File management user-interface ==

=== File manager ===

All the contexts, file areas and files now form a single huge tree structure, although each user only has access to certain parts of that tree. The file manager (files/index.php) allow users to brows this tree, and manage files within it, according to the level of permissions they have.

Single pane file manager is hard to implement without drag & drop which is notoriously problematic in web based applications. I propose to implement a two pane commander-style file manager. Two pane manager allows you to easily copy/move files between two different contexts (ex: courses).

File manager must not interact directly with filesystem API, instead each module should return traversable tree of files and directories with both real and localised names (localised names are needed for dirs like backupdata).

This code will be in file/.

=== Formslib field types ===

This code will be in lib/form/

* Upload single files.
* Upload multiple files to a files area.
* HTML editor (see next)

=== Integration with the HTML editor ===

Each instance of the HTML editor will be told to store related files in a particular file area.

During editing, files will be stored in a draft files area. Then when the form is submitted they will be (automatically) moved into the real file area.

Files will be selected using the repository file picker.

=== Local files repository plugin ===

Allows users to see an browse files they already have access to within this Moodle, for inclusion in the page currently being edited.

This code will be in repository/local/

== Backwards compatibility ==

=== Content backwards compatibility ===

This should be preserved as much as possible. This will involve rewriting links in content during the upgrade to 2.0.

Some new features (like resource sharing - if implemented) may not work with existing data that still uses files from course files area.

There might be a breakage of links due to special characters stripping in uploaded files which will not match the links in uploaded html files any more. This should not be very common I hope.

===Code backwards compatibility===

Other Moodle code (for example plugins) will have to be converted to the new APIs. See [[Development:Using_the_file_API]] for guidance.

It is not possible to provide backwards-compatibility here. For example, the old $CFG->dataroot/$courseid/ will no longer exist, and there is no way to emulate that, so we won't try.

== Upgrade and migration ==

When a site is upgraded to Moodle 2.0, all the files in moodledata will have to be migrated. This is going to be a pain, like DML/DDL was :-(

The upgrade process should be interruptible (like the Unicode upgrade was) so it can be stopped/restarted any time.

=== Migration of content ===

* resources - move files to new resource content file area; can be done automatically for pdf, image resources; definitely not accurate for uploaded web pages
* questions - image file moved to new area, image tag appended to questions
* moddata files - the easiest part, just move to new storage
* coursefiles - there might be many outdated files :-( :-(
* rss feeds links in readers - will be broken, the new security related code would break it anyway

=== Moving files to files table and file pool ===

The migration process must be interruptable because it might take a very long time. The files would be moved from old location, the restarting would be straightforward.

Proposed stages:
#migration of all course files except moddata - finish marked by some $CFG->files_migrated=true; - this step breaks the old file manager and html editor integration
#migration of blog attachments
#migration of question files
#migration of moddata files - each module is responsible to copy data from converted coursefiles or directly from moddata which is not converted automatically

Some people use symbolic links in coursefiles - we must make sure that those will be copied to new storage in both places, though they can not be linked any more - anybody wanting to have content synced will need to move the files to some repository and set up the sync again.

::Talked about a double task here, when migrating course files to module areas:
::# Parse html files to detect all the dependencies and move them together.
::# Fallback in pluginfile.php so, if something isn't found in module filearea, search for it in course filearea, copying it and finally, serving it.

:: Also we talked about the possibility of add a new setting to resource in order to define if it should work against old coursefiles or new autocontained file areas. Migrated resources will point to old coursefiles while new ones will enforce autocontained file areas.

:: it seems that only resource files will be really complex (because allow arbitrary HTML inclusion). The rest (labels, intros... doesn't) and should be easier to parse.

::[[User:Eloy Lafuente (stronk7)|Eloy Lafuente (stronk7)]] 19:00, 29 June 2008 (CDT)

== Parts of Moodle that need to be modified ==

Of course, all parts of Moodle that use files need to be changed. See MDL-14589 for a more detailed list.

=== Any form where the user can upload files ===

=== Any from containing a HTML editor ===

Since users can embed images etc. there.

=== Backup/restore ===

File handling in backups needs to be fully rewritten - list of files in xml + pool of sha1 named files with contents. This solves the utf-8 trouble here, yay!!

=== Antivirus scanning ===

== Issues that need to be resolved ==

=== Unicode support in zip format ===

''This has now been solved by using the built in zip in PHP 5.2.8.''

Zip format is an old standard for compressing files. It was created long before Unicode existed, and Unicode support was only recently added. There are several ways used for encoding of non-ASCII characters in path names, but unfortunately it is not very standardised. Most Windows packers use DOS encoding.

Client software:
* Windows built-in compression - bundled with Windows, non-standard DOS encoding only
* WinZip - shareware, Unicode option (since v11.2)
* TotalCommander - shareware, single byte(DOS) encoding only
* 7-Zip - free, Unicode or DOS encoding depending on characters used in file name (since v4.58beta)
* Info-ZIP - free, uses some weird character set conversions

PHP extraction:
* Info-ZIP binary execution - no Unicode support at all, mangles character sets in file names (depends on OS, see docs), files must be copied to temp directory before compression and after extraction
* PclZip PHP library - reads single byte encoded names only, problems with random problems and higher memory usage.
* Zip PHP extension - reads single byte encoded names only, 64bit operating system can not open/create archives with more than 500 files (depends on sum of lengths of all filenames and directories, to be fixed in PHP 5.3 and external PECL library, no PHP 5.2.x backport planned!), adding of files is limited by number of free file handles (around 1000 - depends on OS and other PHP code, workaround is to close and reopen archive)

Large file support:
PHP running under 32bit operating systems does not support files >2GB (do not expect fix before PHP 6). This might be a potential problem for larger backups.

Tar Alternative:
* tar with gzip compression - easy to implement in PHP + zlib extension (PclTar, Tar from PEAR or custom code)
* no problem with unicode in *nix, Windows again expects DOS encoding :-(
* seems suitable for backup/restore - yay!

Roadmap:
# add zip processing class that fully hides the underlying library
# use single byte encoding "garbage in/garbage out" approach for encoding of files in zip archives; add new 'zipencoding' string into lang packs (ex: cp852 DOS charset for Czech locale) and use it during extraction, we might support true unicode later when PHP Zip extension does that

== Possible future ideas ==

=== Files maintenance report ===

This would do deep validation of the files on disc. It would:
* Report when there is a row in the files table, but the corresponding file is missing from the file system.
* Report files that still exist on disc, even though no references remain.
* Report orphaned files.
* Report total disc space usage by context (as much as is possible with content-addressible file storage).
* Verify that the SHA1 hash of the contents of each file matches the file name.

In addition, it might offer options to fix these problems, where possible.

=== Support quotas per user, course, etc. ===

People want this.

If we have implemented the above report, it would then just be a matter of adding the interface hooks to stop people uploading more files once the quota has been reached.

(We could also divide the file size by number of instances that are using it, this might be considered more accurate in some scenarios.)

== See also ==

* [[Development:Using the file API]]
* [[Development:Repository API]]
* [[Development:Portfolio API]]
* [[Development:Resource module file API migration]]
* MDL-14589 - File API Meta issue

{{CategoryDeveloper}}
[[Category:Files]]

[[ja:開発:ファイルAPI]]

Development:Deprecated functions in 2.0

2009-09-24T09:21:41Z

Nicolasconnault:

{{Work in progress}}
{{Moodle 2.0}}

This page lists all functions that have been deprecated between 1.9 and 2.0, with instructions on how to upgrade your code. A count of remaining function calls in core is kept next to each function name.

== General notes ==

The following functions have been arranged in alphabetical order, although some of them are very closely related to each other. The number of occurrences of these function calls at the time of writing are indicated in parentheses.

== Functions to migrate ==
=== button_to_popup_window (0) ===
Old code:
<code php>
button_to_popup_window($url, $name, $linkname, $height, $width, $title, $options, $return, $id, $class);
</code>
New code:
<code php>
$form = new html_form();
$form->button->text = $linkname;
$form->button->title = $title;
$form->button->id = $id;
$form->url = $url;
$form->add_class($class);
$form->button->add_action(new popup_action('click', $url, $name, $options));
echo $OUTPUT->button($form);
</code>
Note: popup parameters ($options) '''must''' be prepared as an associative array, not a string as previously. Simply reusing the $options param previously passed to button_to_popup_window() will not work. The $height and $width params are also part of the popup params. See lib/deprecatedlib.php for an example of how the legacy function call is handled.

=== choose_from_menu (1) ===
Old code:
<code php>
choose_from_menu($options, $name, $selected, $nothing, $script, $nothingvalue, $return, $disabled, $tabindex, $id, $listbox, $multiple, $class);
</code>
New code:
<code php>
$select = moodle_select::make($options, $name, $selected); // Required
$select->nothinglabel = $nothing;
$select->nothingvalue = $nothingvalue;
$select->disabled = $disabled;
$select->tabindex = $tabindex;
$select->id = $id;
$select->listbox = $listbox;
$select->multiple = $multiple;
$select->add_classes($class);

echo $OUTPUT->select($select);
</code>

=== choose_from_menu_nested (0) ===
Old code:
<code php>
choose_from_menu_nested($options, $name, $selected, $nothing, $script, $nothingvalue, $return, $disabled, $tabindex);
</code>
New code:
<code php>
$select = moodle_select::make($options, $name, $selected);
$select->tabindex = $tabindex;
$select->disabled = $disabled;
$select->nothingvalue = $nothingvalue;
$select->nested = true;

echo $OUTPUT->select($select);
</code>
Notes:
#The lang string "choose" is no longer used, in favour of "choosedots".
#The $script param is no longer supported. Please use component::add_action() instead.

=== choose_from_menu_yesno (0) ===
Old code:
<code php>
choose_from_menu_yesno($name, $selected, $script, $return, $disabled, $tabindex);
</code>
New code:
<code php>
$select = moodle_select::make_yes_no($name, $selected);
$select->disabled = $disabled;
$select->tabindex = $tabindex;
echo $OUTPUT->select($select);
</code>
Note: The $script param has been dropped, you need to use component::add_action() instead.

=== choose_from_radio (0) ===

=== close_window_button (0) ===
Old code:
<code php>
close_window_button($name, $return, $reloadopener);
</code>
New code:
<code php>
echo $OUTPUT->close_window_button(get_string($name));
</code>
Note: You must pass a language string already processed by get_string().

=== print_continue (0) ===
Old code:
<code php>
print_continue($link, $return);
</code>
New code:
<code php>
echo $OUTPUT->continue_button($link);
</code>

=== doc_link (0) ===
Old code:
<code php>
doc_link($path, $text, $iconpath);
</code>
New code:
<code php>
echo $OUTPUT->doc_link($path, $text, $iconpath);
</code>
Note: This is not for general use, do not confuse with help_icon()

=== formerr (0) ===
Old code:
<code php>
formerr($string);
</code>
New code:
<code php>
echo $OUTPUT->error_text($error);
</code>

=== helpbutton (0) ===
Old code:
<code php>
helpbutton($page, $title, $module, $image, $linktext, $text, $return, $imagetext);
</code>
New code:
<code php>
$helpicon = new help_icon();
$helpicon->page = $page; // required
$helpicon->text = $title; // required
$helpicon->module = $module; // defaults to 'moodle'
$helpicon->linktext = $linktext;

echo $OUTPUT->help_icon($helpicon);
</code>

=== link_to_popup_window (0) ===
Old code:
<code php>
link_to_popup_window($url, $name, $linkname, $height, $width, $title, $options, $return);
</code>
New code:
<code php>
$link = html_link::make($url, $linkname);
$link->title = $title; // optional
$options['height'] = $height; // optional
$options['width'] = $width; // optional
$link->add_action(new popup_action('click', $url, $name, $options));
echo $OUTPUT->link($link);
</code>
Note: popup parameters ($options) '''must''' be prepared as an associative array, not a string as previously. Simply reusing the $options param previously passed to link_to_popup_window() will not work. See lib/deprecatedlib.php for an example of how the legacy function call is handled.

=== notice_yesno (0) ===
Old code:
<code php>
notice_yesno($message, $linkyes, $linkno, $optionsyes, $optionsno, $methodyes, $methodno);
</code>
New code (simplest form):
<code php>
echo $OUTPUT->confirm($message, $linkyes, $linkno);
</code>

New code (with options in arrays):
<code php>
echo $OUTPUT->confirm($message, new moodle_url($linkyes, $optionsyes), new moodle_url($linkno, $optionsno));
</code>

New code (if the "get" method is required):
<code php>
$formcontinue = html_form::make_button($linkyes, $optionsyes, get_string('yes'), $methodyes);
$formcancel = html_form::make_button($linkno, $optionsno, get_string('no'), $methodno);
echo $OUTPUT->confirm($message, $formcontinue, $formcancel);
</code>

=== notify (0) ===
Old code:
<code php>
notify($message, $classes, $align, $return);
</code>
New code:
<code php>
echo $OUTPUT->notification($message, $classes='');
</code>
Note: Use a CSS rule for alignment.

=== popup_form (0) ===
Old code:
<code php>
popup_form($baseurl, $options, $formid, $selected, $nothing, $help, $helptext, $return, $targetwindow, $selectlabel, $optionsextra, $submitvalue, $disabled, $showbutton);
</code>
New code:
<code php>
// if $baseurl == 'http://domain.com/index.php?var1=1&var2='
$select = html_select::make_popup_form('http://domain.com/index.php?var1=1', 'var2', $options, $formid, $selected);
$select->disabled = $disabled; // optional
$select->set_label($selectlabel, $select->id); // optional, set to false if no "nothing" option is desired (when $selectlabel == '' in original call)
$select->set_help_icon($help, $helptext); // optional
$select->form->button->text = $submitvalue; // optional

echo $OUTPUT->select($select);
</code>
Notes:
*The $optionsextra param is not supported. If your code uses it, you should find another way to add extra params to your <option> tags without using this horrible hack which usually includes inline JS or CSS.

=== print_arrow (15) ===
=== print_box* (0) ===
Old code:
<code php>
print_box($message, $classes, $ids, $return);
print_box_start($classes, $ids, $return);
print_box_end();
</code>
New code:
<code php>
echo $OUTPUT->box($message, $classes, $ids);
echo $OUTPUT->box_start($classes, $ids);
echo $OUTPUT->box_end();
</code>

=== print_checkbox (10) ===
Old code:
<code php>
print_checkbox($name, $value, $checked, $label, $alt, $script, $return);
</code>
New code:
<code php>
$checkbox = new html_select_option();
$checkbox->value = $value; // Required
$checkbox->selected = $checked;
$checkbox->text = $label;
$checkbox->label->text = $label;
$checkbox->alt = $alt;

echo $OUTPUT->checkbox($checkbox, $name);
</code>
Note: html_select_option is a component that can be rendered as a select <option>, a radio button or a checkbox. It holds sufficient information to render all these elements, except the $name variable which is attached to a moodle_select component. This is why we pass the $name string to $OUTPUT->checkbox().

=== print_container (0) ===
Old code:
<code php>
print_container($message, $clearfix, $classes, $idbase, $return);
</code>
New code:
<code php>
if ($clearfix) {
$classes .= ' clearfix';
}
echo $OUTPUT->container($message, $classes, $idbase);
</code>

=== print_date_selector (0) ===

=== print_footer (0) ===
Old code:
<code php>
print_footer($course, $usercourse, $return);
</code>
New code:
<code php>
echo $OUTPUT->footer();
</code>
Notes: No parameters are required.

=== print_header (501) ===
Old code:
<code php>
print_header($title, $heading, $navigation, $focus, $meta, $cache, $button, $menu, $usexml, $bodytags, $return);
</code>
New code:
<code php>
$PAGE->set_heading($heading); // Required
$PAGE->set_title($title);
$PAGE->set_cacheable($cache);
$PAGE->set_focuscontrol($focus);
$PAGE->set_button($button);
echo $OUTPUT->header($navigation, $menu);
</code>
Note: Navigation code is being rewritten, this doc will then be updated with the new usage.

=== print_heading_with_help (0) ===

=== print_heading (0) ===
Old code:
<code php>
print_heading($text, $align, $size, $class, $return, $id);
</code>
New code:
<code php>
echo $OUTPUT->heading($text, $size, $class, $id);
</code>
Note: Use a CSS class rule to control alignment.

=== print_heading_block (0) ===

=== print_headline (0) ===
Old code:
<code php>
print_headline($text, $size);
</code>
New code:
<code php>
echo $OUTPUT->heading($text, $size);
</code>

=== print_paging_bar (2) ===

Old code:
<code php>
print_paging_bar($totalcount, $page, $perpage, $baseurl, $pagevar, $nocurr, $return);
</code>
New code:
<code php>
$pagingbar = new moodle_paging_bar();
$pagingbar->totalcount = $totalcount; // Required
$pagingbar->page = $page; // Required
$pagingbar->perpage = $perpage; // Required
$pagingbar->baseurl = $baseurl; // Required
$pagingbar->pagevar = $pagevar;
echo $OUTPUT->paging_bar($pagingbar);
</code>
Note: The last two instances of print_paging_bar are found in the old tablelib, which will soon be deprecated.

Note: $nocurr has been dropped. Current page number is never displayed as a link

=== print_scale_menu_helpbutton (0) ===
Old code:
<code php>
print_scale_menu_helpbutton($courseid, $scale);
</code>
New code:
<code php>
echo $OUTPUT->help_button(help_button::make_scale_menu($courseid, $scale));
</code>

=== print_side_block (4) ===
=== print_single_button (0) ===
Old code:
<code php>
print_single_button($link, $options, $label, $method, $notusedanymore, $return, $tooltip, $disabled, $jsconfirmmessage, $formid)
</code>
New code:
<code php>
$form = new html_form();
$form->url = new moodle_url($link, $options); // Required
$form->button = new html_button();
$form->button->text = $label; // Required
$form->button->disabled = $disabled;
$form->button->title = $tooltip;
$form->method = $method;
$form->id = $formid;

if ($jsconfirmmessage) {
$confirmaction = new component_action('click', 'confirm_dialog', array('message' => $jsconfirmmessage));
$form->button->add_action($confirmaction);
}

$output = $OUTPUT->button($form);
</code>

=== print_spacer (0) ===
Old code:
<code php>
print_spacer($height, $width, $br, $return);
</code>
New code:
<code php>
$spacer = new html_image();
$spacer->height = $height;
$spacer->width = $width;
echo $OUTPUT->spacer($spacer);
</code>
Note: The $br attribute has been dropped. You can simply add a line break manually if you need one.

=== print_table (0) ===
Old code:
<code php>
$table = new stdClass();
$table->class = 'mytable';
$table->head = array('Firstname', 'Lastname');
$table->rowclasses = array();
// (other table properties here)
$table->data = array(array(...),array(...),array(...));
print_table($table, $return);
</code>
New code:
<code php>
$table = new html_table();
$table->set_classes('mytable'); // note the new style of setting CSS class
$table->head = array('First name', 'Last name');
$table->colclasses = array('name fname','name lname');
$table->rowclasses = array();
// (other table properties here)
$table->data = array(array(...),array(...),array(...));
echo $OUTPUT->table($newtable);
</code>
Notes: The new html_table object has the same member variables as the one originally used by print_table(), but has additional, required methods. You must map the old $table object to the new html_table object, as demonstrated above and in lib/deprecatedlib.php (see old print_table function).

=== print_textarea (55) ===
=== print_textfield (0) ===

=== print_time_selector (0) ===

=== print_user_picture (0) ===

Old code:
<code php>
print_user_picture($user, $courseid, $picture, $size, $return, $link, $target, $alttext);
</code>
New code (simple):
<code php>
$userpic = new moodle_user_picture();
$userpic->user = $user;
$userpic->courseid = $courseid;
echo $OUTPUT->user_picture($userpic);
</code>
New code (complex: alternate text, size, different image and popup action):
<code php>
$userpic = new user_picture();
$userpic->user = $user;
$userpic->courseid = $courseid;
$userpic->size = $size;
$userpic->link = $link;
$userpic->alttext = $alttext;
$userpic->image->src = $picture;
$userpic->add_action(new popup_action('click', new moodle_url($target)));

echo $OUTPUT->user_picture($userpic);
</code>

=== update_course_button (0) ===

=== update_module_button (94) ===
Old code:
<code php>
$button = update_module_button($cm->id, $course->id, get_string('modulename', 'workshop')); // passed to print_header_simple()
</code>
New code:
<code php>
$PAGE->set_button($OUTPUT->update_module_button($cm->id, 'workshop'));
</code>
Note: $courseid param has been dropped.

=== update_tag_button (0) ===

== Non-supported functions ==
These functions have been completely dropped in 2.0, most likely because they were used very little or not at all. All calls to these functions in core should have been replaced.
=== blocks_print_group ===
=== print_file_picture ===
=== print_png ===
=== print_scale_menu ===
=== print_side_block_end ===
=== print_side_block_start ===
=== print_timer_selector ===
=== print_user ===
=== update_categories_search_button ===
=== update_mymoodle_icon ===

==See also==

* [[Developement:How_Moodle_outputs_HTML]]
* [[Development:Migrating your code to the 2.0 rendering_API]]

{{CategoryDeveloper}}

Development:Deprecated functions in 2.0

2009-09-24T09:20:33Z

Nicolasconnault: /* General notes */

{{Work in progress}}
{{Moodle 2.0}}

This page lists the old HTML-outputting functions of pre-2.0 lib/weblib.php and their 2.0 equivalents using $OUTPUT functions.

== General notes ==

The following functions have been arranged in alphabetical order, although some of them are very closely related to each other. The number of occurrences of these function calls at the time of writing are indicated in parentheses.

== Functions to migrate ==
=== button_to_popup_window (0) ===
Old code:
<code php>
button_to_popup_window($url, $name, $linkname, $height, $width, $title, $options, $return, $id, $class);
</code>
New code:
<code php>
$form = new html_form();
$form->button->text = $linkname;
$form->button->title = $title;
$form->button->id = $id;
$form->url = $url;
$form->add_class($class);
$form->button->add_action(new popup_action('click', $url, $name, $options));
echo $OUTPUT->button($form);
</code>
Note: popup parameters ($options) '''must''' be prepared as an associative array, not a string as previously. Simply reusing the $options param previously passed to button_to_popup_window() will not work. The $height and $width params are also part of the popup params. See lib/deprecatedlib.php for an example of how the legacy function call is handled.

=== choose_from_menu (1) ===
Old code:
<code php>
choose_from_menu($options, $name, $selected, $nothing, $script, $nothingvalue, $return, $disabled, $tabindex, $id, $listbox, $multiple, $class);
</code>
New code:
<code php>
$select = moodle_select::make($options, $name, $selected); // Required
$select->nothinglabel = $nothing;
$select->nothingvalue = $nothingvalue;
$select->disabled = $disabled;
$select->tabindex = $tabindex;
$select->id = $id;
$select->listbox = $listbox;
$select->multiple = $multiple;
$select->add_classes($class);

echo $OUTPUT->select($select);
</code>

=== choose_from_menu_nested (0) ===
Old code:
<code php>
choose_from_menu_nested($options, $name, $selected, $nothing, $script, $nothingvalue, $return, $disabled, $tabindex);
</code>
New code:
<code php>
$select = moodle_select::make($options, $name, $selected);
$select->tabindex = $tabindex;
$select->disabled = $disabled;
$select->nothingvalue = $nothingvalue;
$select->nested = true;

echo $OUTPUT->select($select);
</code>
Notes:
#The lang string "choose" is no longer used, in favour of "choosedots".
#The $script param is no longer supported. Please use component::add_action() instead.

=== choose_from_menu_yesno (0) ===
Old code:
<code php>
choose_from_menu_yesno($name, $selected, $script, $return, $disabled, $tabindex);
</code>
New code:
<code php>
$select = moodle_select::make_yes_no($name, $selected);
$select->disabled = $disabled;
$select->tabindex = $tabindex;
echo $OUTPUT->select($select);
</code>
Note: The $script param has been dropped, you need to use component::add_action() instead.

=== choose_from_radio (0) ===

=== close_window_button (0) ===
Old code:
<code php>
close_window_button($name, $return, $reloadopener);
</code>
New code:
<code php>
echo $OUTPUT->close_window_button(get_string($name));
</code>
Note: You must pass a language string already processed by get_string().

=== print_continue (0) ===
Old code:
<code php>
print_continue($link, $return);
</code>
New code:
<code php>
echo $OUTPUT->continue_button($link);
</code>

=== doc_link (0) ===
Old code:
<code php>
doc_link($path, $text, $iconpath);
</code>
New code:
<code php>
echo $OUTPUT->doc_link($path, $text, $iconpath);
</code>
Note: This is not for general use, do not confuse with help_icon()

=== formerr (0) ===
Old code:
<code php>
formerr($string);
</code>
New code:
<code php>
echo $OUTPUT->error_text($error);
</code>

=== helpbutton (0) ===
Old code:
<code php>
helpbutton($page, $title, $module, $image, $linktext, $text, $return, $imagetext);
</code>
New code:
<code php>
$helpicon = new help_icon();
$helpicon->page = $page; // required
$helpicon->text = $title; // required
$helpicon->module = $module; // defaults to 'moodle'
$helpicon->linktext = $linktext;

echo $OUTPUT->help_icon($helpicon);
</code>

=== link_to_popup_window (0) ===
Old code:
<code php>
link_to_popup_window($url, $name, $linkname, $height, $width, $title, $options, $return);
</code>
New code:
<code php>
$link = html_link::make($url, $linkname);
$link->title = $title; // optional
$options['height'] = $height; // optional
$options['width'] = $width; // optional
$link->add_action(new popup_action('click', $url, $name, $options));
echo $OUTPUT->link($link);
</code>
Note: popup parameters ($options) '''must''' be prepared as an associative array, not a string as previously. Simply reusing the $options param previously passed to link_to_popup_window() will not work. See lib/deprecatedlib.php for an example of how the legacy function call is handled.

=== notice_yesno (0) ===
Old code:
<code php>
notice_yesno($message, $linkyes, $linkno, $optionsyes, $optionsno, $methodyes, $methodno);
</code>
New code (simplest form):
<code php>
echo $OUTPUT->confirm($message, $linkyes, $linkno);
</code>

New code (with options in arrays):
<code php>
echo $OUTPUT->confirm($message, new moodle_url($linkyes, $optionsyes), new moodle_url($linkno, $optionsno));
</code>

New code (if the "get" method is required):
<code php>
$formcontinue = html_form::make_button($linkyes, $optionsyes, get_string('yes'), $methodyes);
$formcancel = html_form::make_button($linkno, $optionsno, get_string('no'), $methodno);
echo $OUTPUT->confirm($message, $formcontinue, $formcancel);
</code>

=== notify (0) ===
Old code:
<code php>
notify($message, $classes, $align, $return);
</code>
New code:
<code php>
echo $OUTPUT->notification($message, $classes='');
</code>
Note: Use a CSS rule for alignment.

=== popup_form (0) ===
Old code:
<code php>
popup_form($baseurl, $options, $formid, $selected, $nothing, $help, $helptext, $return, $targetwindow, $selectlabel, $optionsextra, $submitvalue, $disabled, $showbutton);
</code>
New code:
<code php>
// if $baseurl == 'http://domain.com/index.php?var1=1&var2='
$select = html_select::make_popup_form('http://domain.com/index.php?var1=1', 'var2', $options, $formid, $selected);
$select->disabled = $disabled; // optional
$select->set_label($selectlabel, $select->id); // optional, set to false if no "nothing" option is desired (when $selectlabel == '' in original call)
$select->set_help_icon($help, $helptext); // optional
$select->form->button->text = $submitvalue; // optional

echo $OUTPUT->select($select);
</code>
Notes:
*The $optionsextra param is not supported. If your code uses it, you should find another way to add extra params to your <option> tags without using this horrible hack which usually includes inline JS or CSS.

=== print_arrow (15) ===
=== print_box* (0) ===
Old code:
<code php>
print_box($message, $classes, $ids, $return);
print_box_start($classes, $ids, $return);
print_box_end();
</code>
New code:
<code php>
echo $OUTPUT->box($message, $classes, $ids);
echo $OUTPUT->box_start($classes, $ids);
echo $OUTPUT->box_end();
</code>

=== print_checkbox (10) ===
Old code:
<code php>
print_checkbox($name, $value, $checked, $label, $alt, $script, $return);
</code>
New code:
<code php>
$checkbox = new html_select_option();
$checkbox->value = $value; // Required
$checkbox->selected = $checked;
$checkbox->text = $label;
$checkbox->label->text = $label;
$checkbox->alt = $alt;

echo $OUTPUT->checkbox($checkbox, $name);
</code>
Note: html_select_option is a component that can be rendered as a select <option>, a radio button or a checkbox. It holds sufficient information to render all these elements, except the $name variable which is attached to a moodle_select component. This is why we pass the $name string to $OUTPUT->checkbox().

=== print_container (0) ===
Old code:
<code php>
print_container($message, $clearfix, $classes, $idbase, $return);
</code>
New code:
<code php>
if ($clearfix) {
$classes .= ' clearfix';
}
echo $OUTPUT->container($message, $classes, $idbase);
</code>

=== print_date_selector (0) ===

=== print_footer (0) ===
Old code:
<code php>
print_footer($course, $usercourse, $return);
</code>
New code:
<code php>
echo $OUTPUT->footer();
</code>
Notes: No parameters are required.

=== print_header (501) ===
Old code:
<code php>
print_header($title, $heading, $navigation, $focus, $meta, $cache, $button, $menu, $usexml, $bodytags, $return);
</code>
New code:
<code php>
$PAGE->set_heading($heading); // Required
$PAGE->set_title($title);
$PAGE->set_cacheable($cache);
$PAGE->set_focuscontrol($focus);
$PAGE->set_button($button);
echo $OUTPUT->header($navigation, $menu);
</code>
Note: Navigation code is being rewritten, this doc will then be updated with the new usage.

=== print_heading_with_help (0) ===

=== print_heading (0) ===
Old code:
<code php>
print_heading($text, $align, $size, $class, $return, $id);
</code>
New code:
<code php>
echo $OUTPUT->heading($text, $size, $class, $id);
</code>
Note: Use a CSS class rule to control alignment.

=== print_heading_block (0) ===

=== print_headline (0) ===
Old code:
<code php>
print_headline($text, $size);
</code>
New code:
<code php>
echo $OUTPUT->heading($text, $size);
</code>

=== print_paging_bar (2) ===

Old code:
<code php>
print_paging_bar($totalcount, $page, $perpage, $baseurl, $pagevar, $nocurr, $return);
</code>
New code:
<code php>
$pagingbar = new moodle_paging_bar();
$pagingbar->totalcount = $totalcount; // Required
$pagingbar->page = $page; // Required
$pagingbar->perpage = $perpage; // Required
$pagingbar->baseurl = $baseurl; // Required
$pagingbar->pagevar = $pagevar;
echo $OUTPUT->paging_bar($pagingbar);
</code>
Note: The last two instances of print_paging_bar are found in the old tablelib, which will soon be deprecated.

Note: $nocurr has been dropped. Current page number is never displayed as a link

=== print_scale_menu_helpbutton (0) ===
Old code:
<code php>
print_scale_menu_helpbutton($courseid, $scale);
</code>
New code:
<code php>
echo $OUTPUT->help_button(help_button::make_scale_menu($courseid, $scale));
</code>

=== print_side_block (4) ===
=== print_single_button (0) ===
Old code:
<code php>
print_single_button($link, $options, $label, $method, $notusedanymore, $return, $tooltip, $disabled, $jsconfirmmessage, $formid)
</code>
New code:
<code php>
$form = new html_form();
$form->url = new moodle_url($link, $options); // Required
$form->button = new html_button();
$form->button->text = $label; // Required
$form->button->disabled = $disabled;
$form->button->title = $tooltip;
$form->method = $method;
$form->id = $formid;

if ($jsconfirmmessage) {
$confirmaction = new component_action('click', 'confirm_dialog', array('message' => $jsconfirmmessage));
$form->button->add_action($confirmaction);
}

$output = $OUTPUT->button($form);
</code>

=== print_spacer (0) ===
Old code:
<code php>
print_spacer($height, $width, $br, $return);
</code>
New code:
<code php>
$spacer = new html_image();
$spacer->height = $height;
$spacer->width = $width;
echo $OUTPUT->spacer($spacer);
</code>
Note: The $br attribute has been dropped. You can simply add a line break manually if you need one.

=== print_table (0) ===
Old code:
<code php>
$table = new stdClass();
$table->class = 'mytable';
$table->head = array('Firstname', 'Lastname');
$table->rowclasses = array();
// (other table properties here)
$table->data = array(array(...),array(...),array(...));
print_table($table, $return);
</code>
New code:
<code php>
$table = new html_table();
$table->set_classes('mytable'); // note the new style of setting CSS class
$table->head = array('First name', 'Last name');
$table->colclasses = array('name fname','name lname');
$table->rowclasses = array();
// (other table properties here)
$table->data = array(array(...),array(...),array(...));
echo $OUTPUT->table($newtable);
</code>
Notes: The new html_table object has the same member variables as the one originally used by print_table(), but has additional, required methods. You must map the old $table object to the new html_table object, as demonstrated above and in lib/deprecatedlib.php (see old print_table function).

=== print_textarea (55) ===
=== print_textfield (0) ===

=== print_time_selector (0) ===

=== print_user_picture (0) ===

Old code:
<code php>
print_user_picture($user, $courseid, $picture, $size, $return, $link, $target, $alttext);
</code>
New code (simple):
<code php>
$userpic = new moodle_user_picture();
$userpic->user = $user;
$userpic->courseid = $courseid;
echo $OUTPUT->user_picture($userpic);
</code>
New code (complex: alternate text, size, different image and popup action):
<code php>
$userpic = new user_picture();
$userpic->user = $user;
$userpic->courseid = $courseid;
$userpic->size = $size;
$userpic->link = $link;
$userpic->alttext = $alttext;
$userpic->image->src = $picture;
$userpic->add_action(new popup_action('click', new moodle_url($target)));

echo $OUTPUT->user_picture($userpic);
</code>

=== update_course_button (0) ===

=== update_module_button (94) ===
Old code:
<code php>
$button = update_module_button($cm->id, $course->id, get_string('modulename', 'workshop')); // passed to print_header_simple()
</code>
New code:
<code php>
$PAGE->set_button($OUTPUT->update_module_button($cm->id, 'workshop'));
</code>
Note: $courseid param has been dropped.

=== update_tag_button (0) ===

== Non-supported functions ==
These functions have been completely dropped in 2.0, most likely because they were used very little or not at all. All calls to these functions in core should have been replaced.
=== blocks_print_group ===
=== print_file_picture ===
=== print_png ===
=== print_scale_menu ===
=== print_side_block_end ===
=== print_side_block_start ===
=== print_timer_selector ===
=== print_user ===
=== update_categories_search_button ===
=== update_mymoodle_icon ===

==See also==

* [[Developement:How_Moodle_outputs_HTML]]
* [[Development:Migrating your code to the 2.0 rendering_API]]

{{CategoryDeveloper}}

Development:Outputting HTML in 2.0

2009-09-24T09:19:56Z

Nicolasconnault: Development:Outputting HTML in 2.0 moved to Development:Deprecated functions in 2.0: Expanding the use of this page for all deprecated functions

#REDIRECT [[Development:Deprecated functions in 2.0]]

Development:Deprecated functions in 2.0

2009-09-24T09:19:56Z

Nicolasconnault: Development:Outputting HTML in 2.0 moved to Development:Deprecated functions in 2.0: Expanding the use of this page for all deprecated functions

{{Work in progress}}
{{Moodle 2.0}}

This page lists the old HTML-outputting functions of pre-2.0 lib/weblib.php and their 2.0 equivalents using $OUTPUT functions.

== General notes ==
The principle of the new rendering API is to let the developer build metadata-rich components that ''represent'' HTML elements, but may be rendered in many different ways. A menu component, for example, could be rendered as a <select> element, or as a list of radio buttons or check boxes.

The following functions have been arranged in alphabetical order, although some of them are very closely related to each other. The number of occurrences of these function calls at the time of writing are indicated in parentheses.

== Functions to migrate ==
=== button_to_popup_window (0) ===
Old code:
<code php>
button_to_popup_window($url, $name, $linkname, $height, $width, $title, $options, $return, $id, $class);
</code>
New code:
<code php>
$form = new html_form();
$form->button->text = $linkname;
$form->button->title = $title;
$form->button->id = $id;
$form->url = $url;
$form->add_class($class);
$form->button->add_action(new popup_action('click', $url, $name, $options));
echo $OUTPUT->button($form);
</code>
Note: popup parameters ($options) '''must''' be prepared as an associative array, not a string as previously. Simply reusing the $options param previously passed to button_to_popup_window() will not work. The $height and $width params are also part of the popup params. See lib/deprecatedlib.php for an example of how the legacy function call is handled.

=== choose_from_menu (1) ===
Old code:
<code php>
choose_from_menu($options, $name, $selected, $nothing, $script, $nothingvalue, $return, $disabled, $tabindex, $id, $listbox, $multiple, $class);
</code>
New code:
<code php>
$select = moodle_select::make($options, $name, $selected); // Required
$select->nothinglabel = $nothing;
$select->nothingvalue = $nothingvalue;
$select->disabled = $disabled;
$select->tabindex = $tabindex;
$select->id = $id;
$select->listbox = $listbox;
$select->multiple = $multiple;
$select->add_classes($class);

echo $OUTPUT->select($select);
</code>

=== choose_from_menu_nested (0) ===
Old code:
<code php>
choose_from_menu_nested($options, $name, $selected, $nothing, $script, $nothingvalue, $return, $disabled, $tabindex);
</code>
New code:
<code php>
$select = moodle_select::make($options, $name, $selected);
$select->tabindex = $tabindex;
$select->disabled = $disabled;
$select->nothingvalue = $nothingvalue;
$select->nested = true;

echo $OUTPUT->select($select);
</code>
Notes:
#The lang string "choose" is no longer used, in favour of "choosedots".
#The $script param is no longer supported. Please use component::add_action() instead.

=== choose_from_menu_yesno (0) ===
Old code:
<code php>
choose_from_menu_yesno($name, $selected, $script, $return, $disabled, $tabindex);
</code>
New code:
<code php>
$select = moodle_select::make_yes_no($name, $selected);
$select->disabled = $disabled;
$select->tabindex = $tabindex;
echo $OUTPUT->select($select);
</code>
Note: The $script param has been dropped, you need to use component::add_action() instead.

=== choose_from_radio (0) ===

=== close_window_button (0) ===
Old code:
<code php>
close_window_button($name, $return, $reloadopener);
</code>
New code:
<code php>
echo $OUTPUT->close_window_button(get_string($name));
</code>
Note: You must pass a language string already processed by get_string().

=== print_continue (0) ===
Old code:
<code php>
print_continue($link, $return);
</code>
New code:
<code php>
echo $OUTPUT->continue_button($link);
</code>

=== doc_link (0) ===
Old code:
<code php>
doc_link($path, $text, $iconpath);
</code>
New code:
<code php>
echo $OUTPUT->doc_link($path, $text, $iconpath);
</code>
Note: This is not for general use, do not confuse with help_icon()

=== formerr (0) ===
Old code:
<code php>
formerr($string);
</code>
New code:
<code php>
echo $OUTPUT->error_text($error);
</code>

=== helpbutton (0) ===
Old code:
<code php>
helpbutton($page, $title, $module, $image, $linktext, $text, $return, $imagetext);
</code>
New code:
<code php>
$helpicon = new help_icon();
$helpicon->page = $page; // required
$helpicon->text = $title; // required
$helpicon->module = $module; // defaults to 'moodle'
$helpicon->linktext = $linktext;

echo $OUTPUT->help_icon($helpicon);
</code>

=== link_to_popup_window (0) ===
Old code:
<code php>
link_to_popup_window($url, $name, $linkname, $height, $width, $title, $options, $return);
</code>
New code:
<code php>
$link = html_link::make($url, $linkname);
$link->title = $title; // optional
$options['height'] = $height; // optional
$options['width'] = $width; // optional
$link->add_action(new popup_action('click', $url, $name, $options));
echo $OUTPUT->link($link);
</code>
Note: popup parameters ($options) '''must''' be prepared as an associative array, not a string as previously. Simply reusing the $options param previously passed to link_to_popup_window() will not work. See lib/deprecatedlib.php for an example of how the legacy function call is handled.

=== notice_yesno (0) ===
Old code:
<code php>
notice_yesno($message, $linkyes, $linkno, $optionsyes, $optionsno, $methodyes, $methodno);
</code>
New code (simplest form):
<code php>
echo $OUTPUT->confirm($message, $linkyes, $linkno);
</code>

New code (with options in arrays):
<code php>
echo $OUTPUT->confirm($message, new moodle_url($linkyes, $optionsyes), new moodle_url($linkno, $optionsno));
</code>

New code (if the "get" method is required):
<code php>
$formcontinue = html_form::make_button($linkyes, $optionsyes, get_string('yes'), $methodyes);
$formcancel = html_form::make_button($linkno, $optionsno, get_string('no'), $methodno);
echo $OUTPUT->confirm($message, $formcontinue, $formcancel);
</code>

=== notify (0) ===
Old code:
<code php>
notify($message, $classes, $align, $return);
</code>
New code:
<code php>
echo $OUTPUT->notification($message, $classes='');
</code>
Note: Use a CSS rule for alignment.

=== popup_form (0) ===
Old code:
<code php>
popup_form($baseurl, $options, $formid, $selected, $nothing, $help, $helptext, $return, $targetwindow, $selectlabel, $optionsextra, $submitvalue, $disabled, $showbutton);
</code>
New code:
<code php>
// if $baseurl == 'http://domain.com/index.php?var1=1&var2='
$select = html_select::make_popup_form('http://domain.com/index.php?var1=1', 'var2', $options, $formid, $selected);
$select->disabled = $disabled; // optional
$select->set_label($selectlabel, $select->id); // optional, set to false if no "nothing" option is desired (when $selectlabel == '' in original call)
$select->set_help_icon($help, $helptext); // optional
$select->form->button->text = $submitvalue; // optional

echo $OUTPUT->select($select);
</code>
Notes:
*The $optionsextra param is not supported. If your code uses it, you should find another way to add extra params to your <option> tags without using this horrible hack which usually includes inline JS or CSS.

=== print_arrow (15) ===
=== print_box* (0) ===
Old code:
<code php>
print_box($message, $classes, $ids, $return);
print_box_start($classes, $ids, $return);
print_box_end();
</code>
New code:
<code php>
echo $OUTPUT->box($message, $classes, $ids);
echo $OUTPUT->box_start($classes, $ids);
echo $OUTPUT->box_end();
</code>

=== print_checkbox (10) ===
Old code:
<code php>
print_checkbox($name, $value, $checked, $label, $alt, $script, $return);
</code>
New code:
<code php>
$checkbox = new html_select_option();
$checkbox->value = $value; // Required
$checkbox->selected = $checked;
$checkbox->text = $label;
$checkbox->label->text = $label;
$checkbox->alt = $alt;

echo $OUTPUT->checkbox($checkbox, $name);
</code>
Note: html_select_option is a component that can be rendered as a select <option>, a radio button or a checkbox. It holds sufficient information to render all these elements, except the $name variable which is attached to a moodle_select component. This is why we pass the $name string to $OUTPUT->checkbox().

=== print_container (0) ===
Old code:
<code php>
print_container($message, $clearfix, $classes, $idbase, $return);
</code>
New code:
<code php>
if ($clearfix) {
$classes .= ' clearfix';
}
echo $OUTPUT->container($message, $classes, $idbase);
</code>

=== print_date_selector (0) ===

=== print_footer (0) ===
Old code:
<code php>
print_footer($course, $usercourse, $return);
</code>
New code:
<code php>
echo $OUTPUT->footer();
</code>
Notes: No parameters are required.

=== print_header (501) ===
Old code:
<code php>
print_header($title, $heading, $navigation, $focus, $meta, $cache, $button, $menu, $usexml, $bodytags, $return);
</code>
New code:
<code php>
$PAGE->set_heading($heading); // Required
$PAGE->set_title($title);
$PAGE->set_cacheable($cache);
$PAGE->set_focuscontrol($focus);
$PAGE->set_button($button);
echo $OUTPUT->header($navigation, $menu);
</code>
Note: Navigation code is being rewritten, this doc will then be updated with the new usage.

=== print_heading_with_help (0) ===

=== print_heading (0) ===
Old code:
<code php>
print_heading($text, $align, $size, $class, $return, $id);
</code>
New code:
<code php>
echo $OUTPUT->heading($text, $size, $class, $id);
</code>
Note: Use a CSS class rule to control alignment.

=== print_heading_block (0) ===

=== print_headline (0) ===
Old code:
<code php>
print_headline($text, $size);
</code>
New code:
<code php>
echo $OUTPUT->heading($text, $size);
</code>

=== print_paging_bar (2) ===

Old code:
<code php>
print_paging_bar($totalcount, $page, $perpage, $baseurl, $pagevar, $nocurr, $return);
</code>
New code:
<code php>
$pagingbar = new moodle_paging_bar();
$pagingbar->totalcount = $totalcount; // Required
$pagingbar->page = $page; // Required
$pagingbar->perpage = $perpage; // Required
$pagingbar->baseurl = $baseurl; // Required
$pagingbar->pagevar = $pagevar;
echo $OUTPUT->paging_bar($pagingbar);
</code>
Note: The last two instances of print_paging_bar are found in the old tablelib, which will soon be deprecated.

Note: $nocurr has been dropped. Current page number is never displayed as a link

=== print_scale_menu_helpbutton (0) ===
Old code:
<code php>
print_scale_menu_helpbutton($courseid, $scale);
</code>
New code:
<code php>
echo $OUTPUT->help_button(help_button::make_scale_menu($courseid, $scale));
</code>

=== print_side_block (4) ===
=== print_single_button (0) ===
Old code:
<code php>
print_single_button($link, $options, $label, $method, $notusedanymore, $return, $tooltip, $disabled, $jsconfirmmessage, $formid)
</code>
New code:
<code php>
$form = new html_form();
$form->url = new moodle_url($link, $options); // Required
$form->button = new html_button();
$form->button->text = $label; // Required
$form->button->disabled = $disabled;
$form->button->title = $tooltip;
$form->method = $method;
$form->id = $formid;

if ($jsconfirmmessage) {
$confirmaction = new component_action('click', 'confirm_dialog', array('message' => $jsconfirmmessage));
$form->button->add_action($confirmaction);
}

$output = $OUTPUT->button($form);
</code>

=== print_spacer (0) ===
Old code:
<code php>
print_spacer($height, $width, $br, $return);
</code>
New code:
<code php>
$spacer = new html_image();
$spacer->height = $height;
$spacer->width = $width;
echo $OUTPUT->spacer($spacer);
</code>
Note: The $br attribute has been dropped. You can simply add a line break manually if you need one.

=== print_table (0) ===
Old code:
<code php>
$table = new stdClass();
$table->class = 'mytable';
$table->head = array('Firstname', 'Lastname');
$table->rowclasses = array();
// (other table properties here)
$table->data = array(array(...),array(...),array(...));
print_table($table, $return);
</code>
New code:
<code php>
$table = new html_table();
$table->set_classes('mytable'); // note the new style of setting CSS class
$table->head = array('First name', 'Last name');
$table->colclasses = array('name fname','name lname');
$table->rowclasses = array();
// (other table properties here)
$table->data = array(array(...),array(...),array(...));
echo $OUTPUT->table($newtable);
</code>
Notes: The new html_table object has the same member variables as the one originally used by print_table(), but has additional, required methods. You must map the old $table object to the new html_table object, as demonstrated above and in lib/deprecatedlib.php (see old print_table function).

=== print_textarea (55) ===
=== print_textfield (0) ===

=== print_time_selector (0) ===

=== print_user_picture (0) ===

Old code:
<code php>
print_user_picture($user, $courseid, $picture, $size, $return, $link, $target, $alttext);
</code>
New code (simple):
<code php>
$userpic = new moodle_user_picture();
$userpic->user = $user;
$userpic->courseid = $courseid;
echo $OUTPUT->user_picture($userpic);
</code>
New code (complex: alternate text, size, different image and popup action):
<code php>
$userpic = new user_picture();
$userpic->user = $user;
$userpic->courseid = $courseid;
$userpic->size = $size;
$userpic->link = $link;
$userpic->alttext = $alttext;
$userpic->image->src = $picture;
$userpic->add_action(new popup_action('click', new moodle_url($target)));

echo $OUTPUT->user_picture($userpic);
</code>

=== update_course_button (0) ===

=== update_module_button (94) ===
Old code:
<code php>
$button = update_module_button($cm->id, $course->id, get_string('modulename', 'workshop')); // passed to print_header_simple()
</code>
New code:
<code php>
$PAGE->set_button($OUTPUT->update_module_button($cm->id, 'workshop'));
</code>
Note: $courseid param has been dropped.

=== update_tag_button (0) ===

== Non-supported functions ==
These functions have been completely dropped in 2.0, most likely because they were used very little or not at all. All calls to these functions in core should have been replaced.
=== blocks_print_group ===
=== print_file_picture ===
=== print_png ===
=== print_scale_menu ===
=== print_side_block_end ===
=== print_side_block_start ===
=== print_timer_selector ===
=== print_user ===
=== update_categories_search_button ===
=== update_mymoodle_icon ===

==See also==

* [[Developement:How_Moodle_outputs_HTML]]
* [[Development:Migrating your code to the 2.0 rendering_API]]

{{CategoryDeveloper}}

Development talk:Blog 2.0

2009-09-24T08:44:25Z

Nicolasconnault: /* Some questions */

=== Some questions ===

* about the "who can view"/"externl blogs"/"associations" things... is going to be some capability like:
** viewblogentries
** viewdraftblogentries
** fetchexternalblogs
** searchblogentries
** associateblogentries
:Yes to the above [[User:Nicolas Connault|Nicolas Connault]] 08:56, 22 September 2009 (UTC)
* Also, are "fetched" and manual blog entries differentiated in any way?
:In the database, entries that have been copied from an external blog will have a value in the post.uniquehash field. Also, you will be able to automatically tag an external blog's entries with one or more tags [[User:Nicolas Connault|Nicolas Connault]] 08:56, 22 September 2009 (UTC)
* Finally, both tags and associations are going to be published in the RSS Feeds?
:I don't see why not, maybe that could be optional [[User:Nicolas Connault|Nicolas Connault]] 08:56, 22 September 2009 (UTC)
* Is it going to be possible to get RSS Feeds by tag or association?
:Yes [[User:Nicolas Connault|Nicolas Connault]] 08:56, 22 September 2009 (UTC)
* [http://en.wikipedia.org/wiki/Atom_(standard) ATOM] (import from external blog feeds / publish local feeds)
:Not sure, can you explain? [[User:Nicolas Connault|Nicolas Connault]] 08:56, 22 September 2009 (UTC)
* When blog entries are displayed for say, course XX, will also "child" entries be displayed (activity-associated).
:Yes, whenever an entry is associated with an activity, it is also automatically associated with the course. [[User:Nicolas Connault|Nicolas Connault]] 08:56, 22 September 2009 (UTC)
::"automatically associated" stands for: association record created automatically or rely in accesslib (nested contexts) abilities?
* If association is disabled in one site (or user if the capability exists), which will be the behaviour of the blocks?
:Instead of searching for entries associated with the course, it will just show all blog entries (for the site). The links in the blog_menu will be simplified accordingly. [[User:Nicolas Connault|Nicolas Connault]] 08:56, 22 September 2009 (UTC)
--[[User:Eloy Lafuente (stronk7)|Eloy Lafuente (stronk7)]] 08:45, 22 September 2009 (UTC)

----

===More questions===
'''Who can view blog entries''' - the description is not correct, there were more access levels, we can not just remove them - please explain the differences and propose upgrade routes. The descriptions have to contain all relevant capabilities and their use.

'''Associations''' - just the context id does not seem to be granular enough, we use are+itemid elsewhere because it allows you to specify the exact forum discussion or post for example. Another problem is should we allow association with context you are not enrolled in? Please include all relevant capabilities too. ''blogid'' in blog_assoc table links which column and table? Should it be called postid?

'''External blogs''' I would not call it import, maybe better "sync with external blog". I suppose that it might be good to have a tag name in the blog description. There could be also separate option for synchronisation of external tags. Hmm, we could also fetch posts with some tags only. We do not need tags in order to distinguish external feeds - they have the hash there. The problem I see is if you accidentally add some ext blog and then you want to delete it - we do not know from which feed it was added (I suppose one user may have multiple ext blogs linked). Again include all caps.

'''Atom''' what is it ''atom write'' support?

'''Attachments''' we need embedded images too.

'''Problems'''
* different access control compared to 1.9
* RSS feeds when posts are not accessible without login need some form of protection

[[User:Petr Škoda (škoďák)|Petr Škoda (škoďák)]] 21:13, 22 September 2009 (UTC)

----

Development talk:Blog 2.0

2009-09-22T08:56:05Z

Nicolasconnault: /* Some questions */

Development:Blog 2.0

2009-09-22T08:46:15Z

Nicolasconnault: /* Description of improvements */

{{Work in progress}}{{Moodle 2.0}}

* '''PROJECT STATE: Coding'''
* '''MAIN TRACKER ISSUE''': MDL-19676 Blog 2.0 improvements
* '''DISCUSSION AND COMMENTS''': http://moodle.org/mod/forum/discuss.php?d=133348

== Description of improvements ==
=== Who can view blog entries? ===
Blog entries are either in draft mode (only the author can view it), or in public mode. In public mode, everyone on the entire site can view the blog entry.

At one stage in 2.0 development there was an attempt to restrict who can view certain blog entries, based on course enrolment and capabilities. However, after extensive discussion and feasibility testing it became clear that this would lead to serious performance and usability issues, and would turn the blog into something more akin to a forum. It was thus decided to make all blogs public. (See MDL-19676)

An admin setting can allow for blog entries to be accessible by non-logged-in users, for the purpose of publishing and RSS feed aggregation.

=== Associations ===
A blog entry can optionally be associated with a course. This makes it possible for a user to blog "about" that course. All blog entries associated in that way can be viewed on a page like blog/index.php?courseid=3. This type of filtering of blog entries does not take into account course enrolments.

Additionally, blog entries can be associated with activity modules, in which case the blog entry is automatically associated with the module's course.

This requires the creation of a new table, in which the associations are recorded.
Tracker issue: MDL-14408

=== Improved navigation ===
Before 2.0, the navigation for any listing of blog entries was either "Site > User > Blogs" (for a user's blog entries) or "Site > Blogs" for the whole site's blog entries, optionally filtered by tag. With the new association features, we need a better way to display what type of blog listing we are looking at, based on the parameters passed to blog/index.php. The navigation should also reflect additional filters such as tag and search.

=== External blogs ===
A user can import blog entries into Moodle from external blogs. The external blog's entries are copied into Moodle when the external blog URL is entered, and a cron task periodically checks these external blogs to copy new entries not yet entered in Moodle. The period of time between checks can be adjusted as an admin setting.

These external blogs are a user preference, and two types of tags can be added to each of them: "External tags" and "Moodle tags":
*External tags are used to filter the external blog entries that get copied into Moodle. They must match the tags used by that external blog.
*Moodle tags are automatically added to each blog entry copied into Moodle from an external blog that uses such tags. This makes it easier to distinguish which of a user's blog entries come from an external blog.

This requires the creation of a new DB table.
Tracker issue: MDL-19683

=== Search blog entries ===
It is now possible to search blog entries using a search box. The results maintain the current context, so that if you are viewing a list of blog entries for a particular user, entering a term in the search box will return only the blog entries for that user that match the search term. The search term also appears in the navigation breadcrumbs.

Tracker issue: MDL-19686

=== Contextual blog menu ===
Previously, the "blog menu" block was the same on every page on which it appeared. In 2.0 it changes depending on which page you are. For example, if you are on course/view.php, it will include a link to blog entries associated with that course. Also, the link for adding a new entry will include the courseid, making the course association automatically pre-selected in the blog entry edit form.

Tracker issue: MDL-19687

=== File attachments ===
The [[Development:File_API|new file manager]] must be implemented to allow for multiple file attachments per blog entry.

Tracker issue: MDL-19744

=== Comments ===
The new [[Development:Comments_2.0|Comments API]] makes it possible for anyone having the correct capability to comment on blog entries.

Tracker issue: MDL-8776

=== New "Recent blog entries" block ===
This block can be configured to display the last N blog entries, filtered by context. For example, if you are viewing an assignment activity, this block would display the last N blog entries that are associated with that assignment.

Tracker issue: MDL-19688

== Potential problems and limitations ==

== DB Structure ==
2 new tables need to be added: blog_external and blog_association

=== blog_external ===

{| class="nicetable"
|-
! Field
! Type
! Default
! Info
|-
| id
| int(10)
| auto-incrementing
| The unique ID for this external blog.
|-
| userid
| int(10)
|
| The owner of the external blog
|-
| name
| char(255)
|
| A descriptive name for the external blog. Automatically fetched during initial import, can be overridden.
|-
| description
| text(small)
|
| A long description of the external blog. Automatically fetched during initial import, can be overridden.
|-
| url
| text(small)
|
| The URL to the external blog (e.g. http://moodle.org/rss.xml)
|-
| timemodified
| int(10)
|
|
|-
| timefetched
| int(10)
|
| The last time the entries from this external blog were fetched by Moodle.
|}

=== blog_association ===

{| class="nicetable"
|-
! Field
! Type
! Default
! Info
|-
| id
| int(10)
| auto-incrementing
| The unique ID for this blog entry<->contextid association.
|-
| contextid
| int(10)
|
| The context id defined in context table - identifies the instance of the course or plugin associated with the blog entry.
|-
| blogid
| int(10)
|
| The id of the blog entry (from the post table) being associated with a course or module instance
|}

== Upgrade process ==
The only task required by the upgrade process is to install the new DB tables.

== See also ==
*[[Development:Blogs|Early wishlist]]
*[[Student_projects/Blog_improvements|2008 GSoC project addressing some of these improvements]]

Development:Blog 2.0

2009-09-22T08:08:51Z

Nicolasconnault:

{{Work in progress}}{{Moodle 2.0}}

* '''PROJECT STATE: Coding'''
* '''MAIN TRACKER ISSUE''': MDL-19676 Blog 2.0 improvements
* '''DISCUSSION AND COMMENTS''': http://moodle.org/mod/forum/discuss.php?d=133348

== Description of improvements ==
=== Who can view blog entries? ===
Blog entries are either in draft mode (only the author can view it), or in public mode. In public mode, everyone on the entire site can view the blog entry.

At one stage in 2.0 development there was an attempt to restrict who can view certain blog entries, based on course enrolment and capabilities. However, after extensive discussion and feasibility testing it became clear that this would lead to serious performance and usability issues, and would turn the blog into something more akin to a forum. It was thus decided to make all blogs public. (See [http://tracker.moodle.org/browse/MDL-19676 this tracker issue])

An admin setting can allow for blog entries to be accessible by non-logged-in users, for the purpose of publishing and RSS feed aggregation.

=== Associations ===
A blog entry can optionally be associated with a course. This makes it possible for a user to blog "about" that course. All blog entries associated in that way can be viewed on a page like blog/index.php?courseid=3. This type of filtering of blog entries does not take into account course enrolments.

Additionally, blog entries can be associated with activity modules, in which case the blog entry is automatically associated with the module's course.

This requires the creation of a new table, in which the associations are recorded.
Tracker issue: [http://tracker.moodle.org/browse/MDL-14408]

=== Improved navigation ===
Before 2.0, the navigation for any listing of blog entries was either "Site > User > Blogs" (for a user's blog entries) or "Site > Blogs" for the whole site's blog entries, optionally filtered by tag. With the new association features, we need a better way to display what type of blog listing we are looking at, based on the parameters passed to blog/index.php. The navigation should also reflect additional filters such as tag and search.

=== External blogs ===
A user can import blog entries into Moodle from external blogs. The external blog's entries are copied into Moodle when the external blog URL is entered, and a cron task periodically checks these external blogs to copy new entries not yet entered in Moodle. The period of time between checks can be adjusted as an admin setting.

These external blogs are a user preference, and two types of tags can be added to each of them: "External tags" and "Moodle tags":
*External tags are used to filter the external blog entries that get copied into Moodle. They must match the tags used by that external blog.
*Moodle tags are automatically added to each blog entry copied into Moodle from an external blog that uses such tags. This makes it easier to distinguish which of a user's blog entries come from an external blog.

This requires the creation of a new DB table.
Tracker issue: [http://tracker.moodle.org/browse/MDL-19683]

=== Search blog entries ===
It is now possible to search blog entries using a search box. The results maintain the current context, so that if you are viewing a list of blog entries for a particular user, entering a term in the search box will return only the blog entries for that user that match the search term. The search term also appears in the navigation breadcrumbs.

Tracker issue: [http://tracker.moodle.org/browse/MDL-19686]

=== Contextual blog menu ===
Previously, the "blog menu" block was the same on every page on which it appeared. In 2.0 it changes depending on which page you are. For example, if you are on course/view.php, it will include a link to blog entries associated with that course. Also, the link for adding a new entry will include the courseid, making the course association automatically pre-selected in the blog entry edit form.

Tracker issue: [http://tracker.moodle.org/browse/MDL-19687]

=== File attachments ===
The [[Development:File_API|new file manager]] must be implemented to allow for multiple file attachments per blog entry.

Tracker issue: [http://tracker.moodle.org/browse/MDL-19744]

=== Comments ===
The new [[Development:Comments_2.0|Comments API]] makes it possible for anyone having the correct capability to comment on blog entries.

Tracker issue: [http://tracker.moodle.org/browse/MDL-8776]

=== New "Recent blog entries" block ===
This block can be configured to display the last N blog entries, filtered by context. For example, if you are viewing an assignment activity, this block would display the last N blog entries that are associated with that assignment.

Tracker issue: [http://tracker.moodle.org/browse/MDL-19688]

== Potential problems and limitations ==

== DB Structure ==
2 new tables need to be added: blog_external and blog_association

=== blog_external ===

{| class="nicetable"
|-
! Field
! Type
! Default
! Info
|-
| id
| int(10)
| auto-incrementing
| The unique ID for this external blog.
|-
| userid
| int(10)
|
| The owner of the external blog
|-
| name
| char(255)
|
| A descriptive name for the external blog. Automatically fetched during initial import, can be overridden.
|-
| description
| text(small)
|
| A long description of the external blog. Automatically fetched during initial import, can be overridden.
|-
| url
| text(small)
|
| The URL to the external blog (e.g. http://moodle.org/rss.xml)
|-
| timemodified
| int(10)
|
|
|-
| timefetched
| int(10)
|
| The last time the entries from this external blog were fetched by Moodle.
|}

=== blog_association ===

{| class="nicetable"
|-
! Field
! Type
! Default
! Info
|-
| id
| int(10)
| auto-incrementing
| The unique ID for this blog entry<->contextid association.
|-
| contextid
| int(10)
|
| The context id defined in context table - identifies the instance of the course or plugin associated with the blog entry.
|-
| blogid
| int(10)
|
| The id of the blog entry (from the post table) being associated with a course or module instance
|}

== Upgrade process ==
The only task required by the upgrade process is to install the new DB tables.

== See also ==
*[[Development:Blogs|Early wishlist]]
*[[Student_projects/Blog_improvements|2008 GSoC project addressing some of these improvements]]

Development:Blog 2.0

2009-09-22T08:01:59Z

Nicolasconnault: /* Upgrade process */

{{Work in progress}}{{Moodle 2.0}}

* '''PROJECT STATE: Coding'''
* '''MAIN TRACKER ISSUE''': MDL-19676 Blog 2.0 improvements
* '''DISCUSSION AND COMMENTS''': Link to forum discussion will appear here

== Description of improvements ==
=== Who can view blog entries? ===
Blog entries are either in draft mode (only the author can view it), or in public mode. In public mode, everyone on the entire site can view the blog entry.

At one stage in 2.0 development there was an attempt to restrict who can view certain blog entries, based on course enrolment and capabilities. However, after extensive discussion and feasibility testing it became clear that this would lead to serious performance and usability issues, and would turn the blog into something more akin to a forum. It was thus decided to make all blogs public. (See [http://tracker.moodle.org/browse/MDL-19676 this tracker issue])

An admin setting can allow for blog entries to be accessible by non-logged-in users, for the purpose of publishing and RSS feed aggregation.

=== Associations ===
A blog entry can optionally be associated with a course. This makes it possible for a user to blog "about" that course. All blog entries associated in that way can be viewed on a page like blog/index.php?courseid=3. This type of filtering of blog entries does not take into account course enrolments.

Additionally, blog entries can be associated with activity modules, in which case the blog entry is automatically associated with the module's course.

This requires the creation of a new table, in which the associations are recorded.
Tracker issue: [http://tracker.moodle.org/browse/MDL-14408]

=== Improved navigation ===
Before 2.0, the navigation for any listing of blog entries was either "Site > User > Blogs" (for a user's blog entries) or "Site > Blogs" for the whole site's blog entries, optionally filtered by tag. With the new association features, we need a better way to display what type of blog listing we are looking at, based on the parameters passed to blog/index.php. The navigation should also reflect additional filters such as tag and search.

=== External blogs ===
A user can import blog entries into Moodle from external blogs. The external blog's entries are copied into Moodle when the external blog URL is entered, and a cron task periodically checks these external blogs to copy new entries not yet entered in Moodle. The period of time between checks can be adjusted as an admin setting.

These external blogs are a user preference, and two types of tags can be added to each of them: "External tags" and "Moodle tags":
*External tags are used to filter the external blog entries that get copied into Moodle. They must match the tags used by that external blog.
*Moodle tags are automatically added to each blog entry copied into Moodle from an external blog that uses such tags. This makes it easier to distinguish which of a user's blog entries come from an external blog.

This requires the creation of a new DB table.
Tracker issue: [http://tracker.moodle.org/browse/MDL-19683]

=== Search blog entries ===
It is now possible to search blog entries using a search box. The results maintain the current context, so that if you are viewing a list of blog entries for a particular user, entering a term in the search box will return only the blog entries for that user that match the search term. The search term also appears in the navigation breadcrumbs.

Tracker issue: [http://tracker.moodle.org/browse/MDL-19686]

=== Contextual blog menu ===
Previously, the "blog menu" block was the same on every page on which it appeared. In 2.0 it changes depending on which page you are. For example, if you are on course/view.php, it will include a link to blog entries associated with that course. Also, the link for adding a new entry will include the courseid, making the course association automatically pre-selected in the blog entry edit form.

Tracker issue: [http://tracker.moodle.org/browse/MDL-19687]

=== File attachments ===
The [[Development:File_API|new file manager]] must be implemented to allow for multiple file attachments per blog entry.

Tracker issue: [http://tracker.moodle.org/browse/MDL-19744]

=== Comments ===
The new [[Development:Comments_2.0|Comments API]] makes it possible for anyone having the correct capability to comment on blog entries.

Tracker issue: [http://tracker.moodle.org/browse/MDL-8776]

=== New "Recent blog entries" block ===
This block can be configured to display the last N blog entries, filtered by context. For example, if you are viewing an assignment activity, this block would display the last N blog entries that are associated with that assignment.

Tracker issue: [http://tracker.moodle.org/browse/MDL-19688]

== Potential problems and limitations ==

== DB Structure ==
2 new tables need to be added: blog_external and blog_association

=== blog_external ===

{| class="nicetable"
|-
! Field
! Type
! Default
! Info
|-
| id
| int(10)
| auto-incrementing
| The unique ID for this external blog.
|-
| userid
| int(10)
|
| The owner of the external blog
|-
| name
| char(255)
|
| A descriptive name for the external blog. Automatically fetched during initial import, can be overridden.
|-
| description
| text(small)
|
| A long description of the external blog. Automatically fetched during initial import, can be overridden.
|-
| url
| text(small)
|
| The URL to the external blog (e.g. http://moodle.org/rss.xml)
|-
| timemodified
| int(10)
|
|
|-
| timefetched
| int(10)
|
| The last time the entries from this external blog were fetched by Moodle.
|}

=== blog_association ===

{| class="nicetable"
|-
! Field
! Type
! Default
! Info
|-
| id
| int(10)
| auto-incrementing
| The unique ID for this blog entry<->contextid association.
|-
| contextid
| int(10)
|
| The context id defined in context table - identifies the instance of the course or plugin associated with the blog entry.
|-
| blogid
| int(10)
|
| The id of the blog entry (from the post table) being associated with a course or module instance
|}

== Upgrade process ==
The only task required by the upgrade process is to install the new DB tables.

== See also ==
*[[Development:Blogs|Early wishlist]]
*[[Student_projects/Blog_improvements|2008 GSoC project addressing some of these improvements]]

Development:Blog 2.0

2009-09-22T08:00:14Z

Nicolasconnault: /* DB Structure */

{{Work in progress}}{{Moodle 2.0}}

* '''PROJECT STATE: Coding'''
* '''MAIN TRACKER ISSUE''': MDL-19676 Blog 2.0 improvements
* '''DISCUSSION AND COMMENTS''': Link to forum discussion will appear here

== Description of improvements ==
=== Who can view blog entries? ===
Blog entries are either in draft mode (only the author can view it), or in public mode. In public mode, everyone on the entire site can view the blog entry.

At one stage in 2.0 development there was an attempt to restrict who can view certain blog entries, based on course enrolment and capabilities. However, after extensive discussion and feasibility testing it became clear that this would lead to serious performance and usability issues, and would turn the blog into something more akin to a forum. It was thus decided to make all blogs public. (See [http://tracker.moodle.org/browse/MDL-19676 this tracker issue])

An admin setting can allow for blog entries to be accessible by non-logged-in users, for the purpose of publishing and RSS feed aggregation.

=== Associations ===
A blog entry can optionally be associated with a course. This makes it possible for a user to blog "about" that course. All blog entries associated in that way can be viewed on a page like blog/index.php?courseid=3. This type of filtering of blog entries does not take into account course enrolments.

Additionally, blog entries can be associated with activity modules, in which case the blog entry is automatically associated with the module's course.

This requires the creation of a new table, in which the associations are recorded.
Tracker issue: [http://tracker.moodle.org/browse/MDL-14408]

=== Improved navigation ===
Before 2.0, the navigation for any listing of blog entries was either "Site > User > Blogs" (for a user's blog entries) or "Site > Blogs" for the whole site's blog entries, optionally filtered by tag. With the new association features, we need a better way to display what type of blog listing we are looking at, based on the parameters passed to blog/index.php. The navigation should also reflect additional filters such as tag and search.

=== External blogs ===
A user can import blog entries into Moodle from external blogs. The external blog's entries are copied into Moodle when the external blog URL is entered, and a cron task periodically checks these external blogs to copy new entries not yet entered in Moodle. The period of time between checks can be adjusted as an admin setting.

These external blogs are a user preference, and two types of tags can be added to each of them: "External tags" and "Moodle tags":
*External tags are used to filter the external blog entries that get copied into Moodle. They must match the tags used by that external blog.
*Moodle tags are automatically added to each blog entry copied into Moodle from an external blog that uses such tags. This makes it easier to distinguish which of a user's blog entries come from an external blog.

This requires the creation of a new DB table.
Tracker issue: [http://tracker.moodle.org/browse/MDL-19683]

=== Search blog entries ===
It is now possible to search blog entries using a search box. The results maintain the current context, so that if you are viewing a list of blog entries for a particular user, entering a term in the search box will return only the blog entries for that user that match the search term. The search term also appears in the navigation breadcrumbs.

Tracker issue: [http://tracker.moodle.org/browse/MDL-19686]

=== Contextual blog menu ===
Previously, the "blog menu" block was the same on every page on which it appeared. In 2.0 it changes depending on which page you are. For example, if you are on course/view.php, it will include a link to blog entries associated with that course. Also, the link for adding a new entry will include the courseid, making the course association automatically pre-selected in the blog entry edit form.

Tracker issue: [http://tracker.moodle.org/browse/MDL-19687]

=== File attachments ===
The [[Development:File_API|new file manager]] must be implemented to allow for multiple file attachments per blog entry.

Tracker issue: [http://tracker.moodle.org/browse/MDL-19744]

=== Comments ===
The new [[Development:Comments_2.0|Comments API]] makes it possible for anyone having the correct capability to comment on blog entries.

Tracker issue: [http://tracker.moodle.org/browse/MDL-8776]

=== New "Recent blog entries" block ===
This block can be configured to display the last N blog entries, filtered by context. For example, if you are viewing an assignment activity, this block would display the last N blog entries that are associated with that assignment.

Tracker issue: [http://tracker.moodle.org/browse/MDL-19688]

== Potential problems and limitations ==

== DB Structure ==
2 new tables need to be added: blog_external and blog_association

=== blog_external ===

{| class="nicetable"
|-
! Field
! Type
! Default
! Info
|-
| id
| int(10)
| auto-incrementing
| The unique ID for this external blog.
|-
| userid
| int(10)
|
| The owner of the external blog
|-
| name
| char(255)
|
| A descriptive name for the external blog. Automatically fetched during initial import, can be overridden.
|-
| description
| text(small)
|
| A long description of the external blog. Automatically fetched during initial import, can be overridden.
|-
| url
| text(small)
|
| The URL to the external blog (e.g. http://moodle.org/rss.xml)
|-
| timemodified
| int(10)
|
|
|-
| timefetched
| int(10)
|
| The last time the entries from this external blog were fetched by Moodle.
|}

=== blog_association ===

{| class="nicetable"
|-
! Field
! Type
! Default
! Info
|-
| id
| int(10)
| auto-incrementing
| The unique ID for this blog entry<->contextid association.
|-
| contextid
| int(10)
|
| The context id defined in context table - identifies the instance of the course or plugin associated with the blog entry.
|-
| blogid
| int(10)
|
| The id of the blog entry (from the post table) being associated with a course or module instance
|}

== Upgrade process ==

== See also ==
*[[Development:Blogs|Early wishlist]]
*[[Student_projects/Blog_improvements|2008 GSoC project addressing some of these improvements]]

Development:Blog 2.0

2009-09-21T06:52:31Z

Nicolasconnault: /* Who can view blog entries? */

{{Work in progress}}{{Moodle 2.0}}

* '''PROJECT STATE: Coding'''
* '''MAIN TRACKER ISSUE''': MDL-19676 Blog 2.0 improvements
* '''DISCUSSION AND COMMENTS''': Link to forum discussion will appear here

== Description of improvements ==
=== Who can view blog entries? ===
Blog entries are either in draft mode (only the author can view it), or in public mode. In public mode, everyone on the entire site can view the blog entry.

At one stage in 2.0 development there was an attempt to restrict who can view certain blog entries, based on course enrolment and capabilities. However, after extensive discussion and feasibility testing it became clear that this would lead to serious performance and usability issues, and would turn the blog into something more akin to a forum. It was thus decided to make all blogs public. (See [http://tracker.moodle.org/browse/MDL-19676 this tracker issue])

An admin setting can allow for blog entries to be accessible by non-logged-in users, for the purpose of publishing and RSS feed aggregation.

=== Associations ===
A blog entry can optionally be associated with a course. This makes it possible for a user to blog "about" that course. All blog entries associated in that way can be viewed on a page like blog/index.php?courseid=3. This type of filtering of blog entries does not take into account course enrolments.

Additionally, blog entries can be associated with activity modules, in which case the blog entry is automatically associated with the module's course.

This requires the creation of a new table, in which the associations are recorded.
Tracker issue: [http://tracker.moodle.org/browse/MDL-14408]

=== Improved navigation ===
Before 2.0, the navigation for any listing of blog entries was either "Site > User > Blogs" (for a user's blog entries) or "Site > Blogs" for the whole site's blog entries, optionally filtered by tag. With the new association features, we need a better way to display what type of blog listing we are looking at, based on the parameters passed to blog/index.php. The navigation should also reflect additional filters such as tag and search.

=== External blogs ===
A user can import blog entries into Moodle from external blogs. The external blog's entries are copied into Moodle when the external blog URL is entered, and a cron task periodically checks these external blogs to copy new entries not yet entered in Moodle. The period of time between checks can be adjusted as an admin setting.

These external blogs are a user preference, and two types of tags can be added to each of them: "External tags" and "Moodle tags":
*External tags are used to filter the external blog entries that get copied into Moodle. They must match the tags used by that external blog.
*Moodle tags are automatically added to each blog entry copied into Moodle from an external blog that uses such tags. This makes it easier to distinguish which of a user's blog entries come from an external blog.

This requires the creation of a new DB table.
Tracker issue: [http://tracker.moodle.org/browse/MDL-19683]

=== Search blog entries ===
It is now possible to search blog entries using a search box. The results maintain the current context, so that if you are viewing a list of blog entries for a particular user, entering a term in the search box will return only the blog entries for that user that match the search term. The search term also appears in the navigation breadcrumbs.

Tracker issue: [http://tracker.moodle.org/browse/MDL-19686]

=== Contextual blog menu ===
Previously, the "blog menu" block was the same on every page on which it appeared. In 2.0 it changes depending on which page you are. For example, if you are on course/view.php, it will include a link to blog entries associated with that course. Also, the link for adding a new entry will include the courseid, making the course association automatically pre-selected in the blog entry edit form.

Tracker issue: [http://tracker.moodle.org/browse/MDL-19687]

=== File attachments ===
The [[Development:File_API|new file manager]] must be implemented to allow for multiple file attachments per blog entry.

Tracker issue: [http://tracker.moodle.org/browse/MDL-19744]

=== Comments ===
The new [[Development:Comments_2.0|Comments API]] makes it possible for anyone having the correct capability to comment on blog entries.

Tracker issue: [http://tracker.moodle.org/browse/MDL-8776]

=== New "Recent blog entries" block ===
This block can be configured to display the last N blog entries, filtered by context. For example, if you are viewing an assignment activity, this block would display the last N blog entries that are associated with that assignment.

Tracker issue: [http://tracker.moodle.org/browse/MDL-19688]

== Potential problems and limitations ==

== DB Structure ==
2 new tables need to be added: blog_external and blog_associations

== Upgrade process ==

== See also ==
*[[Development:Blogs|Early wishlist]]
*[[Student_projects/Blog_improvements|2008 GSoC project addressing some of these improvements]]

Development:Blog 2.0

2009-09-21T06:52:12Z

Nicolasconnault: /* Who can view blog entries? */

{{Work in progress}}{{Moodle 2.0}}

* '''PROJECT STATE: Coding'''
* '''MAIN TRACKER ISSUE''': MDL-19676 Blog 2.0 improvements
* '''DISCUSSION AND COMMENTS''': Link to forum discussion will appear here

== Description of improvements ==
=== Who can view blog entries? ===
Blog entries are either in draft mode (only the author can view it), or in public mode. In public mode, everyone on the entire site can view the blog entry.

At one stage in 2.0 development there was an attempt to restrict who can view certain blog entries, based on course enrolment and capabilities. However, after extensive discussion and feasibility testing it became clear that this would lead to serious performance and usability issues, and would turn the blog into something more akin to a forum. It was thus decided to make all blogs public. (See [http://tracker.moodle.org/browse/MDL-19676 |this tracker issue])

An admin setting can allow for blog entries to be accessible by non-logged-in users, for the purpose of publishing and RSS feed aggregation.

=== Associations ===
A blog entry can optionally be associated with a course. This makes it possible for a user to blog "about" that course. All blog entries associated in that way can be viewed on a page like blog/index.php?courseid=3. This type of filtering of blog entries does not take into account course enrolments.

Additionally, blog entries can be associated with activity modules, in which case the blog entry is automatically associated with the module's course.

This requires the creation of a new table, in which the associations are recorded.
Tracker issue: [http://tracker.moodle.org/browse/MDL-14408]

=== Improved navigation ===
Before 2.0, the navigation for any listing of blog entries was either "Site > User > Blogs" (for a user's blog entries) or "Site > Blogs" for the whole site's blog entries, optionally filtered by tag. With the new association features, we need a better way to display what type of blog listing we are looking at, based on the parameters passed to blog/index.php. The navigation should also reflect additional filters such as tag and search.

=== External blogs ===
A user can import blog entries into Moodle from external blogs. The external blog's entries are copied into Moodle when the external blog URL is entered, and a cron task periodically checks these external blogs to copy new entries not yet entered in Moodle. The period of time between checks can be adjusted as an admin setting.

These external blogs are a user preference, and two types of tags can be added to each of them: "External tags" and "Moodle tags":
*External tags are used to filter the external blog entries that get copied into Moodle. They must match the tags used by that external blog.
*Moodle tags are automatically added to each blog entry copied into Moodle from an external blog that uses such tags. This makes it easier to distinguish which of a user's blog entries come from an external blog.

This requires the creation of a new DB table.
Tracker issue: [http://tracker.moodle.org/browse/MDL-19683]

=== Search blog entries ===
It is now possible to search blog entries using a search box. The results maintain the current context, so that if you are viewing a list of blog entries for a particular user, entering a term in the search box will return only the blog entries for that user that match the search term. The search term also appears in the navigation breadcrumbs.

Tracker issue: [http://tracker.moodle.org/browse/MDL-19686]

=== Contextual blog menu ===
Previously, the "blog menu" block was the same on every page on which it appeared. In 2.0 it changes depending on which page you are. For example, if you are on course/view.php, it will include a link to blog entries associated with that course. Also, the link for adding a new entry will include the courseid, making the course association automatically pre-selected in the blog entry edit form.

Tracker issue: [http://tracker.moodle.org/browse/MDL-19687]

=== File attachments ===
The [[Development:File_API|new file manager]] must be implemented to allow for multiple file attachments per blog entry.

Tracker issue: [http://tracker.moodle.org/browse/MDL-19744]

=== Comments ===
The new [[Development:Comments_2.0|Comments API]] makes it possible for anyone having the correct capability to comment on blog entries.

Tracker issue: [http://tracker.moodle.org/browse/MDL-8776]

=== New "Recent blog entries" block ===
This block can be configured to display the last N blog entries, filtered by context. For example, if you are viewing an assignment activity, this block would display the last N blog entries that are associated with that assignment.

Tracker issue: [http://tracker.moodle.org/browse/MDL-19688]

== Potential problems and limitations ==

== DB Structure ==
2 new tables need to be added: blog_external and blog_associations

== Upgrade process ==

== See also ==
*[[Development:Blogs|Early wishlist]]
*[[Student_projects/Blog_improvements|2008 GSoC project addressing some of these improvements]]

Development:Blog 2.0

2009-09-21T06:48:14Z

Nicolasconnault: /* DB Structure */

{{Work in progress}}{{Moodle 2.0}}

* '''PROJECT STATE: Coding'''
* '''MAIN TRACKER ISSUE''': MDL-19676 Blog 2.0 improvements
* '''DISCUSSION AND COMMENTS''': Link to forum discussion will appear here

== Description of improvements ==
=== Who can view blog entries? ===
Blog entries are either in draft mode (only the author can view it), or in public mode. In public mode, everyone on the entire site can view the blog entry.

At one stage in 2.0 development there was an attempt to restrict who can view certain blog entries, based on course enrolment and capabilities. However, after extensive discussion and feasibility testing it became clear that this would lead to serious performance and usability issues, and would turn the blog into something more akin to a forum. It was thus decided to make all blogs public. (See [http://tracker.moodle.org/browse/MDL-19676|this tracker issue])

An admin setting can allow for blog entries to be accessible by non-logged-in users, for the purpose of publishing and RSS feed aggregation.

=== Associations ===
A blog entry can optionally be associated with a course. This makes it possible for a user to blog "about" that course. All blog entries associated in that way can be viewed on a page like blog/index.php?courseid=3. This type of filtering of blog entries does not take into account course enrolments.

Additionally, blog entries can be associated with activity modules, in which case the blog entry is automatically associated with the module's course.

This requires the creation of a new table, in which the associations are recorded.
Tracker issue: [http://tracker.moodle.org/browse/MDL-14408]

=== Improved navigation ===
Before 2.0, the navigation for any listing of blog entries was either "Site > User > Blogs" (for a user's blog entries) or "Site > Blogs" for the whole site's blog entries, optionally filtered by tag. With the new association features, we need a better way to display what type of blog listing we are looking at, based on the parameters passed to blog/index.php. The navigation should also reflect additional filters such as tag and search.

=== External blogs ===
A user can import blog entries into Moodle from external blogs. The external blog's entries are copied into Moodle when the external blog URL is entered, and a cron task periodically checks these external blogs to copy new entries not yet entered in Moodle. The period of time between checks can be adjusted as an admin setting.

These external blogs are a user preference, and two types of tags can be added to each of them: "External tags" and "Moodle tags":
*External tags are used to filter the external blog entries that get copied into Moodle. They must match the tags used by that external blog.
*Moodle tags are automatically added to each blog entry copied into Moodle from an external blog that uses such tags. This makes it easier to distinguish which of a user's blog entries come from an external blog.

This requires the creation of a new DB table.
Tracker issue: [http://tracker.moodle.org/browse/MDL-19683]

=== Search blog entries ===
It is now possible to search blog entries using a search box. The results maintain the current context, so that if you are viewing a list of blog entries for a particular user, entering a term in the search box will return only the blog entries for that user that match the search term. The search term also appears in the navigation breadcrumbs.

Tracker issue: [http://tracker.moodle.org/browse/MDL-19686]

=== Contextual blog menu ===
Previously, the "blog menu" block was the same on every page on which it appeared. In 2.0 it changes depending on which page you are. For example, if you are on course/view.php, it will include a link to blog entries associated with that course. Also, the link for adding a new entry will include the courseid, making the course association automatically pre-selected in the blog entry edit form.

Tracker issue: [http://tracker.moodle.org/browse/MDL-19687]

=== File attachments ===
The [[Development:File_API|new file manager]] must be implemented to allow for multiple file attachments per blog entry.

Tracker issue: [http://tracker.moodle.org/browse/MDL-19744]

=== Comments ===
The new [[Development:Comments_2.0|Comments API]] makes it possible for anyone having the correct capability to comment on blog entries.

Tracker issue: [http://tracker.moodle.org/browse/MDL-8776]

=== New "Recent blog entries" block ===
This block can be configured to display the last N blog entries, filtered by context. For example, if you are viewing an assignment activity, this block would display the last N blog entries that are associated with that assignment.

Tracker issue: [http://tracker.moodle.org/browse/MDL-19688]

== Potential problems and limitations ==

== DB Structure ==
2 new tables need to be added: blog_external and blog_associations

== Upgrade process ==

== See also ==
*[[Development:Blogs|Early wishlist]]
*[[Student_projects/Blog_improvements|2008 GSoC project addressing some of these improvements]]

Development:Blog 2.0

2009-09-21T06:29:09Z

Nicolasconnault:

{{Work in progress}}{{Moodle 2.0}}

* '''PROJECT STATE: Coding'''
* '''MAIN TRACKER ISSUE''': MDL-19676 Blog 2.0 improvements
* '''DISCUSSION AND COMMENTS''': Link to forum discussion will appear here

== Description of improvements ==
=== Who can view blog entries? ===
Blog entries are either in draft mode (only the author can view it), or in public mode. In public mode, everyone on the entire site can view the blog entry.

At one stage in 2.0 development there was an attempt to restrict who can view certain blog entries, based on course enrolment and capabilities. However, after extensive discussion and feasibility testing it became clear that this would lead to serious performance and usability issues, and would turn the blog into something more akin to a forum. It was thus decided to make all blogs public. (See [http://tracker.moodle.org/browse/MDL-19676|this tracker issue])

An admin setting can allow for blog entries to be accessible by non-logged-in users, for the purpose of publishing and RSS feed aggregation.

=== Associations ===
A blog entry can optionally be associated with a course. This makes it possible for a user to blog "about" that course. All blog entries associated in that way can be viewed on a page like blog/index.php?courseid=3. This type of filtering of blog entries does not take into account course enrolments.

Additionally, blog entries can be associated with activity modules, in which case the blog entry is automatically associated with the module's course.

This requires the creation of a new table, in which the associations are recorded.
Tracker issue: [http://tracker.moodle.org/browse/MDL-14408]

=== Improved navigation ===
Before 2.0, the navigation for any listing of blog entries was either "Site > User > Blogs" (for a user's blog entries) or "Site > Blogs" for the whole site's blog entries, optionally filtered by tag. With the new association features, we need a better way to display what type of blog listing we are looking at, based on the parameters passed to blog/index.php. The navigation should also reflect additional filters such as tag and search.

=== External blogs ===
A user can import blog entries into Moodle from external blogs. The external blog's entries are copied into Moodle when the external blog URL is entered, and a cron task periodically checks these external blogs to copy new entries not yet entered in Moodle. The period of time between checks can be adjusted as an admin setting.

These external blogs are a user preference, and two types of tags can be added to each of them: "External tags" and "Moodle tags":
*External tags are used to filter the external blog entries that get copied into Moodle. They must match the tags used by that external blog.
*Moodle tags are automatically added to each blog entry copied into Moodle from an external blog that uses such tags. This makes it easier to distinguish which of a user's blog entries come from an external blog.

This requires the creation of a new DB table.
Tracker issue: [http://tracker.moodle.org/browse/MDL-19683]

=== Search blog entries ===
It is now possible to search blog entries using a search box. The results maintain the current context, so that if you are viewing a list of blog entries for a particular user, entering a term in the search box will return only the blog entries for that user that match the search term. The search term also appears in the navigation breadcrumbs.

Tracker issue: [http://tracker.moodle.org/browse/MDL-19686]

=== Contextual blog menu ===
Previously, the "blog menu" block was the same on every page on which it appeared. In 2.0 it changes depending on which page you are. For example, if you are on course/view.php, it will include a link to blog entries associated with that course. Also, the link for adding a new entry will include the courseid, making the course association automatically pre-selected in the blog entry edit form.

Tracker issue: [http://tracker.moodle.org/browse/MDL-19687]

=== File attachments ===
The [[Development:File_API|new file manager]] must be implemented to allow for multiple file attachments per blog entry.

Tracker issue: [http://tracker.moodle.org/browse/MDL-19744]

=== Comments ===
The new [[Development:Comments_2.0|Comments API]] makes it possible for anyone having the correct capability to comment on blog entries.

Tracker issue: [http://tracker.moodle.org/browse/MDL-8776]

=== New "Recent blog entries" block ===
This block can be configured to display the last N blog entries, filtered by context. For example, if you are viewing an assignment activity, this block would display the last N blog entries that are associated with that assignment.

Tracker issue: [http://tracker.moodle.org/browse/MDL-19688]

== Potential problems and limitations ==

== DB Structure ==

== Upgrade process ==

== See also ==
*[[Development:Blogs|Early wishlist]]
*[[Student_projects/Blog_improvements|2008 GSoC project addressing some of these improvements]]

Development:Blog 2.0

2009-09-21T06:24:43Z

Nicolasconnault: /* Other links and resources */

{{Work in progress}}{{Moodle 2.0}}

* '''PROJECT STATE: Coding'''
* '''MAIN TRACKER ISSUE''': MDL-19676 Blog 2.0 improvements
* '''DISCUSSION AND COMMENTS''': Link to forum discussion will appear here

== Description of improvements ==
=== Who can view blog entries? ===
Blog entries are either in draft mode (only the author can view it), or in public mode. In public mode, everyone on the entire site can view the blog entry.

At one stage in 2.0 development there was an attempt to restrict who can view certain blog entries, based on course enrolment and capabilities. However, after extensive discussion and feasibility testing it became clear that this would lead to serious performance and usability issues, and would turn the blog into something more akin to a forum. It was thus decided to make all blogs public.

An admin setting can allow for blog entries to be accessible by non-logged-in users, for the purpose of publishing and RSS feed aggregation.

=== Associations ===
A blog entry can optionally be associated with a course. This makes it possible for a user to blog "about" that course. All blog entries associated in that way can be viewed on a page like blog/index.php?courseid=3. This type of filtering of blog entries does not take into account course enrolments.

Additionally, blog entries can be associated with activity modules, in which case the blog entry is automatically associated with the module's course.

This requires the creation of a new table, in which the associations are recorded.

=== Improved navigation ===
Before 2.0, the navigation for any listing of blog entries was either "Site > User > Blogs" (for a user's blog entries) or "Site > Blogs" for the whole site's blog entries, optionally filtered by tag. With the new association features, we need a better way to display what type of blog listing we are looking at, based on the parameters passed to blog/index.php. The navigation should also reflect additional filters such as tag and search.

=== External blogs ===
A user can import blog entries into Moodle from external blogs. The external blog's entries are copied into Moodle when the external blog URL is entered, and a cron task periodically checks these external blogs to copy new entries not yet entered in Moodle. The period of time between checks can be adjusted as an admin setting.

These external blogs are a user preference, and two types of tags can be added to each of them: "External tags" and "Moodle tags":
*External tags are used to filter the external blog entries that get copied into Moodle. They must match the tags used by that external blog.
*Moodle tags are automatically added to each blog entry copied into Moodle from an external blog that uses such tags. This makes it easier to distinguish which of a user's blog entries come from an external blog.

This requires the creation of a new DB table.

=== Search blog entries ===
It is now possible to search blog entries using a search box. The results maintain the current context, so that if you are viewing a list of blog entries for a particular user, entering a term in the search box will return only the blog entries for that user that match the search term. The search term also appears in the navigation breadcrumbs.

=== Contextual blog menu ===
Previously, the "blog menu" block was the same on every page on which it appeared. In 2.0 it changes depending on which page you are. For example, if you are on course/view.php, it will include a link to blog entries associated with that course. Also, the link for adding a new entry will include the courseid, making the course association automatically pre-selected in the blog entry edit form.

=== File attachments ===
The [[Development:File_API|new file manager]] must be implemented to allow for multiple file attachments per blog entry.

=== Comments ===
The new [[Development:Comments_2.0|Comments API]] makes it possible for anyone having the correct capability to comment on blog entries.

=== New "Recent blog entries" block ===
This block can be configured to display the last N blog entries, filtered by context. For example, if you are viewing an assignment activity, this block would display the last N blog entries that are associated with that assignment.

== Potential problems and limitations ==

== DB Structure ==

== Upgrade process ==

== Other links and resources ==
*[[Development:Blogs|Early wishlist]]
*[[Student_projects/Blog_improvements|2008 GSoC project addressing some of these improvements]]

Development:Blog 2.0

2009-09-21T06:24:21Z

Nicolasconnault: Other links and resources

{{Work in progress}}{{Moodle 2.0}}

* '''PROJECT STATE: Coding'''
* '''MAIN TRACKER ISSUE''': MDL-19676 Blog 2.0 improvements
* '''DISCUSSION AND COMMENTS''': Link to forum discussion will appear here

== Description of improvements ==
=== Who can view blog entries? ===
Blog entries are either in draft mode (only the author can view it), or in public mode. In public mode, everyone on the entire site can view the blog entry.

At one stage in 2.0 development there was an attempt to restrict who can view certain blog entries, based on course enrolment and capabilities. However, after extensive discussion and feasibility testing it became clear that this would lead to serious performance and usability issues, and would turn the blog into something more akin to a forum. It was thus decided to make all blogs public.

An admin setting can allow for blog entries to be accessible by non-logged-in users, for the purpose of publishing and RSS feed aggregation.

=== Associations ===
A blog entry can optionally be associated with a course. This makes it possible for a user to blog "about" that course. All blog entries associated in that way can be viewed on a page like blog/index.php?courseid=3. This type of filtering of blog entries does not take into account course enrolments.

Additionally, blog entries can be associated with activity modules, in which case the blog entry is automatically associated with the module's course.

This requires the creation of a new table, in which the associations are recorded.

=== Improved navigation ===
Before 2.0, the navigation for any listing of blog entries was either "Site > User > Blogs" (for a user's blog entries) or "Site > Blogs" for the whole site's blog entries, optionally filtered by tag. With the new association features, we need a better way to display what type of blog listing we are looking at, based on the parameters passed to blog/index.php. The navigation should also reflect additional filters such as tag and search.

=== External blogs ===
A user can import blog entries into Moodle from external blogs. The external blog's entries are copied into Moodle when the external blog URL is entered, and a cron task periodically checks these external blogs to copy new entries not yet entered in Moodle. The period of time between checks can be adjusted as an admin setting.

These external blogs are a user preference, and two types of tags can be added to each of them: "External tags" and "Moodle tags":
*External tags are used to filter the external blog entries that get copied into Moodle. They must match the tags used by that external blog.
*Moodle tags are automatically added to each blog entry copied into Moodle from an external blog that uses such tags. This makes it easier to distinguish which of a user's blog entries come from an external blog.

This requires the creation of a new DB table.

=== Search blog entries ===
It is now possible to search blog entries using a search box. The results maintain the current context, so that if you are viewing a list of blog entries for a particular user, entering a term in the search box will return only the blog entries for that user that match the search term. The search term also appears in the navigation breadcrumbs.

=== Contextual blog menu ===
Previously, the "blog menu" block was the same on every page on which it appeared. In 2.0 it changes depending on which page you are. For example, if you are on course/view.php, it will include a link to blog entries associated with that course. Also, the link for adding a new entry will include the courseid, making the course association automatically pre-selected in the blog entry edit form.

=== File attachments ===
The [[Development:File_API|new file manager]] must be implemented to allow for multiple file attachments per blog entry.

=== Comments ===
The new [[Development:Comments_2.0|Comments API]] makes it possible for anyone having the correct capability to comment on blog entries.

=== New "Recent blog entries" block ===
This block can be configured to display the last N blog entries, filtered by context. For example, if you are viewing an assignment activity, this block would display the last N blog entries that are associated with that assignment.

== Potential problems and limitations ==

== DB Structure ==

== Upgrade process ==

== Other links and resources ==
*[[https://docs.moodle.org/en/Development:Blogs|Early wishlist]]
*[[https://docs.moodle.org/en/Student_projects/Blog_improvements|2008 GSoC project addressing some of these improvements]]

Development:Blog 2.0

2009-09-21T06:20:48Z

Nicolasconnault: /* Description of improvements */

Development:Blog 2.0

2009-09-21T06:16:08Z

Nicolasconnault: /* Description of improvements */

Development:Blog 2.0

2009-09-21T06:14:13Z

Nicolasconnault: /* Description of improvements */

Development:Blog 2.0

2009-09-21T06:08:30Z

Nicolasconnault: /* Description of improvements */

Development:Blog 2.0

2009-09-21T06:04:46Z

Nicolasconnault: /* Description of improvements */

Development:Blog 2.0

2009-09-21T05:59:42Z

Nicolasconnault: /* Description of improvements */

Development:Blog 2.0

2009-09-21T03:45:00Z

Nicolasconnault: New page: {{Work in progress}}{{Moodle 2.0}} * '''PROJECT STATE: Coding''' * '''MAIN TRACKER ISSUE''': MDL-19676 Blog 2.0 improvements * '''DISCUSSION AND COMMENTS''': Link to forum discussion will...

{{Work in progress}}{{Moodle 2.0}}

* '''PROJECT STATE: Coding'''
* '''MAIN TRACKER ISSUE''': MDL-19676 Blog 2.0 improvements
* '''DISCUSSION AND COMMENTS''': Link to forum discussion will appear here

== Description of improvements ==

== Potential problems and limitations ==

== DB Structure ==

== Upgrade process ==

Grade aggregation

2009-09-01T07:23:19Z

Nicolasconnault: /* Weighted mean */

{{Grades}}The aggregation dropdown menu lets you choose the aggregation strategy that will be used to calculate each participant's overall grade for a [[Grade categories|grade category]]. The different options are explained below.

The grades are first converted to percentage values (interval from 0 to 1), then aggregated using one of the strategies below and finally converted to the associated category item's range (between Minimum grade and Maximum grade).

Important: An empty grade is simply a missing gradebook entry, and could mean different things. For example, it could be a participant who hasn't yet submitted an assignment, an assignment submission not yet graded by the teacher, or a grade that has been manually deleted by the gradebook administrator. Caution in interpreting these "empty grades" is thus advised.

== Mean of grades ==
The sum of all grades divided by the total number of grades.
A1 70/100, A2 20/80, A3 10/10, category max 100:
(0.7 + 0.25 + 1.0)/3 = 0.65 --> 65/100

== Weighted mean ==
Each grade item can be given a weight, which is then used in the arithmetic mean aggregation to influence the importance of each item in the overall mean. In simple terms, the category "total" will be equal to the sum of the scores in each grade item, these scores being multiplied by the grade items' weights, and that sum being finally divided by the sum of the weights, as shown in this example.
A1 70/100 weight 10, A2 20/80 weight 5, A3 10/10 weight 3, category max 100:
(0.7*10 + 0.25*5 + 1.0*3)/18 = 0.625 --> 62.5/100

== Simple weighted mean ==
The difference from Weighted mean is that weight is calculated as Maximum grade - Minimum grade for each item. 100 point assignment has weight 100, 10 point assignment has weight 10.
A1 70/100, A2 20/80, A3 10/10, category max 100:
(0.7*100 + 0.25*80 + 1.0*10)/190 = 0.526 --> 52.6/100

== Mean of grades (with extra credits) ==
Arithmetic mean with a twist. An old, now unsupported aggregation strategy provided here only for backward compatibility with old activities.

== Median of grades ==
The middle grade (or the mean of the two middle grades) when grades are arranged in order of size. The advantage over the mean is that it is not affected by outliers (grades which are uncommonly far from the mean).
A1 70/100, A2 20/80, A3 10/10, category max 100:
0.7 + 0.25 + 1.0 --> 0.70 --> 70/100

== Smallest grade ==
The result is the smallest grade after normalisation. It is usually used in combination with Aggregate only non-empty grades.
A1 70/100, A2 20/80, A3 10/10, category max 100:
min(0.7 + 0.25 + 1.0) = 0.25 --> 25/100

== Highest grade ==
The result is the highest grade after normalisation.
A1 70/100, A2 20/80, A3 10/10, category max 100:
max(0.7 + 0.25 + 1.0) = 1.0 --> 100/100

== Mode of grades ==
The mode is the grade that occurs the most frequently. It is more often used for non-numerical grades. The advantage over the mean is that it is not affected by outliers (grades which are uncommonly far from the mean). However it loses its meaning once there is more than one most frequently occurring grade (only one is kept), or when all the grades are different from each other.
A1 70/100, A2 35/50, A3 20/80, A4 10/10, A5 7/10 category max 100:
mode(0.7; 0.7; 0.25; 1.0; 0.7) = 0.7 --> 70/100

== Sum of grades ==
The sum of all grade values. Scale grades are ignored. This is the only type that does not convert the grades to percentages internally. The Maximum grade of associated category item is calculated automatically as a sum of maximums from all aggregated items.
A1 70/100, A2 20/80, A3 10/10:
70 + 20 + 10 = 100/190

When the "Sum of grades" aggregation strategy is used, a grade item can act as Extra credit for the category. This means that the grade item's maximum grade will not be added to the category total's maximum grade, but the item's grade will. Following is an example:

* Item 1 is graded 0-100
* Item 2 is graded 0-75
* Item 1 has the "Act as extra credit" checkbox ticked, Item 2 doesn't.
* Both items belong to Category 1, which has "Sum of grades" as its aggregation strategy
* Category 1's total will be graded 0-75
* A student gets graded 20 on Item 1 and 70 on Item 2
* The student's total for Category 1 will be 75/75 (20+70 = 90 but Item 1 only acts as extra credit, so it brings the total to its maximum)

==Available aggregation types==
[[Image:Available agg types.png|thumb|Available aggregation types setting]]
In Moodle 1.9.5 onwards, a new available aggregation types setting in ''Administration > Grades > [[Grade category settings]]'' enables administrators to reduce the number of aggregation types.

Note that reducing the number of aggregation types simply results in disabled aggregation types not appearing in the aggregation type dropdown menu. All existing grade category calculations remain the same, regardless of whether the aggregation type is later disabled by an administrator.

[[ca:Agregació de les categories]]
[[fr:Tendance centrale de la catégorie]]

Development:Deprecated functions in 2.0

2009-08-20T13:12:28Z

Nicolasconnault: /* link_to_popup_window (54) */

{{Work in progress}}
{{Moodle 2.0}}

This page lists the old HTML-outputting functions of pre-2.0 lib/weblib.php and their 2.0 equivalents using $OUTPUT functions.

== General notes ==
The principle of the new rendering API is to let the developer build metadata-rich components that ''represent'' HTML elements, but may be rendered in many different ways. A menu component, for example, could be rendered as a <select> element, or as a list of radio buttons or check boxes.

The following functions have been arranged in alphabetical order, although some of them are very closely related to each other. The number of occurrences of these function calls at the time of writing are indicated in parentheses.

== Functions to migrate ==
=== button_to_popup_window (0) ===
Old code:
<code php>
button_to_popup_window($url, $name, $linkname, $height, $width, $title, $options, $return, $id, $class);
</code>
New code:
<code php>
$form = new html_form();
$form->button->text = $linkname;
$form->button->title = $title;
$form->button->id = $id;
$form->url = $url;
$form->add_class($class);
$form->button->add_action(new popup_action('click', $url, $name, $options));
echo $OUTPUT->button($form);
</code>
Note: popup parameters ($options) '''must''' be prepared as an associative array, not a string as previously. Simply reusing the $options param previously passed to button_to_popup_window() will not work. The $height and $width params are also part of the popup params. See lib/deprecatedlib.php for an example of how the legacy function call is handled.

=== choose_from_menu (1) ===
Old code:
<code php>
choose_from_menu($options, $name, $selected, $nothing, $script, $nothingvalue, $return, $disabled, $tabindex, $id, $listbox, $multiple, $class);
</code>
New code:
<code php>
$select = moodle_select::make($options, $name, $selected); // Required
$select->nothinglabel = $nothing;
$select->nothingvalue = $nothingvalue;
$select->disabled = $disabled;
$select->tabindex = $tabindex;
$select->id = $id;
$select->listbox = $listbox;
$select->multiple = $multiple;
$select->add_classes($class);

echo $OUTPUT->select($select);
</code>

=== choose_from_menu_nested (0) ===
Old code:
<code php>
choose_from_menu_nested($options, $name, $selected, $nothing, $script, $nothingvalue, $return, $disabled, $tabindex);
</code>
New code:
<code php>
$select = moodle_select::make($options, $name, $selected);
$select->tabindex = $tabindex;
$select->disabled = $disabled;
$select->nothingvalue = $nothingvalue;
$select->nested = true;

echo $OUTPUT->select($select);
</code>
Notes:
#The lang string "choose" is no longer used, in favour of "choosedots".
#The $script param is no longer supported. Please use component::add_action() instead.

=== choose_from_menu_yesno (0) ===
Old code:
<code php>
choose_from_menu_yesno($name, $selected, $script, $return, $disabled, $tabindex);
</code>
New code:
<code php>
$select = moodle_select::make_yes_no($name, $selected);
$select->disabled = $disabled;
$select->tabindex = $tabindex;
echo $OUTPUT->select($select);
</code>
Note: The $script param has been dropped, you need to use component::add_action() instead.

=== choose_from_radio (0) ===

=== close_window_button (0) ===
Old code:
<code php>
close_window_button($name, $return, $reloadopener);
</code>
New code:
<code php>
echo $OUTPUT->close_window_button(get_string($name));
</code>
Note: You must pass a language string already processed by get_string().

=== print_continue (0) ===
Old code:
<code php>
print_continue($link, $return);
</code>
New code:
<code php>
echo $OUTPUT->continue_button($link);
</code>

=== doc_link (0) ===
Old code:
<code php>
doc_link($path, $text, $iconpath);
</code>
New code:
<code php>
echo $OUTPUT->doc_link($path, $text, $iconpath);
</code>
Note: This is not for general use, do not confuse with help_icon()

=== formerr (0) ===
Old code:
<code php>
formerr($string);
</code>
New code:
<code php>
echo $OUTPUT->error_text($error);
</code>

=== helpbutton (0) ===
Old code:
<code php>
helpbutton($page, $title, $module, $image, $linktext, $text, $return, $imagetext);
</code>
New code:
<code php>
$helpicon = new help_icon();
$helpicon->page = $page; // required
$helpicon->text = $title; // required
$helpicon->module = $module; // defaults to 'moodle'
$helpicon->linktext = $linktext;

echo $OUTPUT->help_icon($helpicon);
</code>

=== link_to_popup_window (0) ===
Old code:
<code php>
link_to_popup_window($url, $name, $linkname, $height, $width, $title, $options, $return);
</code>
New code:
<code php>
$link = html_link::make($url, $linkname);
$link->title = $title; // optional
$options['height'] = $height; // optional
$options['width'] = $width; // optional
$link->add_action(new popup_action('click', $url, $name, $options));
echo $OUTPUT->link($link);
</code>
Note: popup parameters ($options) '''must''' be prepared as an associative array, not a string as previously. Simply reusing the $options param previously passed to link_to_popup_window() will not work. See lib/deprecatedlib.php for an example of how the legacy function call is handled.

=== notice_yesno (0) ===
Old code:
<code php>
notice_yesno($message, $linkyes, $linkno, $optionsyes, $optionsno, $methodyes, $methodno);
</code>
New code (simplest form):
<code php>
echo $OUTPUT->confirm($message, $linkyes, $linkno);
</code>

New code (with options in arrays):
<code php>
echo $OUTPUT->confirm($message, new moodle_url($linkyes, $optionsyes), new moodle_url($linkno, $optionsno));
</code>

New code (if the "get" method is required):
<code php>
$formcontinue = html_form::make_button($linkyes, $optionsyes, get_string('yes'), $methodyes);
$formcancel = html_form::make_button($linkno, $optionsno, get_string('no'), $methodno);
echo $OUTPUT->confirm($message, $formcontinue, $formcancel);
</code>

=== notify (0) ===
Old code:
<code php>
notify($message, $classes, $align, $return);
</code>
New code:
<code php>
echo $OUTPUT->notification($message, $classes='');
</code>
Note: Use a CSS rule for alignment.

=== popup_form (0) ===
Old code:
<code php>
popup_form($baseurl, $options, $formid, $selected, $nothing, $help, $helptext, $return, $targetwindow, $selectlabel, $optionsextra, $submitvalue, $disabled, $showbutton);
</code>
New code:
<code php>
// if $baseurl == 'http://domain.com/index.php?var1=1&var2='
$select = html_select::make_popup_form('http://domain.com/index.php?var1=1', 'var2', $options, $formid, $selected);
$select->disabled = $disabled; // optional
$select->set_label($selectlabel, $select->id); // optional, set to false if no "nothing" option is desired (when $selectlabel == '' in original call)
$select->set_help_icon($help, $helptext); // optional
$select->form->button->text = $submitvalue; // optional

echo $OUTPUT->select($select);
</code>
Notes:
*The $optionsextra param is not supported. If your code uses it, you should find another way to add extra params to your <option> tags without using this horrible hack which usually includes inline JS or CSS.

=== print_arrow (15) ===
=== print_box* (0) ===
Old code:
<code php>
print_box($message, $classes, $ids, $return);
print_box_start($classes, $ids, $return);
print_box_end();
</code>
New code:
<code php>
echo $OUTPUT->box($message, $classes, $ids);
echo $OUTPUT->box_start($classes, $ids);
echo $OUTPUT->box_end();
</code>

=== print_checkbox (10) ===
Old code:
<code php>
print_checkbox($name, $value, $checked, $label, $alt, $script, $return);
</code>
New code:
<code php>
$checkbox = new html_select_option();
$checkbox->value = $value; // Required
$checkbox->selected = $checked;
$checkbox->text = $label;
$checkbox->label->text = $label;
$checkbox->alt = $alt;

echo $OUTPUT->checkbox($checkbox, $name);
</code>
Note: html_select_option is a component that can be rendered as a select <option>, a radio button or a checkbox. It holds sufficient information to render all these elements, except the $name variable which is attached to a moodle_select component. This is why we pass the $name string to $OUTPUT->checkbox().

=== print_container (0) ===
Old code:
<code php>
print_container($message, $clearfix, $classes, $idbase, $return);
</code>
New code:
<code php>
if ($clearfix) {
$classes .= ' clearfix';
}
echo $OUTPUT->container($message, $classes, $idbase);
</code>

=== print_date_selector (0) ===

=== print_footer (0) ===
Old code:
<code php>
print_footer($course, $usercourse, $return);
</code>
New code:
<code php>
echo $OUTPUT->footer();
</code>
Notes: No parameters are required.

=== print_header (501) ===
Old code:
<code php>
print_header($title, $heading, $navigation, $focus, $meta, $cache, $button, $menu, $usexml, $bodytags, $return);
</code>
New code:
<code php>
$PAGE->set_heading($heading); // Required
$PAGE->set_title($title);
$PAGE->set_cacheable($cache);
$PAGE->set_focuscontrol($focus);
$PAGE->set_button($button);
echo $OUTPUT->header($navigation, $menu);
</code>
Note: Navigation code is being rewritten, this doc will then be updated with the new usage.

=== print_heading_with_help (0) ===

=== print_heading (0) ===
Old code:
<code php>
print_heading($text, $align, $size, $class, $return, $id);
</code>
New code:
<code php>
echo $OUTPUT->heading($text, $size, $class, $id);
</code>
Note: Use a CSS class rule to control alignment.

=== print_heading_block (0) ===

=== print_headline (0) ===
Old code:
<code php>
print_headline($text, $size);
</code>
New code:
<code php>
echo $OUTPUT->heading($text, $size);
</code>

=== print_paging_bar (2) ===

Old code:
<code php>
print_paging_bar($totalcount, $page, $perpage, $baseurl, $pagevar, $nocurr, $return);
</code>
New code:
<code php>
$pagingbar = new moodle_paging_bar();
$pagingbar->totalcount = $totalcount; // Required
$pagingbar->page = $page; // Required
$pagingbar->perpage = $perpage; // Required
$pagingbar->baseurl = $baseurl; // Required
$pagingbar->pagevar = $pagevar;
$pagingbar->nocurr = $nocurr;
echo $OUTPUT->paging_bar($pagingbar);
</code>
Note: The last two instances of print_paging_bar are found in the old tablelib, which will soon be deprecated.

=== print_scale_menu_helpbutton (0) ===
Old code:
<code php>
print_scale_menu_helpbutton($courseid, $scale);
</code>
New code:
<code php>
echo $OUTPUT->help_button(help_button::make_scale_menu($courseid, $scale));
</code>

=== print_side_block (4) ===
=== print_single_button (0) ===
Old code:
<code php>
print_single_button($link, $options, $label, $method, $notusedanymore, $return, $tooltip, $disabled, $jsconfirmmessage, $formid)
</code>
New code:
<code php>
$form = new html_form();
$form->url = new moodle_url($link, $options); // Required
$form->button = new html_button();
$form->button->text = $label; // Required
$form->button->disabled = $disabled;
$form->button->title = $tooltip;
$form->method = $method;
$form->id = $formid;

if ($jsconfirmmessage) {
$confirmaction = new component_action('click', 'confirm_dialog', array('message' => $jsconfirmmessage));
$form->button->add_action($confirmaction);
}

$output = $OUTPUT->button($form);
</code>

=== print_spacer (0) ===
Old code:
<code php>
print_spacer($height, $width, $br, $return);
</code>
New code:
<code php>
$spacer = new html_image();
$spacer->height = $height;
$spacer->width = $width;
echo $OUTPUT->spacer($spacer);
</code>
Note: The $br attribute has been dropped. You can simply add a line break manually if you need one.

=== print_table (0) ===
Old code:
<code php>
$table = new stdClass();
$table->class = 'mytable';
$table->head = array('Firstname', 'Lastname');
$table->rowclasses = array();
// (other table properties here)
$table->data = array(array(...),array(...),array(...));
print_table($table, $return);
</code>
New code:
<code php>
$table = new html_table();
$table->set_classes('mytable'); // note the new style of setting CSS class
$table->head = array('First name', 'Last name');
$table->colclasses = array('name fname','name lname');
$table->rowclasses = array();
// (other table properties here)
$table->data = array(array(...),array(...),array(...));
echo $OUTPUT->table($newtable);
</code>
Notes: The new html_table object has the same member variables as the one originally used by print_table(), but has additional, required methods. You must map the old $table object to the new html_table object, as demonstrated above and in lib/deprecatedlib.php (see old print_table function).

=== print_textarea (55) ===
=== print_textfield (0) ===

=== print_time_selector (0) ===

=== print_user_picture (0) ===

Old code:
<code php>
print_user_picture($user, $courseid, $picture, $size, $return, $link, $target, $alttext);
</code>
New code (simple):
<code php>
$userpic = new moodle_user_picture();
$userpic->user = $user;
$userpic->courseid = $courseid;
echo $OUTPUT->user_picture($userpic);
</code>
New code (complex: alternate text, size, different image and popup action):
<code php>
$userpic = new user_picture();
$userpic->user = $user;
$userpic->courseid = $courseid;
$userpic->size = $size;
$userpic->link = $link;
$userpic->alttext = $alttext;
$userpic->image->src = $picture;
$userpic->add_action(new popup_action('click', new moodle_url($target)));

echo $OUTPUT->user_picture($userpic);
</code>

=== update_course_button (0) ===

=== update_module_button (94) ===
Old code:
<code php>
$button = update_module_button($cm->id, $course->id, get_string('modulename', 'workshop')); // passed to print_header_simple()
</code>
New code:
<code php>
$PAGE->set_button($OUTPUT->update_module_button($cm->id, 'workshop'));
</code>
Note: $courseid param has been dropped.

=== update_tag_button (0) ===

== Non-supported functions ==
These functions have been completely dropped in 2.0, most likely because they were used very little or not at all. All calls to these functions in core should have been replaced.
=== blocks_print_group ===
=== print_file_picture ===
=== print_png ===
=== print_scale_menu ===
=== print_side_block_end ===
=== print_side_block_start ===
=== print_timer_selector ===
=== print_user ===
=== update_categories_search_button ===
=== update_mymoodle_icon ===

==See also==

* [[Developement:How_Moodle_outputs_HTML]]
* [[Development:Migrating your code to the 2.0 rendering_API]]

{{CategoryDeveloper}}

Development:Deprecated functions in 2.0

2009-08-20T12:09:13Z

Nicolasconnault: /* link_to_popup_window (54) */

{{Work in progress}}
{{Moodle 2.0}}

This page lists the old HTML-outputting functions of pre-2.0 lib/weblib.php and their 2.0 equivalents using $OUTPUT functions.

== General notes ==
The principle of the new rendering API is to let the developer build metadata-rich components that ''represent'' HTML elements, but may be rendered in many different ways. A menu component, for example, could be rendered as a <select> element, or as a list of radio buttons or check boxes.

The following functions have been arranged in alphabetical order, although some of them are very closely related to each other. The number of occurrences of these function calls at the time of writing are indicated in parentheses.

== Functions to migrate ==
=== button_to_popup_window (0) ===
Old code:
<code php>
button_to_popup_window($url, $name, $linkname, $height, $width, $title, $options, $return, $id, $class);
</code>
New code:
<code php>
$form = new html_form();
$form->button->text = $linkname;
$form->button->title = $title;
$form->button->id = $id;
$form->url = $url;
$form->add_class($class);
$form->button->add_action(new popup_action('click', $url, $name, $options));
echo $OUTPUT->button($form);
</code>
Note: popup parameters ($options) '''must''' be prepared as an associative array, not a string as previously. Simply reusing the $options param previously passed to button_to_popup_window() will not work. The $height and $width params are also part of the popup params. See lib/deprecatedlib.php for an example of how the legacy function call is handled.

=== choose_from_menu (1) ===
Old code:
<code php>
choose_from_menu($options, $name, $selected, $nothing, $script, $nothingvalue, $return, $disabled, $tabindex, $id, $listbox, $multiple, $class);
</code>
New code:
<code php>
$select = moodle_select::make($options, $name, $selected); // Required
$select->nothinglabel = $nothing;
$select->nothingvalue = $nothingvalue;
$select->disabled = $disabled;
$select->tabindex = $tabindex;
$select->id = $id;
$select->listbox = $listbox;
$select->multiple = $multiple;
$select->add_classes($class);

echo $OUTPUT->select($select);
</code>

=== choose_from_menu_nested (0) ===
Old code:
<code php>
choose_from_menu_nested($options, $name, $selected, $nothing, $script, $nothingvalue, $return, $disabled, $tabindex);
</code>
New code:
<code php>
$select = moodle_select::make($options, $name, $selected);
$select->tabindex = $tabindex;
$select->disabled = $disabled;
$select->nothingvalue = $nothingvalue;
$select->nested = true;

echo $OUTPUT->select($select);
</code>
Notes:
#The lang string "choose" is no longer used, in favour of "choosedots".
#The $script param is no longer supported. Please use component::add_action() instead.

=== choose_from_menu_yesno (0) ===
Old code:
<code php>
choose_from_menu_yesno($name, $selected, $script, $return, $disabled, $tabindex);
</code>
New code:
<code php>
$select = moodle_select::make_yes_no($name, $selected);
$select->disabled = $disabled;
$select->tabindex = $tabindex;
echo $OUTPUT->select($select);
</code>
Note: The $script param has been dropped, you need to use component::add_action() instead.

=== choose_from_radio (0) ===

=== close_window_button (0) ===
Old code:
<code php>
close_window_button($name, $return, $reloadopener);
</code>
New code:
<code php>
echo $OUTPUT->close_window_button(get_string($name));
</code>
Note: You must pass a language string already processed by get_string().

=== print_continue (0) ===
Old code:
<code php>
print_continue($link, $return);
</code>
New code:
<code php>
echo $OUTPUT->continue_button($link);
</code>

=== doc_link (0) ===
Old code:
<code php>
doc_link($path, $text, $iconpath);
</code>
New code:
<code php>
echo $OUTPUT->doc_link($path, $text, $iconpath);
</code>
Note: This is not for general use, do not confuse with help_icon()

=== formerr (0) ===
Old code:
<code php>
formerr($string);
</code>
New code:
<code php>
echo $OUTPUT->error_text($error);
</code>

=== helpbutton (0) ===
Old code:
<code php>
helpbutton($page, $title, $module, $image, $linktext, $text, $return, $imagetext);
</code>
New code:
<code php>
$helpicon = new help_icon();
$helpicon->page = $page; // required
$helpicon->text = $title; // required
$helpicon->module = $module; // defaults to 'moodle'
$helpicon->linktext = $linktext;

echo $OUTPUT->help_icon($helpicon);
</code>

=== link_to_popup_window (54) ===
Old code:
<code php>
link_to_popup_window($url, $name, $linkname, $height, $width, $title, $options, $return);
</code>
New code:
<code php>
$link = html_link::make($url, $linkname);
$link->title = $title; // optional
$options['height'] = $height; // optional
$options['width'] = $width; // optional
$link->add_action(new popup_action('click', $url, $name, $options));
echo $OUTPUT->link($link);
</code>
Note: popup parameters ($options) '''must''' be prepared as an associative array, not a string as previously. Simply reusing the $options param previously passed to link_to_popup_window() will not work. See lib/deprecatedlib.php for an example of how the legacy function call is handled.

=== notice_yesno (0) ===
Old code:
<code php>
notice_yesno($message, $linkyes, $linkno, $optionsyes, $optionsno, $methodyes, $methodno);
</code>
New code (simplest form):
<code php>
echo $OUTPUT->confirm($message, $linkyes, $linkno);
</code>

New code (with options in arrays):
<code php>
echo $OUTPUT->confirm($message, new moodle_url($linkyes, $optionsyes), new moodle_url($linkno, $optionsno));
</code>

New code (if the "get" method is required):
<code php>
$formcontinue = html_form::make_button($linkyes, $optionsyes, get_string('yes'), $methodyes);
$formcancel = html_form::make_button($linkno, $optionsno, get_string('no'), $methodno);
echo $OUTPUT->confirm($message, $formcontinue, $formcancel);
</code>

=== notify (0) ===
Old code:
<code php>
notify($message, $classes, $align, $return);
</code>
New code:
<code php>
echo $OUTPUT->notification($message, $classes='');
</code>
Note: Use a CSS rule for alignment.

=== popup_form (0) ===
Old code:
<code php>
popup_form($baseurl, $options, $formid, $selected, $nothing, $help, $helptext, $return, $targetwindow, $selectlabel, $optionsextra, $submitvalue, $disabled, $showbutton);
</code>
New code:
<code php>
// if $baseurl == 'http://domain.com/index.php?var1=1&var2='
$select = html_select::make_popup_form('http://domain.com/index.php?var1=1', 'var2', $options, $formid, $selected);
$select->disabled = $disabled; // optional
$select->set_label($selectlabel, $select->id); // optional, set to false if no "nothing" option is desired (when $selectlabel == '' in original call)
$select->set_help_icon($help, $helptext); // optional
$select->form->button->text = $submitvalue; // optional

echo $OUTPUT->select($select);
</code>
Notes:
*The $optionsextra param is not supported. If your code uses it, you should find another way to add extra params to your <option> tags without using this horrible hack which usually includes inline JS or CSS.

=== print_arrow (15) ===
=== print_box* (0) ===
Old code:
<code php>
print_box($message, $classes, $ids, $return);
print_box_start($classes, $ids, $return);
print_box_end();
</code>
New code:
<code php>
echo $OUTPUT->box($message, $classes, $ids);
echo $OUTPUT->box_start($classes, $ids);
echo $OUTPUT->box_end();
</code>

=== print_checkbox (10) ===
Old code:
<code php>
print_checkbox($name, $value, $checked, $label, $alt, $script, $return);
</code>
New code:
<code php>
$checkbox = new html_select_option();
$checkbox->value = $value; // Required
$checkbox->selected = $checked;
$checkbox->text = $label;
$checkbox->label->text = $label;
$checkbox->alt = $alt;

echo $OUTPUT->checkbox($checkbox, $name);
</code>
Note: html_select_option is a component that can be rendered as a select <option>, a radio button or a checkbox. It holds sufficient information to render all these elements, except the $name variable which is attached to a moodle_select component. This is why we pass the $name string to $OUTPUT->checkbox().

=== print_container (0) ===
Old code:
<code php>
print_container($message, $clearfix, $classes, $idbase, $return);
</code>
New code:
<code php>
if ($clearfix) {
$classes .= ' clearfix';
}
echo $OUTPUT->container($message, $classes, $idbase);
</code>

=== print_date_selector (0) ===

=== print_footer (0) ===
Old code:
<code php>
print_footer($course, $usercourse, $return);
</code>
New code:
<code php>
echo $OUTPUT->footer();
</code>
Notes: No parameters are required.

=== print_header (501) ===
Old code:
<code php>
print_header($title, $heading, $navigation, $focus, $meta, $cache, $button, $menu, $usexml, $bodytags, $return);
</code>
New code:
<code php>
$PAGE->set_heading($heading); // Required
$PAGE->set_title($title);
$PAGE->set_cacheable($cache);
$PAGE->set_focuscontrol($focus);
$PAGE->set_button($button);
echo $OUTPUT->header($navigation, $menu);
</code>
Note: Navigation code is being rewritten, this doc will then be updated with the new usage.

=== print_heading_with_help (0) ===

=== print_heading (0) ===
Old code:
<code php>
print_heading($text, $align, $size, $class, $return, $id);
</code>
New code:
<code php>
echo $OUTPUT->heading($text, $size, $class, $id);
</code>
Note: Use a CSS class rule to control alignment.

=== print_heading_block (0) ===

=== print_headline (0) ===
Old code:
<code php>
print_headline($text, $size);
</code>
New code:
<code php>
echo $OUTPUT->heading($text, $size);
</code>

=== print_paging_bar (2) ===

Old code:
<code php>
print_paging_bar($totalcount, $page, $perpage, $baseurl, $pagevar, $nocurr, $return);
</code>
New code:
<code php>
$pagingbar = new moodle_paging_bar();
$pagingbar->totalcount = $totalcount; // Required
$pagingbar->page = $page; // Required
$pagingbar->perpage = $perpage; // Required
$pagingbar->baseurl = $baseurl; // Required
$pagingbar->pagevar = $pagevar;
$pagingbar->nocurr = $nocurr;
echo $OUTPUT->paging_bar($pagingbar);
</code>
Note: The last two instances of print_paging_bar are found in the old tablelib, which will soon be deprecated.

=== print_scale_menu_helpbutton (0) ===
Old code:
<code php>
print_scale_menu_helpbutton($courseid, $scale);
</code>
New code:
<code php>
echo $OUTPUT->help_button(help_button::make_scale_menu($courseid, $scale));
</code>

=== print_side_block (4) ===
=== print_single_button (0) ===
Old code:
<code php>
print_single_button($link, $options, $label, $method, $notusedanymore, $return, $tooltip, $disabled, $jsconfirmmessage, $formid)
</code>
New code:
<code php>
$form = new html_form();
$form->url = new moodle_url($link, $options); // Required
$form->button = new html_button();
$form->button->text = $label; // Required
$form->button->disabled = $disabled;
$form->button->title = $tooltip;
$form->method = $method;
$form->id = $formid;

if ($jsconfirmmessage) {
$confirmaction = new component_action('click', 'confirm_dialog', array('message' => $jsconfirmmessage));
$form->button->add_action($confirmaction);
}

$output = $OUTPUT->button($form);
</code>

=== print_spacer (0) ===
Old code:
<code php>
print_spacer($height, $width, $br, $return);
</code>
New code:
<code php>
$spacer = new html_image();
$spacer->height = $height;
$spacer->width = $width;
echo $OUTPUT->spacer($spacer);
</code>
Note: The $br attribute has been dropped. You can simply add a line break manually if you need one.

=== print_table (0) ===
Old code:
<code php>
$table = new stdClass();
$table->class = 'mytable';
$table->head = array('Firstname', 'Lastname');
$table->rowclasses = array();
// (other table properties here)
$table->data = array(array(...),array(...),array(...));
print_table($table, $return);
</code>
New code:
<code php>
$table = new html_table();
$table->set_classes('mytable'); // note the new style of setting CSS class
$table->head = array('First name', 'Last name');
$table->colclasses = array('name fname','name lname');
$table->rowclasses = array();
// (other table properties here)
$table->data = array(array(...),array(...),array(...));
echo $OUTPUT->table($newtable);
</code>
Notes: The new html_table object has the same member variables as the one originally used by print_table(), but has additional, required methods. You must map the old $table object to the new html_table object, as demonstrated above and in lib/deprecatedlib.php (see old print_table function).

=== print_textarea (55) ===
=== print_textfield (0) ===

=== print_time_selector (0) ===

=== print_user_picture (0) ===

Old code:
<code php>
print_user_picture($user, $courseid, $picture, $size, $return, $link, $target, $alttext);
</code>
New code (simple):
<code php>
$userpic = new moodle_user_picture();
$userpic->user = $user;
$userpic->courseid = $courseid;
echo $OUTPUT->user_picture($userpic);
</code>
New code (complex: alternate text, size, different image and popup action):
<code php>
$userpic = new user_picture();
$userpic->user = $user;
$userpic->courseid = $courseid;
$userpic->size = $size;
$userpic->link = $link;
$userpic->alttext = $alttext;
$userpic->image->src = $picture;
$userpic->add_action(new popup_action('click', new moodle_url($target)));

echo $OUTPUT->user_picture($userpic);
</code>

=== update_course_button (0) ===

=== update_module_button (94) ===
Old code:
<code php>
$button = update_module_button($cm->id, $course->id, get_string('modulename', 'workshop')); // passed to print_header_simple()
</code>
New code:
<code php>
$PAGE->set_button($OUTPUT->update_module_button($cm->id, 'workshop'));
</code>
Note: $courseid param has been dropped.

=== update_tag_button (0) ===

== Non-supported functions ==
These functions have been completely dropped in 2.0, most likely because they were used very little or not at all. All calls to these functions in core should have been replaced.
=== blocks_print_group ===
=== print_file_picture ===
=== print_png ===
=== print_scale_menu ===
=== print_side_block_end ===
=== print_side_block_start ===
=== print_timer_selector ===
=== print_user ===
=== update_categories_search_button ===
=== update_mymoodle_icon ===

==See also==

* [[Developement:How_Moodle_outputs_HTML]]
* [[Development:Migrating your code to the 2.0 rendering_API]]

{{CategoryDeveloper}}

Development:Deprecated functions in 2.0

2009-08-20T09:02:52Z

Nicolasconnault: /* link_to_popup_window (54) */

{{Work in progress}}
{{Moodle 2.0}}

This page lists the old HTML-outputting functions of pre-2.0 lib/weblib.php and their 2.0 equivalents using $OUTPUT functions.

== General notes ==
The principle of the new rendering API is to let the developer build metadata-rich components that ''represent'' HTML elements, but may be rendered in many different ways. A menu component, for example, could be rendered as a <select> element, or as a list of radio buttons or check boxes.

The following functions have been arranged in alphabetical order, although some of them are very closely related to each other. The number of occurrences of these function calls at the time of writing are indicated in parentheses.

== Functions to migrate ==
=== button_to_popup_window (0) ===
Old code:
<code php>
button_to_popup_window($url, $name, $linkname, $height, $width, $title, $options, $return, $id, $class);
</code>
New code:
<code php>
$form = new html_form();
$form->button->text = $linkname;
$form->button->title = $title;
$form->button->id = $id;
$form->url = $url;
$form->add_class($class);
$form->button->add_action(new popup_action('click', $url, $name, $options));
echo $OUTPUT->button($form);
</code>
Note: popup parameters ($options) '''must''' be prepared as an associative array, not a string as previously. Simply reusing the $options param previously passed to button_to_popup_window() will not work. The $height and $width params are also part of the popup params. See lib/deprecatedlib.php for an example of how the legacy function call is handled.

=== choose_from_menu (1) ===
Old code:
<code php>
choose_from_menu($options, $name, $selected, $nothing, $script, $nothingvalue, $return, $disabled, $tabindex, $id, $listbox, $multiple, $class);
</code>
New code:
<code php>
$select = moodle_select::make($options, $name, $selected); // Required
$select->nothinglabel = $nothing;
$select->nothingvalue = $nothingvalue;
$select->disabled = $disabled;
$select->tabindex = $tabindex;
$select->id = $id;
$select->listbox = $listbox;
$select->multiple = $multiple;
$select->add_classes($class);

echo $OUTPUT->select($select);
</code>

=== choose_from_menu_nested (0) ===
Old code:
<code php>
choose_from_menu_nested($options, $name, $selected, $nothing, $script, $nothingvalue, $return, $disabled, $tabindex);
</code>
New code:
<code php>
$select = moodle_select::make($options, $name, $selected);
$select->tabindex = $tabindex;
$select->disabled = $disabled;
$select->nothingvalue = $nothingvalue;
$select->nested = true;

echo $OUTPUT->select($select);
</code>
Notes:
#The lang string "choose" is no longer used, in favour of "choosedots".
#The $script param is no longer supported. Please use component::add_action() instead.

=== choose_from_menu_yesno (0) ===
Old code:
<code php>
choose_from_menu_yesno($name, $selected, $script, $return, $disabled, $tabindex);
</code>
New code:
<code php>
$select = moodle_select::make_yes_no($name, $selected);
$select->disabled = $disabled;
$select->tabindex = $tabindex;
echo $OUTPUT->select($select);
</code>
Note: The $script param has been dropped, you need to use component::add_action() instead.

=== choose_from_radio (0) ===

=== close_window_button (0) ===
Old code:
<code php>
close_window_button($name, $return, $reloadopener);
</code>
New code:
<code php>
echo $OUTPUT->close_window_button(get_string($name));
</code>
Note: You must pass a language string already processed by get_string().

=== print_continue (0) ===
Old code:
<code php>
print_continue($link, $return);
</code>
New code:
<code php>
echo $OUTPUT->continue_button($link);
</code>

=== doc_link (0) ===
Old code:
<code php>
doc_link($path, $text, $iconpath);
</code>
New code:
<code php>
echo $OUTPUT->doc_link($path, $text, $iconpath);
</code>
Note: This is not for general use, do not confuse with help_icon()

=== formerr (0) ===
Old code:
<code php>
formerr($string);
</code>
New code:
<code php>
echo $OUTPUT->error_text($error);
</code>

=== helpbutton (0) ===
Old code:
<code php>
helpbutton($page, $title, $module, $image, $linktext, $text, $return, $imagetext);
</code>
New code:
<code php>
$helpicon = new help_icon();
$helpicon->page = $page; // required
$helpicon->text = $title; // required
$helpicon->module = $module; // defaults to 'moodle'
$helpicon->linktext = $linktext;

echo $OUTPUT->help_icon($helpicon);
</code>

=== link_to_popup_window (54) ===
Old code:
<code php>
link_to_popup_window($url, $name, $linkname, $height, $width, $title, $options, $return);
</code>
New code:
<code php>
$link = html_link::make($url, $linkname);
$link->title = $title; // optional
$options['height'] = $height; // optional
$options['width'] = $width; // optional
$link->add_action(new popup_action('click', $url, $name, $options));
echo $OUTPUT->link_to_popup($link);
</code>
Note: popup parameters ($options) '''must''' be prepared as an associative array, not a string as previously. Simply reusing the $options param previously passed to link_to_popup_window() will not work. See lib/deprecatedlib.php for an example of how the legacy function call is handled.

=== notice_yesno (0) ===
Old code:
<code php>
notice_yesno($message, $linkyes, $linkno, $optionsyes, $optionsno, $methodyes, $methodno);
</code>
New code (simplest form):
<code php>
echo $OUTPUT->confirm($message, $linkyes, $linkno);
</code>

New code (with options in arrays):
<code php>
echo $OUTPUT->confirm($message, new moodle_url($linkyes, $optionsyes), new moodle_url($linkno, $optionsno));
</code>

New code (if the "get" method is required):
<code php>
$formcontinue = html_form::make_button($linkyes, $optionsyes, get_string('yes'), $methodyes);
$formcancel = html_form::make_button($linkno, $optionsno, get_string('no'), $methodno);
echo $OUTPUT->confirm($message, $formcontinue, $formcancel);
</code>

=== notify (0) ===
Old code:
<code php>
notify($message, $classes, $align, $return);
</code>
New code:
<code php>
echo $OUTPUT->notification($message, $classes='');
</code>
Note: Use a CSS rule for alignment.

=== popup_form (0) ===
Old code:
<code php>
popup_form($baseurl, $options, $formid, $selected, $nothing, $help, $helptext, $return, $targetwindow, $selectlabel, $optionsextra, $submitvalue, $disabled, $showbutton);
</code>
New code:
<code php>
// if $baseurl == 'http://domain.com/index.php?var1=1&var2='
$select = html_select::make_popup_form('http://domain.com/index.php?var1=1', 'var2', $options, $formid, $selected);
$select->disabled = $disabled; // optional
$select->set_label($selectlabel, $select->id); // optional, set to false if no "nothing" option is desired (when $selectlabel == '' in original call)
$select->set_help_icon($help, $helptext); // optional
$select->form->button->text = $submitvalue; // optional

echo $OUTPUT->select($select);
</code>
Notes:
*The $optionsextra param is not supported. If your code uses it, you should find another way to add extra params to your <option> tags without using this horrible hack which usually includes inline JS or CSS.

=== print_arrow (15) ===
=== print_box* (0) ===
Old code:
<code php>
print_box($message, $classes, $ids, $return);
print_box_start($classes, $ids, $return);
print_box_end();
</code>
New code:
<code php>
echo $OUTPUT->box($message, $classes, $ids);
echo $OUTPUT->box_start($classes, $ids);
echo $OUTPUT->box_end();
</code>

=== print_checkbox (10) ===
Old code:
<code php>
print_checkbox($name, $value, $checked, $label, $alt, $script, $return);
</code>
New code:
<code php>
$checkbox = new html_select_option();
$checkbox->value = $value; // Required
$checkbox->selected = $checked;
$checkbox->text = $label;
$checkbox->label->text = $label;
$checkbox->alt = $alt;

echo $OUTPUT->checkbox($checkbox, $name);
</code>
Note: html_select_option is a component that can be rendered as a select <option>, a radio button or a checkbox. It holds sufficient information to render all these elements, except the $name variable which is attached to a moodle_select component. This is why we pass the $name string to $OUTPUT->checkbox().

=== print_container (0) ===
Old code:
<code php>
print_container($message, $clearfix, $classes, $idbase, $return);
</code>
New code:
<code php>
if ($clearfix) {
$classes .= ' clearfix';
}
echo $OUTPUT->container($message, $classes, $idbase);
</code>

=== print_date_selector (0) ===

=== print_footer (0) ===
Old code:
<code php>
print_footer($course, $usercourse, $return);
</code>
New code:
<code php>
echo $OUTPUT->footer();
</code>
Notes: No parameters are required.

=== print_header (501) ===
Old code:
<code php>
print_header($title, $heading, $navigation, $focus, $meta, $cache, $button, $menu, $usexml, $bodytags, $return);
</code>
New code:
<code php>
$PAGE->set_heading($heading); // Required
$PAGE->set_title($title);
$PAGE->set_cacheable($cache);
$PAGE->set_focuscontrol($focus);
$PAGE->set_button($button);
echo $OUTPUT->header($navigation, $menu);
</code>
Note: Navigation code is being rewritten, this doc will then be updated with the new usage.

=== print_heading_with_help (0) ===

=== print_heading (0) ===
Old code:
<code php>
print_heading($text, $align, $size, $class, $return, $id);
</code>
New code:
<code php>
echo $OUTPUT->heading($text, $size, $class, $id);
</code>
Note: Use a CSS class rule to control alignment.

=== print_heading_block (0) ===

=== print_headline (0) ===
Old code:
<code php>
print_headline($text, $size);
</code>
New code:
<code php>
echo $OUTPUT->heading($text, $size);
</code>

=== print_paging_bar (2) ===

Old code:
<code php>
print_paging_bar($totalcount, $page, $perpage, $baseurl, $pagevar, $nocurr, $return);
</code>
New code:
<code php>
$pagingbar = new moodle_paging_bar();
$pagingbar->totalcount = $totalcount; // Required
$pagingbar->page = $page; // Required
$pagingbar->perpage = $perpage; // Required
$pagingbar->baseurl = $baseurl; // Required
$pagingbar->pagevar = $pagevar;
$pagingbar->nocurr = $nocurr;
echo $OUTPUT->paging_bar($pagingbar);
</code>
Note: The last two instances of print_paging_bar are found in the old tablelib, which will soon be deprecated.

=== print_scale_menu_helpbutton (0) ===
Old code:
<code php>
print_scale_menu_helpbutton($courseid, $scale);
</code>
New code:
<code php>
echo $OUTPUT->help_button(help_button::make_scale_menu($courseid, $scale));
</code>

=== print_side_block (4) ===
=== print_single_button (0) ===
Old code:
<code php>
print_single_button($link, $options, $label, $method, $notusedanymore, $return, $tooltip, $disabled, $jsconfirmmessage, $formid)
</code>
New code:
<code php>
$form = new html_form();
$form->url = new moodle_url($link, $options); // Required
$form->button = new html_button();
$form->button->text = $label; // Required
$form->button->disabled = $disabled;
$form->button->title = $tooltip;
$form->method = $method;
$form->id = $formid;

if ($jsconfirmmessage) {
$confirmaction = new component_action('click', 'confirm_dialog', array('message' => $jsconfirmmessage));
$form->button->add_action($confirmaction);
}

$output = $OUTPUT->button($form);
</code>

=== print_spacer (0) ===
Old code:
<code php>
print_spacer($height, $width, $br, $return);
</code>
New code:
<code php>
$spacer = new html_image();
$spacer->height = $height;
$spacer->width = $width;
echo $OUTPUT->spacer($spacer);
</code>
Note: The $br attribute has been dropped. You can simply add a line break manually if you need one.

=== print_table (0) ===
Old code:
<code php>
$table = new stdClass();
$table->class = 'mytable';
$table->head = array('Firstname', 'Lastname');
$table->rowclasses = array();
// (other table properties here)
$table->data = array(array(...),array(...),array(...));
print_table($table, $return);
</code>
New code:
<code php>
$table = new html_table();
$table->set_classes('mytable'); // note the new style of setting CSS class
$table->head = array('First name', 'Last name');
$table->colclasses = array('name fname','name lname');
$table->rowclasses = array();
// (other table properties here)
$table->data = array(array(...),array(...),array(...));
echo $OUTPUT->table($newtable);
</code>
Notes: The new html_table object has the same member variables as the one originally used by print_table(), but has additional, required methods. You must map the old $table object to the new html_table object, as demonstrated above and in lib/deprecatedlib.php (see old print_table function).

=== print_textarea (55) ===
=== print_textfield (0) ===

=== print_time_selector (0) ===

=== print_user_picture (0) ===

Old code:
<code php>
print_user_picture($user, $courseid, $picture, $size, $return, $link, $target, $alttext);
</code>
New code (simple):
<code php>
$userpic = new moodle_user_picture();
$userpic->user = $user;
$userpic->courseid = $courseid;
echo $OUTPUT->user_picture($userpic);
</code>
New code (complex: alternate text, size, different image and popup action):
<code php>
$userpic = new user_picture();
$userpic->user = $user;
$userpic->courseid = $courseid;
$userpic->size = $size;
$userpic->link = $link;
$userpic->alttext = $alttext;
$userpic->image->src = $picture;
$userpic->add_action(new popup_action('click', new moodle_url($target)));

echo $OUTPUT->user_picture($userpic);
</code>

=== update_course_button (0) ===

=== update_module_button (94) ===
Old code:
<code php>
$button = update_module_button($cm->id, $course->id, get_string('modulename', 'workshop')); // passed to print_header_simple()
</code>
New code:
<code php>
$PAGE->set_button($OUTPUT->update_module_button($cm->id, 'workshop'));
</code>
Note: $courseid param has been dropped.

=== update_tag_button (0) ===

== Non-supported functions ==
These functions have been completely dropped in 2.0, most likely because they were used very little or not at all. All calls to these functions in core should have been replaced.
=== blocks_print_group ===
=== print_file_picture ===
=== print_png ===
=== print_scale_menu ===
=== print_side_block_end ===
=== print_side_block_start ===
=== print_timer_selector ===
=== print_user ===
=== update_categories_search_button ===
=== update_mymoodle_icon ===

==See also==

* [[Developement:How_Moodle_outputs_HTML]]
* [[Development:Migrating your code to the 2.0 rendering_API]]

{{CategoryDeveloper}}

Development:Deprecated functions in 2.0

2009-08-20T08:58:53Z

Nicolasconnault: /* formerr (120) */

{{Work in progress}}
{{Moodle 2.0}}

This page lists the old HTML-outputting functions of pre-2.0 lib/weblib.php and their 2.0 equivalents using $OUTPUT functions.

== General notes ==
The principle of the new rendering API is to let the developer build metadata-rich components that ''represent'' HTML elements, but may be rendered in many different ways. A menu component, for example, could be rendered as a <select> element, or as a list of radio buttons or check boxes.

The following functions have been arranged in alphabetical order, although some of them are very closely related to each other. The number of occurrences of these function calls at the time of writing are indicated in parentheses.

== Functions to migrate ==
=== button_to_popup_window (0) ===
Old code:
<code php>
button_to_popup_window($url, $name, $linkname, $height, $width, $title, $options, $return, $id, $class);
</code>
New code:
<code php>
$form = new html_form();
$form->button->text = $linkname;
$form->button->title = $title;
$form->button->id = $id;
$form->url = $url;
$form->add_class($class);
$form->button->add_action(new popup_action('click', $url, $name, $options));
echo $OUTPUT->button($form);
</code>
Note: popup parameters ($options) '''must''' be prepared as an associative array, not a string as previously. Simply reusing the $options param previously passed to button_to_popup_window() will not work. The $height and $width params are also part of the popup params. See lib/deprecatedlib.php for an example of how the legacy function call is handled.

=== choose_from_menu (1) ===
Old code:
<code php>
choose_from_menu($options, $name, $selected, $nothing, $script, $nothingvalue, $return, $disabled, $tabindex, $id, $listbox, $multiple, $class);
</code>
New code:
<code php>
$select = moodle_select::make($options, $name, $selected); // Required
$select->nothinglabel = $nothing;
$select->nothingvalue = $nothingvalue;
$select->disabled = $disabled;
$select->tabindex = $tabindex;
$select->id = $id;
$select->listbox = $listbox;
$select->multiple = $multiple;
$select->add_classes($class);

echo $OUTPUT->select($select);
</code>

=== choose_from_menu_nested (0) ===
Old code:
<code php>
choose_from_menu_nested($options, $name, $selected, $nothing, $script, $nothingvalue, $return, $disabled, $tabindex);
</code>
New code:
<code php>
$select = moodle_select::make($options, $name, $selected);
$select->tabindex = $tabindex;
$select->disabled = $disabled;
$select->nothingvalue = $nothingvalue;
$select->nested = true;

echo $OUTPUT->select($select);
</code>
Notes:
#The lang string "choose" is no longer used, in favour of "choosedots".
#The $script param is no longer supported. Please use component::add_action() instead.

=== choose_from_menu_yesno (0) ===
Old code:
<code php>
choose_from_menu_yesno($name, $selected, $script, $return, $disabled, $tabindex);
</code>
New code:
<code php>
$select = moodle_select::make_yes_no($name, $selected);
$select->disabled = $disabled;
$select->tabindex = $tabindex;
echo $OUTPUT->select($select);
</code>
Note: The $script param has been dropped, you need to use component::add_action() instead.

=== choose_from_radio (0) ===

=== close_window_button (0) ===
Old code:
<code php>
close_window_button($name, $return, $reloadopener);
</code>
New code:
<code php>
echo $OUTPUT->close_window_button(get_string($name));
</code>
Note: You must pass a language string already processed by get_string().

=== print_continue (0) ===
Old code:
<code php>
print_continue($link, $return);
</code>
New code:
<code php>
echo $OUTPUT->continue_button($link);
</code>

=== doc_link (0) ===
Old code:
<code php>
doc_link($path, $text, $iconpath);
</code>
New code:
<code php>
echo $OUTPUT->doc_link($path, $text, $iconpath);
</code>
Note: This is not for general use, do not confuse with help_icon()

=== formerr (0) ===
Old code:
<code php>
formerr($string);
</code>
New code:
<code php>
echo $OUTPUT->error_text($error);
</code>

=== helpbutton (0) ===
Old code:
<code php>
helpbutton($page, $title, $module, $image, $linktext, $text, $return, $imagetext);
</code>
New code:
<code php>
$helpicon = new help_icon();
$helpicon->page = $page; // required
$helpicon->text = $title; // required
$helpicon->module = $module; // defaults to 'moodle'
$helpicon->linktext = $linktext;

echo $OUTPUT->help_icon($helpicon);
</code>

=== link_to_popup_window (54) ===
Old code:
<code php>
link_to_popup_window($url, $name, $linkname, $height, $width, $title, $options, $return);
</code>
New code:
<code php>
$link = html_link::make($url, $linkname);
$link->add_action(new popup_action('click', $url, $name, $options));
echo $OUTPUT->link_to_popup($link);
</code>
Note: popup parameters ($options) '''must''' be prepared as an associative array, not a string as previously. Simply reusing the $options param previously passed to link_to_popup_window() will not work. See lib/deprecatedlib.php for an example of how the legacy function call is handled.

=== notice_yesno (0) ===
Old code:
<code php>
notice_yesno($message, $linkyes, $linkno, $optionsyes, $optionsno, $methodyes, $methodno);
</code>
New code (simplest form):
<code php>
echo $OUTPUT->confirm($message, $linkyes, $linkno);
</code>

New code (with options in arrays):
<code php>
echo $OUTPUT->confirm($message, new moodle_url($linkyes, $optionsyes), new moodle_url($linkno, $optionsno));
</code>

New code (if the "get" method is required):
<code php>
$formcontinue = html_form::make_button($linkyes, $optionsyes, get_string('yes'), $methodyes);
$formcancel = html_form::make_button($linkno, $optionsno, get_string('no'), $methodno);
echo $OUTPUT->confirm($message, $formcontinue, $formcancel);
</code>

=== notify (0) ===
Old code:
<code php>
notify($message, $classes, $align, $return);
</code>
New code:
<code php>
echo $OUTPUT->notification($message, $classes='');
</code>
Note: Use a CSS rule for alignment.

=== popup_form (0) ===
Old code:
<code php>
popup_form($baseurl, $options, $formid, $selected, $nothing, $help, $helptext, $return, $targetwindow, $selectlabel, $optionsextra, $submitvalue, $disabled, $showbutton);
</code>
New code:
<code php>
// if $baseurl == 'http://domain.com/index.php?var1=1&var2='
$select = html_select::make_popup_form('http://domain.com/index.php?var1=1', 'var2', $options, $formid, $selected);
$select->disabled = $disabled; // optional
$select->set_label($selectlabel, $select->id); // optional, set to false if no "nothing" option is desired (when $selectlabel == '' in original call)
$select->set_help_icon($help, $helptext); // optional
$select->form->button->text = $submitvalue; // optional

echo $OUTPUT->select($select);
</code>
Notes:
*The $optionsextra param is not supported. If your code uses it, you should find another way to add extra params to your <option> tags without using this horrible hack which usually includes inline JS or CSS.

=== print_arrow (15) ===
=== print_box* (0) ===
Old code:
<code php>
print_box($message, $classes, $ids, $return);
print_box_start($classes, $ids, $return);
print_box_end();
</code>
New code:
<code php>
echo $OUTPUT->box($message, $classes, $ids);
echo $OUTPUT->box_start($classes, $ids);
echo $OUTPUT->box_end();
</code>

=== print_checkbox (10) ===
Old code:
<code php>
print_checkbox($name, $value, $checked, $label, $alt, $script, $return);
</code>
New code:
<code php>
$checkbox = new html_select_option();
$checkbox->value = $value; // Required
$checkbox->selected = $checked;
$checkbox->text = $label;
$checkbox->label->text = $label;
$checkbox->alt = $alt;

echo $OUTPUT->checkbox($checkbox, $name);
</code>
Note: html_select_option is a component that can be rendered as a select <option>, a radio button or a checkbox. It holds sufficient information to render all these elements, except the $name variable which is attached to a moodle_select component. This is why we pass the $name string to $OUTPUT->checkbox().

=== print_container (0) ===
Old code:
<code php>
print_container($message, $clearfix, $classes, $idbase, $return);
</code>
New code:
<code php>
if ($clearfix) {
$classes .= ' clearfix';
}
echo $OUTPUT->container($message, $classes, $idbase);
</code>

=== print_date_selector (0) ===

=== print_footer (0) ===
Old code:
<code php>
print_footer($course, $usercourse, $return);
</code>
New code:
<code php>
echo $OUTPUT->footer();
</code>
Notes: No parameters are required.

=== print_header (501) ===
Old code:
<code php>
print_header($title, $heading, $navigation, $focus, $meta, $cache, $button, $menu, $usexml, $bodytags, $return);
</code>
New code:
<code php>
$PAGE->set_heading($heading); // Required
$PAGE->set_title($title);
$PAGE->set_cacheable($cache);
$PAGE->set_focuscontrol($focus);
$PAGE->set_button($button);
echo $OUTPUT->header($navigation, $menu);
</code>
Note: Navigation code is being rewritten, this doc will then be updated with the new usage.

=== print_heading_with_help (0) ===

=== print_heading (0) ===
Old code:
<code php>
print_heading($text, $align, $size, $class, $return, $id);
</code>
New code:
<code php>
echo $OUTPUT->heading($text, $size, $class, $id);
</code>
Note: Use a CSS class rule to control alignment.

=== print_heading_block (0) ===

=== print_headline (0) ===
Old code:
<code php>
print_headline($text, $size);
</code>
New code:
<code php>
echo $OUTPUT->heading($text, $size);
</code>

=== print_paging_bar (2) ===

Old code:
<code php>
print_paging_bar($totalcount, $page, $perpage, $baseurl, $pagevar, $nocurr, $return);
</code>
New code:
<code php>
$pagingbar = new moodle_paging_bar();
$pagingbar->totalcount = $totalcount; // Required
$pagingbar->page = $page; // Required
$pagingbar->perpage = $perpage; // Required
$pagingbar->baseurl = $baseurl; // Required
$pagingbar->pagevar = $pagevar;
$pagingbar->nocurr = $nocurr;
echo $OUTPUT->paging_bar($pagingbar);
</code>
Note: The last two instances of print_paging_bar are found in the old tablelib, which will soon be deprecated.

=== print_scale_menu_helpbutton (0) ===
Old code:
<code php>
print_scale_menu_helpbutton($courseid, $scale);
</code>
New code:
<code php>
echo $OUTPUT->help_button(help_button::make_scale_menu($courseid, $scale));
</code>

=== print_side_block (4) ===
=== print_single_button (0) ===
Old code:
<code php>
print_single_button($link, $options, $label, $method, $notusedanymore, $return, $tooltip, $disabled, $jsconfirmmessage, $formid)
</code>
New code:
<code php>
$form = new html_form();
$form->url = new moodle_url($link, $options); // Required
$form->button = new html_button();
$form->button->text = $label; // Required
$form->button->disabled = $disabled;
$form->button->title = $tooltip;
$form->method = $method;
$form->id = $formid;

if ($jsconfirmmessage) {
$confirmaction = new component_action('click', 'confirm_dialog', array('message' => $jsconfirmmessage));
$form->button->add_action($confirmaction);
}

$output = $OUTPUT->button($form);
</code>

=== print_spacer (0) ===
Old code:
<code php>
print_spacer($height, $width, $br, $return);
</code>
New code:
<code php>
$spacer = new html_image();
$spacer->height = $height;
$spacer->width = $width;
echo $OUTPUT->spacer($spacer);
</code>
Note: The $br attribute has been dropped. You can simply add a line break manually if you need one.

=== print_table (0) ===
Old code:
<code php>
$table = new stdClass();
$table->class = 'mytable';
$table->head = array('Firstname', 'Lastname');
$table->rowclasses = array();
// (other table properties here)
$table->data = array(array(...),array(...),array(...));
print_table($table, $return);
</code>
New code:
<code php>
$table = new html_table();
$table->set_classes('mytable'); // note the new style of setting CSS class
$table->head = array('First name', 'Last name');
$table->colclasses = array('name fname','name lname');
$table->rowclasses = array();
// (other table properties here)
$table->data = array(array(...),array(...),array(...));
echo $OUTPUT->table($newtable);
</code>
Notes: The new html_table object has the same member variables as the one originally used by print_table(), but has additional, required methods. You must map the old $table object to the new html_table object, as demonstrated above and in lib/deprecatedlib.php (see old print_table function).

=== print_textarea (55) ===
=== print_textfield (0) ===

=== print_time_selector (0) ===

=== print_user_picture (0) ===

Old code:
<code php>
print_user_picture($user, $courseid, $picture, $size, $return, $link, $target, $alttext);
</code>
New code (simple):
<code php>
$userpic = new moodle_user_picture();
$userpic->user = $user;
$userpic->courseid = $courseid;
echo $OUTPUT->user_picture($userpic);
</code>
New code (complex: alternate text, size, different image and popup action):
<code php>
$userpic = new user_picture();
$userpic->user = $user;
$userpic->courseid = $courseid;
$userpic->size = $size;
$userpic->link = $link;
$userpic->alttext = $alttext;
$userpic->image->src = $picture;
$userpic->add_action(new popup_action('click', new moodle_url($target)));

echo $OUTPUT->user_picture($userpic);
</code>

=== update_course_button (0) ===

=== update_module_button (94) ===
Old code:
<code php>
$button = update_module_button($cm->id, $course->id, get_string('modulename', 'workshop')); // passed to print_header_simple()
</code>
New code:
<code php>
$PAGE->set_button($OUTPUT->update_module_button($cm->id, 'workshop'));
</code>
Note: $courseid param has been dropped.

=== update_tag_button (0) ===

== Non-supported functions ==
These functions have been completely dropped in 2.0, most likely because they were used very little or not at all. All calls to these functions in core should have been replaced.
=== blocks_print_group ===
=== print_file_picture ===
=== print_png ===
=== print_scale_menu ===
=== print_side_block_end ===
=== print_side_block_start ===
=== print_timer_selector ===
=== print_user ===
=== update_categories_search_button ===
=== update_mymoodle_icon ===

==See also==

* [[Developement:How_Moodle_outputs_HTML]]
* [[Development:Migrating your code to the 2.0 rendering_API]]

{{CategoryDeveloper}}

Development:Deprecated functions in 2.0

2009-08-20T08:53:38Z

Nicolasconnault: /* print_table (140) */

{{Work in progress}}
{{Moodle 2.0}}

This page lists the old HTML-outputting functions of pre-2.0 lib/weblib.php and their 2.0 equivalents using $OUTPUT functions.

== General notes ==
The principle of the new rendering API is to let the developer build metadata-rich components that ''represent'' HTML elements, but may be rendered in many different ways. A menu component, for example, could be rendered as a <select> element, or as a list of radio buttons or check boxes.

The following functions have been arranged in alphabetical order, although some of them are very closely related to each other. The number of occurrences of these function calls at the time of writing are indicated in parentheses.

== Functions to migrate ==
=== button_to_popup_window (0) ===
Old code:
<code php>
button_to_popup_window($url, $name, $linkname, $height, $width, $title, $options, $return, $id, $class);
</code>
New code:
<code php>
$form = new html_form();
$form->button->text = $linkname;
$form->button->title = $title;
$form->button->id = $id;
$form->url = $url;
$form->add_class($class);
$form->button->add_action(new popup_action('click', $url, $name, $options));
echo $OUTPUT->button($form);
</code>
Note: popup parameters ($options) '''must''' be prepared as an associative array, not a string as previously. Simply reusing the $options param previously passed to button_to_popup_window() will not work. The $height and $width params are also part of the popup params. See lib/deprecatedlib.php for an example of how the legacy function call is handled.

=== choose_from_menu (1) ===
Old code:
<code php>
choose_from_menu($options, $name, $selected, $nothing, $script, $nothingvalue, $return, $disabled, $tabindex, $id, $listbox, $multiple, $class);
</code>
New code:
<code php>
$select = moodle_select::make($options, $name, $selected); // Required
$select->nothinglabel = $nothing;
$select->nothingvalue = $nothingvalue;
$select->disabled = $disabled;
$select->tabindex = $tabindex;
$select->id = $id;
$select->listbox = $listbox;
$select->multiple = $multiple;
$select->add_classes($class);

echo $OUTPUT->select($select);
</code>

=== choose_from_menu_nested (0) ===
Old code:
<code php>
choose_from_menu_nested($options, $name, $selected, $nothing, $script, $nothingvalue, $return, $disabled, $tabindex);
</code>
New code:
<code php>
$select = moodle_select::make($options, $name, $selected);
$select->tabindex = $tabindex;
$select->disabled = $disabled;
$select->nothingvalue = $nothingvalue;
$select->nested = true;

echo $OUTPUT->select($select);
</code>
Notes:
#The lang string "choose" is no longer used, in favour of "choosedots".
#The $script param is no longer supported. Please use component::add_action() instead.

=== choose_from_menu_yesno (0) ===
Old code:
<code php>
choose_from_menu_yesno($name, $selected, $script, $return, $disabled, $tabindex);
</code>
New code:
<code php>
$select = moodle_select::make_yes_no($name, $selected);
$select->disabled = $disabled;
$select->tabindex = $tabindex;
echo $OUTPUT->select($select);
</code>
Note: The $script param has been dropped, you need to use component::add_action() instead.

=== choose_from_radio (0) ===

=== close_window_button (0) ===
Old code:
<code php>
close_window_button($name, $return, $reloadopener);
</code>
New code:
<code php>
echo $OUTPUT->close_window_button(get_string($name));
</code>
Note: You must pass a language string already processed by get_string().

=== print_continue (0) ===
Old code:
<code php>
print_continue($link, $return);
</code>
New code:
<code php>
echo $OUTPUT->continue_button($link);
</code>

=== doc_link (0) ===
Old code:
<code php>
doc_link($path, $text, $iconpath);
</code>
New code:
<code php>
echo $OUTPUT->doc_link($path, $text, $iconpath);
</code>
Note: This is not for general use, do not confuse with help_icon()

=== formerr (120) ===
Old code:
<code php>
formerr($string);
</code>
New code:
<code php>
echo $OUTPUT->error_text($error);
</code>

=== helpbutton (0) ===
Old code:
<code php>
helpbutton($page, $title, $module, $image, $linktext, $text, $return, $imagetext);
</code>
New code:
<code php>
$helpicon = new help_icon();
$helpicon->page = $page; // required
$helpicon->text = $title; // required
$helpicon->module = $module; // defaults to 'moodle'
$helpicon->linktext = $linktext;

echo $OUTPUT->help_icon($helpicon);
</code>

=== link_to_popup_window (54) ===
Old code:
<code php>
link_to_popup_window($url, $name, $linkname, $height, $width, $title, $options, $return);
</code>
New code:
<code php>
$link = html_link::make($url, $linkname);
$link->add_action(new popup_action('click', $url, $name, $options));
echo $OUTPUT->link_to_popup($link);
</code>
Note: popup parameters ($options) '''must''' be prepared as an associative array, not a string as previously. Simply reusing the $options param previously passed to link_to_popup_window() will not work. See lib/deprecatedlib.php for an example of how the legacy function call is handled.

=== notice_yesno (0) ===
Old code:
<code php>
notice_yesno($message, $linkyes, $linkno, $optionsyes, $optionsno, $methodyes, $methodno);
</code>
New code (simplest form):
<code php>
echo $OUTPUT->confirm($message, $linkyes, $linkno);
</code>

New code (with options in arrays):
<code php>
echo $OUTPUT->confirm($message, new moodle_url($linkyes, $optionsyes), new moodle_url($linkno, $optionsno));
</code>

New code (if the "get" method is required):
<code php>
$formcontinue = html_form::make_button($linkyes, $optionsyes, get_string('yes'), $methodyes);
$formcancel = html_form::make_button($linkno, $optionsno, get_string('no'), $methodno);
echo $OUTPUT->confirm($message, $formcontinue, $formcancel);
</code>

=== notify (0) ===
Old code:
<code php>
notify($message, $classes, $align, $return);
</code>
New code:
<code php>
echo $OUTPUT->notification($message, $classes='');
</code>
Note: Use a CSS rule for alignment.

=== popup_form (0) ===
Old code:
<code php>
popup_form($baseurl, $options, $formid, $selected, $nothing, $help, $helptext, $return, $targetwindow, $selectlabel, $optionsextra, $submitvalue, $disabled, $showbutton);
</code>
New code:
<code php>
// if $baseurl == 'http://domain.com/index.php?var1=1&var2='
$select = html_select::make_popup_form('http://domain.com/index.php?var1=1', 'var2', $options, $formid, $selected);
$select->disabled = $disabled; // optional
$select->set_label($selectlabel, $select->id); // optional, set to false if no "nothing" option is desired (when $selectlabel == '' in original call)
$select->set_help_icon($help, $helptext); // optional
$select->form->button->text = $submitvalue; // optional

echo $OUTPUT->select($select);
</code>
Notes:
*The $optionsextra param is not supported. If your code uses it, you should find another way to add extra params to your <option> tags without using this horrible hack which usually includes inline JS or CSS.

=== print_arrow (15) ===
=== print_box* (0) ===
Old code:
<code php>
print_box($message, $classes, $ids, $return);
print_box_start($classes, $ids, $return);
print_box_end();
</code>
New code:
<code php>
echo $OUTPUT->box($message, $classes, $ids);
echo $OUTPUT->box_start($classes, $ids);
echo $OUTPUT->box_end();
</code>

=== print_checkbox (10) ===
Old code:
<code php>
print_checkbox($name, $value, $checked, $label, $alt, $script, $return);
</code>
New code:
<code php>
$checkbox = new html_select_option();
$checkbox->value = $value; // Required
$checkbox->selected = $checked;
$checkbox->text = $label;
$checkbox->label->text = $label;
$checkbox->alt = $alt;

echo $OUTPUT->checkbox($checkbox, $name);
</code>
Note: html_select_option is a component that can be rendered as a select <option>, a radio button or a checkbox. It holds sufficient information to render all these elements, except the $name variable which is attached to a moodle_select component. This is why we pass the $name string to $OUTPUT->checkbox().

=== print_container (0) ===
Old code:
<code php>
print_container($message, $clearfix, $classes, $idbase, $return);
</code>
New code:
<code php>
if ($clearfix) {
$classes .= ' clearfix';
}
echo $OUTPUT->container($message, $classes, $idbase);
</code>

=== print_date_selector (0) ===

=== print_footer (0) ===
Old code:
<code php>
print_footer($course, $usercourse, $return);
</code>
New code:
<code php>
echo $OUTPUT->footer();
</code>
Notes: No parameters are required.

=== print_header (501) ===
Old code:
<code php>
print_header($title, $heading, $navigation, $focus, $meta, $cache, $button, $menu, $usexml, $bodytags, $return);
</code>
New code:
<code php>
$PAGE->set_heading($heading); // Required
$PAGE->set_title($title);
$PAGE->set_cacheable($cache);
$PAGE->set_focuscontrol($focus);
$PAGE->set_button($button);
echo $OUTPUT->header($navigation, $menu);
</code>
Note: Navigation code is being rewritten, this doc will then be updated with the new usage.

=== print_heading_with_help (0) ===

=== print_heading (0) ===
Old code:
<code php>
print_heading($text, $align, $size, $class, $return, $id);
</code>
New code:
<code php>
echo $OUTPUT->heading($text, $size, $class, $id);
</code>
Note: Use a CSS class rule to control alignment.

=== print_heading_block (0) ===

=== print_headline (0) ===
Old code:
<code php>
print_headline($text, $size);
</code>
New code:
<code php>
echo $OUTPUT->heading($text, $size);
</code>

=== print_paging_bar (2) ===

Old code:
<code php>
print_paging_bar($totalcount, $page, $perpage, $baseurl, $pagevar, $nocurr, $return);
</code>
New code:
<code php>
$pagingbar = new moodle_paging_bar();
$pagingbar->totalcount = $totalcount; // Required
$pagingbar->page = $page; // Required
$pagingbar->perpage = $perpage; // Required
$pagingbar->baseurl = $baseurl; // Required
$pagingbar->pagevar = $pagevar;
$pagingbar->nocurr = $nocurr;
echo $OUTPUT->paging_bar($pagingbar);
</code>
Note: The last two instances of print_paging_bar are found in the old tablelib, which will soon be deprecated.

=== print_scale_menu_helpbutton (0) ===
Old code:
<code php>
print_scale_menu_helpbutton($courseid, $scale);
</code>
New code:
<code php>
echo $OUTPUT->help_button(help_button::make_scale_menu($courseid, $scale));
</code>

=== print_side_block (4) ===
=== print_single_button (0) ===
Old code:
<code php>
print_single_button($link, $options, $label, $method, $notusedanymore, $return, $tooltip, $disabled, $jsconfirmmessage, $formid)
</code>
New code:
<code php>
$form = new html_form();
$form->url = new moodle_url($link, $options); // Required
$form->button = new html_button();
$form->button->text = $label; // Required
$form->button->disabled = $disabled;
$form->button->title = $tooltip;
$form->method = $method;
$form->id = $formid;

if ($jsconfirmmessage) {
$confirmaction = new component_action('click', 'confirm_dialog', array('message' => $jsconfirmmessage));
$form->button->add_action($confirmaction);
}

$output = $OUTPUT->button($form);
</code>

=== print_spacer (0) ===
Old code:
<code php>
print_spacer($height, $width, $br, $return);
</code>
New code:
<code php>
$spacer = new html_image();
$spacer->height = $height;
$spacer->width = $width;
echo $OUTPUT->spacer($spacer);
</code>
Note: The $br attribute has been dropped. You can simply add a line break manually if you need one.

=== print_table (0) ===
Old code:
<code php>
$table = new stdClass();
$table->class = 'mytable';
$table->head = array('Firstname', 'Lastname');
$table->rowclasses = array();
// (other table properties here)
$table->data = array(array(...),array(...),array(...));
print_table($table, $return);
</code>
New code:
<code php>
$table = new html_table();
$table->set_classes('mytable'); // note the new style of setting CSS class
$table->head = array('First name', 'Last name');
$table->colclasses = array('name fname','name lname');
$table->rowclasses = array();
// (other table properties here)
$table->data = array(array(...),array(...),array(...));
echo $OUTPUT->table($newtable);
</code>
Notes: The new html_table object has the same member variables as the one originally used by print_table(), but has additional, required methods. You must map the old $table object to the new html_table object, as demonstrated above and in lib/deprecatedlib.php (see old print_table function).

=== print_textarea (55) ===
=== print_textfield (0) ===

=== print_time_selector (0) ===

=== print_user_picture (0) ===

Old code:
<code php>
print_user_picture($user, $courseid, $picture, $size, $return, $link, $target, $alttext);
</code>
New code (simple):
<code php>
$userpic = new moodle_user_picture();
$userpic->user = $user;
$userpic->courseid = $courseid;
echo $OUTPUT->user_picture($userpic);
</code>
New code (complex: alternate text, size, different image and popup action):
<code php>
$userpic = new user_picture();
$userpic->user = $user;
$userpic->courseid = $courseid;
$userpic->size = $size;
$userpic->link = $link;
$userpic->alttext = $alttext;
$userpic->image->src = $picture;
$userpic->add_action(new popup_action('click', new moodle_url($target)));

echo $OUTPUT->user_picture($userpic);
</code>

=== update_course_button (0) ===

=== update_module_button (94) ===
Old code:
<code php>
$button = update_module_button($cm->id, $course->id, get_string('modulename', 'workshop')); // passed to print_header_simple()
</code>
New code:
<code php>
$PAGE->set_button($OUTPUT->update_module_button($cm->id, 'workshop'));
</code>
Note: $courseid param has been dropped.

=== update_tag_button (0) ===

== Non-supported functions ==
These functions have been completely dropped in 2.0, most likely because they were used very little or not at all. All calls to these functions in core should have been replaced.
=== blocks_print_group ===
=== print_file_picture ===
=== print_png ===
=== print_scale_menu ===
=== print_side_block_end ===
=== print_side_block_start ===
=== print_timer_selector ===
=== print_user ===
=== update_categories_search_button ===
=== update_mymoodle_icon ===

==See also==

* [[Developement:How_Moodle_outputs_HTML]]
* [[Development:Migrating your code to the 2.0 rendering_API]]

{{CategoryDeveloper}}

Development:Deprecated functions in 2.0

2009-08-20T06:33:14Z

Nicolasconnault: /* notice_yesno (79) */

{{Work in progress}}
{{Moodle 2.0}}

This page lists the old HTML-outputting functions of pre-2.0 lib/weblib.php and their 2.0 equivalents using $OUTPUT functions.

== General notes ==
The principle of the new rendering API is to let the developer build metadata-rich components that ''represent'' HTML elements, but may be rendered in many different ways. A menu component, for example, could be rendered as a <select> element, or as a list of radio buttons or check boxes.

The following functions have been arranged in alphabetical order, although some of them are very closely related to each other. The number of occurrences of these function calls at the time of writing are indicated in parentheses.

== Functions to migrate ==
=== button_to_popup_window (0) ===
Old code:
<code php>
button_to_popup_window($url, $name, $linkname, $height, $width, $title, $options, $return, $id, $class);
</code>
New code:
<code php>
$form = new html_form();
$form->button->text = $linkname;
$form->button->title = $title;
$form->button->id = $id;
$form->url = $url;
$form->add_class($class);
$form->button->add_action(new popup_action('click', $url, $name, $options));
echo $OUTPUT->button($form);
</code>
Note: popup parameters ($options) '''must''' be prepared as an associative array, not a string as previously. Simply reusing the $options param previously passed to button_to_popup_window() will not work. The $height and $width params are also part of the popup params. See lib/deprecatedlib.php for an example of how the legacy function call is handled.

=== choose_from_menu (1) ===
Old code:
<code php>
choose_from_menu($options, $name, $selected, $nothing, $script, $nothingvalue, $return, $disabled, $tabindex, $id, $listbox, $multiple, $class);
</code>
New code:
<code php>
$select = moodle_select::make($options, $name, $selected); // Required
$select->nothinglabel = $nothing;
$select->nothingvalue = $nothingvalue;
$select->disabled = $disabled;
$select->tabindex = $tabindex;
$select->id = $id;
$select->listbox = $listbox;
$select->multiple = $multiple;
$select->add_classes($class);

echo $OUTPUT->select($select);
</code>

=== choose_from_menu_nested (0) ===
Old code:
<code php>
choose_from_menu_nested($options, $name, $selected, $nothing, $script, $nothingvalue, $return, $disabled, $tabindex);
</code>
New code:
<code php>
$select = moodle_select::make($options, $name, $selected);
$select->tabindex = $tabindex;
$select->disabled = $disabled;
$select->nothingvalue = $nothingvalue;
$select->nested = true;

echo $OUTPUT->select($select);
</code>
Notes:
#The lang string "choose" is no longer used, in favour of "choosedots".
#The $script param is no longer supported. Please use component::add_action() instead.

=== choose_from_menu_yesno (0) ===
Old code:
<code php>
choose_from_menu_yesno($name, $selected, $script, $return, $disabled, $tabindex);
</code>
New code:
<code php>
$select = moodle_select::make_yes_no($name, $selected);
$select->disabled = $disabled;
$select->tabindex = $tabindex;
echo $OUTPUT->select($select);
</code>
Note: The $script param has been dropped, you need to use component::add_action() instead.

=== choose_from_radio (0) ===

=== close_window_button (0) ===
Old code:
<code php>
close_window_button($name, $return, $reloadopener);
</code>
New code:
<code php>
echo $OUTPUT->close_window_button(get_string($name));
</code>
Note: You must pass a language string already processed by get_string().

=== print_continue (0) ===
Old code:
<code php>
print_continue($link, $return);
</code>
New code:
<code php>
echo $OUTPUT->continue_button($link);
</code>

=== doc_link (0) ===
Old code:
<code php>
doc_link($path, $text, $iconpath);
</code>
New code:
<code php>
echo $OUTPUT->doc_link($path, $text, $iconpath);
</code>
Note: This is not for general use, do not confuse with help_icon()

=== formerr (120) ===
Old code:
<code php>
formerr($string);
</code>
New code:
<code php>
echo $OUTPUT->error_text($error);
</code>

=== helpbutton (0) ===
Old code:
<code php>
helpbutton($page, $title, $module, $image, $linktext, $text, $return, $imagetext);
</code>
New code:
<code php>
$helpicon = new help_icon();
$helpicon->page = $page; // required
$helpicon->text = $title; // required
$helpicon->module = $module; // defaults to 'moodle'
$helpicon->linktext = $linktext;

echo $OUTPUT->help_icon($helpicon);
</code>

=== link_to_popup_window (54) ===
Old code:
<code php>
link_to_popup_window($url, $name, $linkname, $height, $width, $title, $options, $return);
</code>
New code:
<code php>
$link = html_link::make($url, $linkname);
$link->add_action(new popup_action('click', $url, $name, $options));
echo $OUTPUT->link_to_popup($link);
</code>
Note: popup parameters ($options) '''must''' be prepared as an associative array, not a string as previously. Simply reusing the $options param previously passed to link_to_popup_window() will not work. See lib/deprecatedlib.php for an example of how the legacy function call is handled.

=== notice_yesno (0) ===
Old code:
<code php>
notice_yesno($message, $linkyes, $linkno, $optionsyes, $optionsno, $methodyes, $methodno);
</code>
New code (simplest form):
<code php>
echo $OUTPUT->confirm($message, $linkyes, $linkno);
</code>

New code (with options in arrays):
<code php>
echo $OUTPUT->confirm($message, new moodle_url($linkyes, $optionsyes), new moodle_url($linkno, $optionsno));
</code>

New code (if the "get" method is required):
<code php>
$formcontinue = html_form::make_button($linkyes, $optionsyes, get_string('yes'), $methodyes);
$formcancel = html_form::make_button($linkno, $optionsno, get_string('no'), $methodno);
echo $OUTPUT->confirm($message, $formcontinue, $formcancel);
</code>

=== notify (0) ===
Old code:
<code php>
notify($message, $classes, $align, $return);
</code>
New code:
<code php>
echo $OUTPUT->notification($message, $classes='');
</code>
Note: Use a CSS rule for alignment.

=== popup_form (0) ===
Old code:
<code php>
popup_form($baseurl, $options, $formid, $selected, $nothing, $help, $helptext, $return, $targetwindow, $selectlabel, $optionsextra, $submitvalue, $disabled, $showbutton);
</code>
New code:
<code php>
// if $baseurl == 'http://domain.com/index.php?var1=1&var2='
$select = html_select::make_popup_form('http://domain.com/index.php?var1=1', 'var2', $options, $formid, $selected);
$select->disabled = $disabled; // optional
$select->set_label($selectlabel, $select->id); // optional, set to false if no "nothing" option is desired (when $selectlabel == '' in original call)
$select->set_help_icon($help, $helptext); // optional
$select->form->button->text = $submitvalue; // optional

echo $OUTPUT->select($select);
</code>
Notes:
*The $optionsextra param is not supported. If your code uses it, you should find another way to add extra params to your <option> tags without using this horrible hack which usually includes inline JS or CSS.

=== print_arrow (15) ===
=== print_box* (0) ===
Old code:
<code php>
print_box($message, $classes, $ids, $return);
print_box_start($classes, $ids, $return);
print_box_end();
</code>
New code:
<code php>
echo $OUTPUT->box($message, $classes, $ids);
echo $OUTPUT->box_start($classes, $ids);
echo $OUTPUT->box_end();
</code>

=== print_checkbox (10) ===
Old code:
<code php>
print_checkbox($name, $value, $checked, $label, $alt, $script, $return);
</code>
New code:
<code php>
$checkbox = new html_select_option();
$checkbox->value = $value; // Required
$checkbox->selected = $checked;
$checkbox->text = $label;
$checkbox->label->text = $label;
$checkbox->alt = $alt;

echo $OUTPUT->checkbox($checkbox, $name);
</code>
Note: html_select_option is a component that can be rendered as a select <option>, a radio button or a checkbox. It holds sufficient information to render all these elements, except the $name variable which is attached to a moodle_select component. This is why we pass the $name string to $OUTPUT->checkbox().

=== print_container (0) ===
Old code:
<code php>
print_container($message, $clearfix, $classes, $idbase, $return);
</code>
New code:
<code php>
if ($clearfix) {
$classes .= ' clearfix';
}
echo $OUTPUT->container($message, $classes, $idbase);
</code>

=== print_date_selector (0) ===

=== print_footer (0) ===
Old code:
<code php>
print_footer($course, $usercourse, $return);
</code>
New code:
<code php>
echo $OUTPUT->footer();
</code>
Notes: No parameters are required.

=== print_header (501) ===
Old code:
<code php>
print_header($title, $heading, $navigation, $focus, $meta, $cache, $button, $menu, $usexml, $bodytags, $return);
</code>
New code:
<code php>
$PAGE->set_heading($heading); // Required
$PAGE->set_title($title);
$PAGE->set_cacheable($cache);
$PAGE->set_focuscontrol($focus);
$PAGE->set_button($button);
echo $OUTPUT->header($navigation, $menu);
</code>
Note: Navigation code is being rewritten, this doc will then be updated with the new usage.

=== print_heading_with_help (0) ===

=== print_heading (0) ===
Old code:
<code php>
print_heading($text, $align, $size, $class, $return, $id);
</code>
New code:
<code php>
echo $OUTPUT->heading($text, $size, $class, $id);
</code>
Note: Use a CSS class rule to control alignment.

=== print_heading_block (0) ===

=== print_headline (0) ===
Old code:
<code php>
print_headline($text, $size);
</code>
New code:
<code php>
echo $OUTPUT->heading($text, $size);
</code>

=== print_paging_bar (2) ===

Old code:
<code php>
print_paging_bar($totalcount, $page, $perpage, $baseurl, $pagevar, $nocurr, $return);
</code>
New code:
<code php>
$pagingbar = new moodle_paging_bar();
$pagingbar->totalcount = $totalcount; // Required
$pagingbar->page = $page; // Required
$pagingbar->perpage = $perpage; // Required
$pagingbar->baseurl = $baseurl; // Required
$pagingbar->pagevar = $pagevar;
$pagingbar->nocurr = $nocurr;
echo $OUTPUT->paging_bar($pagingbar);
</code>
Note: The last two instances of print_paging_bar are found in the old tablelib, which will soon be deprecated.

=== print_scale_menu_helpbutton (0) ===
Old code:
<code php>
print_scale_menu_helpbutton($courseid, $scale);
</code>
New code:
<code php>
echo $OUTPUT->help_button(help_button::make_scale_menu($courseid, $scale));
</code>

=== print_side_block (4) ===
=== print_single_button (0) ===
Old code:
<code php>
print_single_button($link, $options, $label, $method, $notusedanymore, $return, $tooltip, $disabled, $jsconfirmmessage, $formid)
</code>
New code:
<code php>
$form = new html_form();
$form->url = new moodle_url($link, $options); // Required
$form->button = new html_button();
$form->button->text = $label; // Required
$form->button->disabled = $disabled;
$form->button->title = $tooltip;
$form->method = $method;
$form->id = $formid;

if ($jsconfirmmessage) {
$confirmaction = new component_action('click', 'confirm_dialog', array('message' => $jsconfirmmessage));
$form->button->add_action($confirmaction);
}

$output = $OUTPUT->button($form);
</code>

=== print_spacer (0) ===
Old code:
<code php>
print_spacer($height, $width, $br, $return);
</code>
New code:
<code php>
$spacer = new html_image();
$spacer->height = $height;
$spacer->width = $width;
echo $OUTPUT->spacer($spacer);
</code>
Note: The $br attribute has been dropped. You can simply add a line break manually if you need one.

=== print_table (140) ===
Old code:
<code php>
$table = new stdClass();
$table->class = 'mytable';
$table->head = array('Firstname', 'Lastname');
$table->rowclass = array();
// (other table properties here)
$table->data = array(array(...),array(...),array(...));
print_table($table, $return);
</code>
New code:
<code php>
$table = new html_table();
$table->set_classes('mytable'); // note the new style of setting CSS class
$table->head = array('First name', 'Last name');
$table->colclasses = array('name fname','name lname');
$table->rowclasses = array(); // note the change of rowclass[] to rowclasses[]
// (other table properties here)
$table->data = array(array(...),array(...),array(...));
echo $OUTPUT->table($newtable);
</code>
Notes: The new html_table object has the same member variables as the one originally used by print_table(), but has additional, required methods. You must map the old $table object to the new html_table object, as demonstrated above and in lib/deprecatedlib.php (see old print_table function).

=== print_textarea (55) ===
=== print_textfield (0) ===

=== print_time_selector (0) ===

=== print_user_picture (0) ===

Old code:
<code php>
print_user_picture($user, $courseid, $picture, $size, $return, $link, $target, $alttext);
</code>
New code (simple):
<code php>
$userpic = new moodle_user_picture();
$userpic->user = $user;
$userpic->courseid = $courseid;
echo $OUTPUT->user_picture($userpic);
</code>
New code (complex: alternate text, size, different image and popup action):
<code php>
$userpic = new user_picture();
$userpic->user = $user;
$userpic->courseid = $courseid;
$userpic->size = $size;
$userpic->link = $link;
$userpic->alttext = $alttext;
$userpic->image->src = $picture;
$userpic->add_action(new popup_action('click', new moodle_url($target)));

echo $OUTPUT->user_picture($userpic);
</code>

=== update_course_button (0) ===

=== update_module_button (94) ===
Old code:
<code php>
$button = update_module_button($cm->id, $course->id, get_string('modulename', 'workshop')); // passed to print_header_simple()
</code>
New code:
<code php>
$PAGE->set_button($OUTPUT->update_module_button($cm->id, 'workshop'));
</code>
Note: $courseid param has been dropped.

=== update_tag_button (0) ===

== Non-supported functions ==
These functions have been completely dropped in 2.0, most likely because they were used very little or not at all. All calls to these functions in core should have been replaced.
=== blocks_print_group ===
=== print_file_picture ===
=== print_png ===
=== print_scale_menu ===
=== print_side_block_end ===
=== print_side_block_start ===
=== print_timer_selector ===
=== print_user ===
=== update_categories_search_button ===
=== update_mymoodle_icon ===

==See also==

* [[Developement:How_Moodle_outputs_HTML]]
* [[Development:Migrating your code to the 2.0 rendering_API]]

{{CategoryDeveloper}}

Development:Deprecated functions in 2.0

2009-08-20T06:31:39Z

Nicolasconnault:

{{Work in progress}}
{{Moodle 2.0}}

This page lists the old HTML-outputting functions of pre-2.0 lib/weblib.php and their 2.0 equivalents using $OUTPUT functions.

== General notes ==
The principle of the new rendering API is to let the developer build metadata-rich components that ''represent'' HTML elements, but may be rendered in many different ways. A menu component, for example, could be rendered as a <select> element, or as a list of radio buttons or check boxes.

The following functions have been arranged in alphabetical order, although some of them are very closely related to each other. The number of occurrences of these function calls at the time of writing are indicated in parentheses.

== Functions to migrate ==
=== button_to_popup_window (0) ===
Old code:
<code php>
button_to_popup_window($url, $name, $linkname, $height, $width, $title, $options, $return, $id, $class);
</code>
New code:
<code php>
$form = new html_form();
$form->button->text = $linkname;
$form->button->title = $title;
$form->button->id = $id;
$form->url = $url;
$form->add_class($class);
$form->button->add_action(new popup_action('click', $url, $name, $options));
echo $OUTPUT->button($form);
</code>
Note: popup parameters ($options) '''must''' be prepared as an associative array, not a string as previously. Simply reusing the $options param previously passed to button_to_popup_window() will not work. The $height and $width params are also part of the popup params. See lib/deprecatedlib.php for an example of how the legacy function call is handled.

=== choose_from_menu (1) ===
Old code:
<code php>
choose_from_menu($options, $name, $selected, $nothing, $script, $nothingvalue, $return, $disabled, $tabindex, $id, $listbox, $multiple, $class);
</code>
New code:
<code php>
$select = moodle_select::make($options, $name, $selected); // Required
$select->nothinglabel = $nothing;
$select->nothingvalue = $nothingvalue;
$select->disabled = $disabled;
$select->tabindex = $tabindex;
$select->id = $id;
$select->listbox = $listbox;
$select->multiple = $multiple;
$select->add_classes($class);

echo $OUTPUT->select($select);
</code>

=== choose_from_menu_nested (0) ===
Old code:
<code php>
choose_from_menu_nested($options, $name, $selected, $nothing, $script, $nothingvalue, $return, $disabled, $tabindex);
</code>
New code:
<code php>
$select = moodle_select::make($options, $name, $selected);
$select->tabindex = $tabindex;
$select->disabled = $disabled;
$select->nothingvalue = $nothingvalue;
$select->nested = true;

echo $OUTPUT->select($select);
</code>
Notes:
#The lang string "choose" is no longer used, in favour of "choosedots".
#The $script param is no longer supported. Please use component::add_action() instead.

=== choose_from_menu_yesno (0) ===
Old code:
<code php>
choose_from_menu_yesno($name, $selected, $script, $return, $disabled, $tabindex);
</code>
New code:
<code php>
$select = moodle_select::make_yes_no($name, $selected);
$select->disabled = $disabled;
$select->tabindex = $tabindex;
echo $OUTPUT->select($select);
</code>
Note: The $script param has been dropped, you need to use component::add_action() instead.

=== choose_from_radio (0) ===

=== close_window_button (0) ===
Old code:
<code php>
close_window_button($name, $return, $reloadopener);
</code>
New code:
<code php>
echo $OUTPUT->close_window_button(get_string($name));
</code>
Note: You must pass a language string already processed by get_string().

=== print_continue (0) ===
Old code:
<code php>
print_continue($link, $return);
</code>
New code:
<code php>
echo $OUTPUT->continue_button($link);
</code>

=== doc_link (0) ===
Old code:
<code php>
doc_link($path, $text, $iconpath);
</code>
New code:
<code php>
echo $OUTPUT->doc_link($path, $text, $iconpath);
</code>
Note: This is not for general use, do not confuse with help_icon()

=== formerr (120) ===
Old code:
<code php>
formerr($string);
</code>
New code:
<code php>
echo $OUTPUT->error_text($error);
</code>

=== helpbutton (0) ===
Old code:
<code php>
helpbutton($page, $title, $module, $image, $linktext, $text, $return, $imagetext);
</code>
New code:
<code php>
$helpicon = new help_icon();
$helpicon->page = $page; // required
$helpicon->text = $title; // required
$helpicon->module = $module; // defaults to 'moodle'
$helpicon->linktext = $linktext;

echo $OUTPUT->help_icon($helpicon);
</code>

=== link_to_popup_window (54) ===
Old code:
<code php>
link_to_popup_window($url, $name, $linkname, $height, $width, $title, $options, $return);
</code>
New code:
<code php>
$link = html_link::make($url, $linkname);
$link->add_action(new popup_action('click', $url, $name, $options));
echo $OUTPUT->link_to_popup($link);
</code>
Note: popup parameters ($options) '''must''' be prepared as an associative array, not a string as previously. Simply reusing the $options param previously passed to link_to_popup_window() will not work. See lib/deprecatedlib.php for an example of how the legacy function call is handled.

=== notice_yesno (79) ===
Old code:
<code php>
notice_yesno($message, $linkyes, $linkno, $optionsyes, $optionsno, $methodyes, $methodno);
</code>
New code (simplest form):
<code php>
echo $OUTPUT->confirm($message, $linkyes, $linkno);
</code>
New code (complex form):
<code php>
$formcontinue = html_form::make_button($linkyes, $optionsyes, get_string('yes'), $methodyes);
$formcancel = html_form::make_button($linkno, $optionsno, get_string('no'), $methodno);
echo $OUTPUT->confirm($message, $formcontinue, $formcancel);
</code>

=== notify (0) ===
Old code:
<code php>
notify($message, $classes, $align, $return);
</code>
New code:
<code php>
echo $OUTPUT->notification($message, $classes='');
</code>
Note: Use a CSS rule for alignment.

=== popup_form (0) ===
Old code:
<code php>
popup_form($baseurl, $options, $formid, $selected, $nothing, $help, $helptext, $return, $targetwindow, $selectlabel, $optionsextra, $submitvalue, $disabled, $showbutton);
</code>
New code:
<code php>
// if $baseurl == 'http://domain.com/index.php?var1=1&var2='
$select = html_select::make_popup_form('http://domain.com/index.php?var1=1', 'var2', $options, $formid, $selected);
$select->disabled = $disabled; // optional
$select->set_label($selectlabel, $select->id); // optional, set to false if no "nothing" option is desired (when $selectlabel == '' in original call)
$select->set_help_icon($help, $helptext); // optional
$select->form->button->text = $submitvalue; // optional

echo $OUTPUT->select($select);
</code>
Notes:
*The $optionsextra param is not supported. If your code uses it, you should find another way to add extra params to your <option> tags without using this horrible hack which usually includes inline JS or CSS.

=== print_arrow (15) ===
=== print_box* (0) ===
Old code:
<code php>
print_box($message, $classes, $ids, $return);
print_box_start($classes, $ids, $return);
print_box_end();
</code>
New code:
<code php>
echo $OUTPUT->box($message, $classes, $ids);
echo $OUTPUT->box_start($classes, $ids);
echo $OUTPUT->box_end();
</code>

=== print_checkbox (10) ===
Old code:
<code php>
print_checkbox($name, $value, $checked, $label, $alt, $script, $return);
</code>
New code:
<code php>
$checkbox = new html_select_option();
$checkbox->value = $value; // Required
$checkbox->selected = $checked;
$checkbox->text = $label;
$checkbox->label->text = $label;
$checkbox->alt = $alt;

echo $OUTPUT->checkbox($checkbox, $name);
</code>
Note: html_select_option is a component that can be rendered as a select <option>, a radio button or a checkbox. It holds sufficient information to render all these elements, except the $name variable which is attached to a moodle_select component. This is why we pass the $name string to $OUTPUT->checkbox().

=== print_container (0) ===
Old code:
<code php>
print_container($message, $clearfix, $classes, $idbase, $return);
</code>
New code:
<code php>
if ($clearfix) {
$classes .= ' clearfix';
}
echo $OUTPUT->container($message, $classes, $idbase);
</code>

=== print_date_selector (0) ===

=== print_footer (0) ===
Old code:
<code php>
print_footer($course, $usercourse, $return);
</code>
New code:
<code php>
echo $OUTPUT->footer();
</code>
Notes: No parameters are required.

=== print_header (501) ===
Old code:
<code php>
print_header($title, $heading, $navigation, $focus, $meta, $cache, $button, $menu, $usexml, $bodytags, $return);
</code>
New code:
<code php>
$PAGE->set_heading($heading); // Required
$PAGE->set_title($title);
$PAGE->set_cacheable($cache);
$PAGE->set_focuscontrol($focus);
$PAGE->set_button($button);
echo $OUTPUT->header($navigation, $menu);
</code>
Note: Navigation code is being rewritten, this doc will then be updated with the new usage.

=== print_heading_with_help (0) ===

=== print_heading (0) ===
Old code:
<code php>
print_heading($text, $align, $size, $class, $return, $id);
</code>
New code:
<code php>
echo $OUTPUT->heading($text, $size, $class, $id);
</code>
Note: Use a CSS class rule to control alignment.

=== print_heading_block (0) ===

=== print_headline (0) ===
Old code:
<code php>
print_headline($text, $size);
</code>
New code:
<code php>
echo $OUTPUT->heading($text, $size);
</code>

=== print_paging_bar (2) ===

Old code:
<code php>
print_paging_bar($totalcount, $page, $perpage, $baseurl, $pagevar, $nocurr, $return);
</code>
New code:
<code php>
$pagingbar = new moodle_paging_bar();
$pagingbar->totalcount = $totalcount; // Required
$pagingbar->page = $page; // Required
$pagingbar->perpage = $perpage; // Required
$pagingbar->baseurl = $baseurl; // Required
$pagingbar->pagevar = $pagevar;
$pagingbar->nocurr = $nocurr;
echo $OUTPUT->paging_bar($pagingbar);
</code>
Note: The last two instances of print_paging_bar are found in the old tablelib, which will soon be deprecated.

=== print_scale_menu_helpbutton (0) ===
Old code:
<code php>
print_scale_menu_helpbutton($courseid, $scale);
</code>
New code:
<code php>
echo $OUTPUT->help_button(help_button::make_scale_menu($courseid, $scale));
</code>

=== print_side_block (4) ===
=== print_single_button (0) ===
Old code:
<code php>
print_single_button($link, $options, $label, $method, $notusedanymore, $return, $tooltip, $disabled, $jsconfirmmessage, $formid)
</code>
New code:
<code php>
$form = new html_form();
$form->url = new moodle_url($link, $options); // Required
$form->button = new html_button();
$form->button->text = $label; // Required
$form->button->disabled = $disabled;
$form->button->title = $tooltip;
$form->method = $method;
$form->id = $formid;

if ($jsconfirmmessage) {
$confirmaction = new component_action('click', 'confirm_dialog', array('message' => $jsconfirmmessage));
$form->button->add_action($confirmaction);
}

$output = $OUTPUT->button($form);
</code>

=== print_spacer (0) ===
Old code:
<code php>
print_spacer($height, $width, $br, $return);
</code>
New code:
<code php>
$spacer = new html_image();
$spacer->height = $height;
$spacer->width = $width;
echo $OUTPUT->spacer($spacer);
</code>
Note: The $br attribute has been dropped. You can simply add a line break manually if you need one.

=== print_table (140) ===
Old code:
<code php>
$table = new stdClass();
$table->class = 'mytable';
$table->head = array('Firstname', 'Lastname');
$table->rowclass = array();
// (other table properties here)
$table->data = array(array(...),array(...),array(...));
print_table($table, $return);
</code>
New code:
<code php>
$table = new html_table();
$table->set_classes('mytable'); // note the new style of setting CSS class
$table->head = array('First name', 'Last name');
$table->colclasses = array('name fname','name lname');
$table->rowclasses = array(); // note the change of rowclass[] to rowclasses[]
// (other table properties here)
$table->data = array(array(...),array(...),array(...));
echo $OUTPUT->table($newtable);
</code>
Notes: The new html_table object has the same member variables as the one originally used by print_table(), but has additional, required methods. You must map the old $table object to the new html_table object, as demonstrated above and in lib/deprecatedlib.php (see old print_table function).

=== print_textarea (55) ===
=== print_textfield (0) ===

=== print_time_selector (0) ===

=== print_user_picture (0) ===

Old code:
<code php>
print_user_picture($user, $courseid, $picture, $size, $return, $link, $target, $alttext);
</code>
New code (simple):
<code php>
$userpic = new moodle_user_picture();
$userpic->user = $user;
$userpic->courseid = $courseid;
echo $OUTPUT->user_picture($userpic);
</code>
New code (complex: alternate text, size, different image and popup action):
<code php>
$userpic = new user_picture();
$userpic->user = $user;
$userpic->courseid = $courseid;
$userpic->size = $size;
$userpic->link = $link;
$userpic->alttext = $alttext;
$userpic->image->src = $picture;
$userpic->add_action(new popup_action('click', new moodle_url($target)));

echo $OUTPUT->user_picture($userpic);
</code>

=== update_course_button (0) ===

=== update_module_button (94) ===
Old code:
<code php>
$button = update_module_button($cm->id, $course->id, get_string('modulename', 'workshop')); // passed to print_header_simple()
</code>
New code:
<code php>
$PAGE->set_button($OUTPUT->update_module_button($cm->id, 'workshop'));
</code>
Note: $courseid param has been dropped.

=== update_tag_button (0) ===

== Non-supported functions ==
These functions have been completely dropped in 2.0, most likely because they were used very little or not at all. All calls to these functions in core should have been replaced.
=== blocks_print_group ===
=== print_file_picture ===
=== print_png ===
=== print_scale_menu ===
=== print_side_block_end ===
=== print_side_block_start ===
=== print_timer_selector ===
=== print_user ===
=== update_categories_search_button ===
=== update_mymoodle_icon ===

==See also==

* [[Developement:How_Moodle_outputs_HTML]]
* [[Development:Migrating your code to the 2.0 rendering_API]]

{{CategoryDeveloper}}

Development:Deprecated functions in 2.0

2009-08-20T06:28:33Z

Nicolasconnault: Reverted edits by Nicolasconnault (Talk) to last version by Mudrd8mz

{{Work in progress}}
{{Moodle 2.0}}

This page lists the old HTML-outputting functions of pre-2.0 lib/weblib.php and their 2.0 equivalents using $OUTPUT functions.

== General notes ==
The principle of the new rendering API is to let the developer build metadata-rich components that ''represent'' HTML elements, but may be rendered in many different ways. A menu component, for example, could be rendered as a <select> element, or as a list of radio buttons or check boxes.

The following functions have been arranged in alphabetical order, although some of them are very closely related to each other. The number of occurrences of these function calls at the time of writing are indicated in parentheses.

== Functions to migrate ==
=== button_to_popup_window (4) ===
Old code:
<code php>
button_to_popup_window($url, $name, $linkname, $height, $width, $title, $options, $return, $id, $class);
</code>
New code:
<code php>
$form = new html_form();
$form->button->text = $linkname;
$form->button->title = $title;
$form->button->id = $id;
$form->url = $url;
$form->add_class($class);
$form->button->add_action(new popup_action('click', $url, $name, $options));
echo $OUTPUT->button($form);
</code>
Note: popup parameters ($options) '''must''' be prepared as an associative array, not a string as previously. Simply reusing the $options param previously passed to button_to_popup_window() will not work. The $height and $width params are also part of the popup params. See lib/deprecatedlib.php for an example of how the legacy function call is handled.

=== choose_from_menu (192) ===
Old code:
<code php>
choose_from_menu($options, $name, $selected, $nothing, $script, $nothingvalue, $return, $disabled, $tabindex, $id, $listbox, $multiple, $class);
</code>
New code:
<code php>
$select = moodle_select::make($options, $name, $selected); // Required
$select->nothinglabel = $nothing;
$select->nothingvalue = $nothingvalue;
$select->disabled = $disabled;
$select->tabindex = $tabindex;
$select->id = $id;
$select->listbox = $listbox;
$select->multiple = $multiple;
$select->add_classes($class);

echo $OUTPUT->select($select);
</code>

=== choose_from_menu_nested (6) ===
Old code:
<code php>
choose_from_menu_nested($options, $name, $selected, $nothing, $script, $nothingvalue, $return, $disabled, $tabindex);
</code>
New code:
<code php>
$select = moodle_select::make($options, $name, $selected);
$select->tabindex = $tabindex;
$select->disabled = $disabled;
$select->nothingvalue = $nothingvalue;
$select->nested = true;

echo $OUTPUT->select($select);
</code>
Notes:
#The lang string "choose" is no longer used, in favour of "choosedots".
#The $script param is no longer supported. Please use component::add_action() instead.

=== choose_from_menu_yesno (5) ===
Old code:
<code php>
choose_from_menu_yesno($name, $selected, $script, $return, $disabled, $tabindex);
</code>
New code:
<code php>
$select = moodle_select::make_yes_no($name, $selected);
$select->disabled = $disabled;
$select->tabindex = $tabindex;
echo $OUTPUT->select($select);
</code>
Note: The $script param has been dropped, you need to use component::add_action() instead.

=== choose_from_radio (6) ===
=== close_window_button (34) ===
Old code:
<code php>
close_window_button($name, $return, $reloadopener);
</code>
New code:
<code php>
echo $OUTPUT->close_window_button(get_string($name));
</code>
Note: You must pass a language string already processed by get_string().

=== print_continue (91) ===
Old code:
<code php>
print_continue($link, $return);
</code>
New code:
<code php>
echo $OUTPUT->continue_button($link);
</code>

=== doc_link (30) ===
Old code:
<code php>
doc_link($path, $text, $iconpath);
</code>
New code:
<code php>
echo $OUTPUT->doc_link($path, $text, $iconpath);
</code>

=== helpbutton (391) ===
Old code:
<code php>
helpbutton($page, $title, $module, $image, $linktext, $text, $return, $imagetext);
</code>
New code:
<code php>
$helpicon = new help_icon();
$helpicon->page = $page; // required
$helpicon->text = $title; // required
$helpicon->module = $module; // defaults to 'moodle'
$helpicon->linktext = $linktext;

echo $OUTPUT->help_icon($helpicon);
</code>

=== link_to_popup_window (54) ===
Old code:
<code php>
link_to_popup_window($url, $name, $linkname, $height, $width, $title, $options, $return);
</code>
New code:
<code php>
$link = html_link::make($url, $linkname);
$link->add_action(new popup_action('click', $url, $name, $options));
echo $OUTPUT->link_to_popup($link);
</code>
Note: popup parameters ($options) '''must''' be prepared as an associative array, not a string as previously. Simply reusing the $options param previously passed to link_to_popup_window() will not work. See lib/deprecatedlib.php for an example of how the legacy function call is handled.

=== notice_yesno (79) ===
Old code:
<code php>
notice_yesno($message, $linkyes, $linkno, $optionsyes, $optionsno, $methodyes, $methodno);
</code>
New code (simplest form):
<code php>
echo $OUTPUT->confirm($message, $linkyes, $linkno);
</code>
New code (complex form):
<code php>
$formcontinue = new html_form();
$formcontinue->url = new moodle_url($linkyes, $optionsyes);
$formcontinue->button->text = get_string('yes');
$formcontinue->method = $methodyes;

$formcancel = new html_form();
$formcancel->url = new moodle_url($linkno, $optionsno);
$formcancel->button->text = get_string('no');
$formcancel->method = $methodno;

echo $OUTPUT->confirm($message, $formcontinue, $formcancel);
</code>

=== notify (548) ===
Old code:
<code php>
notify($message, $classes, $align, $return);
</code>
New code:
<code php>
echo $OUTPUT->notification($message, $classes='');
</code>
Note: Use a CSS rule for alignment.

=== popup_form (51) ===
Old code:
<code php>
popup_form($baseurl, $options, $formid, $selected, $nothing, $help, $helptext, $return, $targetwindow, $selectlabel, $optionsextra, $submitvalue, $disabled, $showbutton);
</code>
New code:
<code php>
// After converting $options' keys to full URLs:
$select = moodle_select::make_popup_form($options, $formid, $submitvalue, $selected);
$select->disabled = $disabled; // optional
$select->set_label($selectlabel, $select->id); // optional
$select->set_help_icon($help, $helptext); // optional

echo $OUTPUT->select($select);
</code>
Notes: You must convert the $options array so that the index keys represent a full URL: $baseurl . $key . $optionsextra[$key]. See lib/deprecatedlib.php for an example of conversion.

=== print_arrow (15) ===
=== print_box* (380) ===
Old code:
<code php>
print_box($message, $classes, $ids, $return);
print_box_start($classes, $ids, $return);
print_box_end();
</code>
New code:
<code php>
echo $OUTPUT->box($message, $classes, $ids);
echo $OUTPUT->box_start($classes, $ids);
echo $OUTPUT->box_end();
</code>

=== print_checkbox (33) ===
Old code:
<code php>
print_checkbox($name, $value, $checked, $label, $alt, $script, $return);
</code>
New code:
<code php>
$checkbox = new html_select_option();
$checkbox->value = $value; // Required
$checkbox->selected = $checked;
$checkbox->text = $label;
$checkbox->label->text = $label;
$checkbox->alt = $alt;

echo $OUTPUT->checkbox($checkbox, $name);
</code>
Note: html_select_option is a component that can be rendered as a select <option>, a radio button or a checkbox. It holds sufficient information to render all these elements, except the $name variable which is attached to a moodle_select component. This is why we pass the $name string to $OUTPUT->checkbox().

=== print_container (153) ===
Old code:
<code php>
print_container($message, $clearfix, $classes, $idbase, $return);
</code>
New code:
<code php>
if ($clearfix) {
$classes .= ' clearfix';
}
echo $OUTPUT->container($message, $classes, $idbase);
</code>

=== print_date_selector (11) ===
=== print_footer (569) ===
Old code:
<code php>
print_footer($course, $usercourse, $return);
</code>
New code:
<code php>
echo $OUTPUT->footer();
</code>
Notes: No parameters are required.

=== print_header (501) ===
Old code:
<code php>
print_header($title, $heading, $navigation, $focus, $meta, $cache, $button, $menu, $usexml, $bodytags, $return);
</code>
New code:
<code php>
$PAGE->set_heading($heading); // Required
$PAGE->set_title($title);
$PAGE->set_cacheable($cache);
$PAGE->set_focuscontrol($focus);
$PAGE->set_button($button);
echo $OUTPUT->header($navigation, $menu);
</code>
Note: Navigation code is being rewritten, this doc will then be updated with the new usage.

=== print_header_with_help (0) ===
=== print_heading (436) ===
Old code:
<code php>
print_heading($text, $align, $size, $class, $return, $id);
</code>
New code:
<code php>
echo $OUTPUT->heading($text, $size, $class, $id);
</code>
Note: Use a CSS class rule to control alignment.

=== print_heading_block (9) ===
=== print_headline (11) ===
=== print_paging_bar (41) ===

Old code:
<code php>
print_paging_bar($totalcount, $page, $perpage, $baseurl, $pagevar, $nocurr, $return);
</code>
New code:
<code php>
$pagingbar = new moodle_paging_bar();
$pagingbar->totalcount = $totalcount; // Required
$pagingbar->page = $page; // Required
$pagingbar->perpage = $perpage; // Required
$pagingbar->baseurl = $baseurl; // Required
$pagingbar->pagevar = $pagevar;
$pagingbar->nocurr = $nocurr;
echo $OUTPUT->paging_bar($pagingbar);
</code>

=== print_scale_menu_helpbutton (6) ===
=== print_side_block (4) ===
=== print_single_button (108) ===
Old code:
<code php>
print_single_button($link, $options, $label, $method, $notusedanymore, $return, $tooltip, $disabled, $jsconfirmmessage, $formid)
</code>
New code:
<code php>
$form = new html_form();
$form->url = new moodle_url($link, $options); // Required
$form->button = new html_button();
$form->button->text = $label; // Required
$form->button->disabled = $disabled;
$form->button->title = $tooltip;
$form->method = $method;
$form->id = $formid;

if ($jsconfirmmessage) {
$confirmaction = new component_action('click', 'confirm_dialog', array('message' => $jsconfirmmessage));
$form->button->add_action($confirmaction);
}

$output = $OUTPUT->button($form);
</code>

=== print_spacer (20) ===
Old code:
<code php>
print_spacer($height, $width, $br, $return);
</code>
New code:
<code php>
$spacer = new html_image();
$spacer->height = $height;
$spacer->width = $width;
echo $OUTPUT->spacer($spacer);
</code>
Note: The $br attribute has been dropped. You can simply add a line break manually if you need one.

=== print_table (140) ===
Old code:
<code php>
$table = new stdClass();
$table->class = 'mytable';
$table->head = array('Firstname', 'Lastname');
$table->rowclass = array();
// (other table properties here)
$table->data = array(array(...),array(...),array(...));
print_table($table, $return);
</code>
New code:
<code php>
$table = new html_table();
$table->set_classes('mytable'); // note the new style of setting CSS class
$table->head = array('First name', 'Last name');
$table->colclasses = array('name fname','name lname');
$table->rowclasses = array(); // note the change of rowclass[] to rowclasses[]
// (other table properties here)
$table->data = array(array(...),array(...),array(...));
echo $OUTPUT->table($newtable);
</code>
Notes: The new html_table object has the same member variables as the one originally used by print_table(), but has additional, required methods. You must map the old $table object to the new html_table object, as demonstrated above and in lib/deprecatedlib.php (see old print_table function).

=== print_textarea (55) ===
=== print_textfield (2) ===
=== print_time_selector (9) ===
=== print_user_picture (77) ===

Old code:
<code php>
print_user_picture($user, $courseid, $picture, $size, $return, $link, $target, $alttext);
</code>
New code (simple):
<code php>
$userpic = new user_picture();
$userpic->user = $user;
$userpic->courseid = $courseid;
echo $OUTPUT->user_picture($userpic);
</code>
New code (complex: alternate text, size, different image and popup action):
<code php>
$userpic = new user_picture();
$userpic->user = $user;
$userpic->courseid = $courseid;
$userpic->size = $size;
$userpic->link = $link;
$userpic->alttext = $alttext;
$userpic->image->src = $picture;
$userpic->add_action(new popup_action('click', new moodle_url($target)));

echo $OUTPUT->user_picture($userpic);
</code>

=== update_course_button (0) ===

=== update_module_button (94) ===
Old code:
<code php>
$button = update_module_button($cm->id, $course->id, get_string('modulename', 'workshop')); // passed to print_header_simple()
</code>
New code:
<code php>
$PAGE->set_button($OUTPUT->update_module_button($cm->id, 'workshop'));
</code>
Note: $courseid param has been dropped.

=== update_tag_button (4) ===

== Non-supported functions ==
These functions have been completely dropped in 2.0, most likely because they were used very little or not at all. All calls to these functions in core should have been replaced.
=== blocks_print_group ===
=== print_file_picture ===
=== print_png ===
=== print_scale_menu ===
=== print_side_block_end ===
=== print_side_block_start ===
=== print_timer_selector ===
=== print_user ===
=== update_categories_search_button ===
=== update_mymoodle_icon ===