Can someone point me in the 'write' direction to more about the HTML Writer, syntax and stuff? I first came across html_writer in a tutorial written by Sam Hemelric, but he only gave a brief overview of it in this page...
Thanks
Mary
Just search the Moodle code for "html_writer::" to find lots of examples.
It is basically a simple helper class for outputting HTML tags. It lets you do things like
echo html_writer::tag('div', 'Some content', array('id' => 'xyz', class => 'mydiv somethingelse'));
Of course, for a simple example like this, it would be easier to do
echo '<div id="xyz" class="mydiv somethingelse">Some content</div>';
however, in code where the content and the attributes are coming from different variables and function calls, html_writer is a lot easier to use that writing code with lots of string concatenation.
Hi Tim,
Thanks for the reply.
I have used html_writer to good advantage in a couple of themes, lately, and understand what I have done so far, but there are elements of the syntax I am struggling with. Mainly not knowing how to write the following...
in simple HTML terms it goes like this...
<a href="localhost/moodle" title="home" ><img src="home_icon.png" alt="Home" /></a>
However, how would I write the above in php using the html_writer class for Moodle 2.0, given that there are some predefined php functions for pix output?
For example - hyperlinks to specific pages can be written thus...
echo html_writer::link(new moodle_url('/user/profile.php', array('id'=>$USER->id)), get_string('myprofile')).' | ';
echo html_writer::link(new moodle_url('/login/logout.php', array('sesskey'=>sesskey())), get_string('logout'));
and output for an image can be written thus...
echo html_writer::tag('div', $OUTPUT->user_picture($USER, array('size'=>55)), array('class'=>'userimg'));
But how would I combine the two to get my example to work?
Mary
Try
echo html_writer::link(new moodle_url('/'),
html_writer::empty_tag('img', array(
'src' => $OUTPUT->pix_url('home_icon', 'theme'),
'alt' => get_string('home'))),
array('title' => get_string('home')));
It would be nice to add an html_writer::image($src, $alt, $attributes); method, but no ones seems to have written that yet. So, we just have to use html_writer::empty_tag, which is easy enough.
Thanks for this Tim!
Is it the intention that themes can alter the behaviour of the HTML writer?
No...rather the other way round.
I just want to know HOW to USE it to my advantage.
There are two levels of abstraction here. Renderers and html_writer.
Renderers are the higher level concept. They have methods like $OUTPUT->user_picture(...), $OUTPUT->block(...), $questionrenderer->question(...). These are the things that themes can override.
Obviously, the renderers actually need to output HTML in order to display those things, and html_writer is just a low-level helper class that makes that easier. For example, it is probably easier to say
echo html_writer::empty_tag('img', array('src' => $pixurl, 'alt' => get_string('alt')));
than it is to say
echo '<img src="' . $pixurl . '" alt="' . get_string('alt') . '" />';
Actually, in that simple case, the string concatenation comes out shorter than the html_writer call. In more complex cases, however, the string concatenation gets worse, and very hard to read. The html_writer version tends to stay more manageable.
Hi Tim,
Perhaps if I had asked for a Glossary of Terms so that I could learn the various terms used as you have in this example:
echo html_writer::empty_tag('img', array('src' => $pixurl, 'alt' => get_string('alt')));
Go back a few years and try to recall how you first learnt how to do this. All I am doing at the moment is finding something similar and copying it. Surely there must be a book I can read on this...but what do I ask for at Waterstones or on Amazon!
Thanks
Mary
+1 for that
I'm looking at all this and thinking why? It seems at the moment, that it's easier to just write the code by hand than dig so deep to find examples of code to try to learn from with no real guide - and when I'm really still looking for examples that make the html_writer more worth while - and easy enough for others to follow behind and build on any code I've created - than coding by hand. I personally don't like the idea of writing part of the code with html_writer and part of it 'traditionally' and if it's the best/recommended way of doing it I would like to use the html_writer, but want to do it properly
Are the performance hits of calling html_writer for something like <li> or an img tag like your example, Tim, outweighed by the benefits for the relatively few complex lines used in theming? Or is this something which is likely to be appropriately used more in the core coding or the modules and plugins?
Please don't take this as criticism of the html-writer class, it is purely intended to help me understand the benefits of it and how to use it best.
Richard
Well, html_writer did not exist a few years ago
The way to learn the details of an API like html_writer is to look at the documentation of the methods (http://phpdocs.moodle.org/HEAD/core/lib/html_writer.html#empty_tag - warning, that is a bit out of date) and then if that is not explained well enough, just try it out and see what happens, or read the code.
Thanks Tim, this will come in very useful.
Cheers
Mary
Just be warned that phpdocs.moodle.org, which should be automatically regenerated regularly, was last updated in August. That is very out-of-date. I just reopened MDLSITE-952. Please vote if you care.
Excellent Tim, thanks for that
Richard
finding quite a few cases where the html_writer seems to be being used for things that are both shorter and more readable to do in html.
course/lib has things like echo html_writer::start_tag('div', array('class' => 'activityinstance'));
renderers are also full of people using $content.=html_writer::start_tag('ul',array('class'=>'nav')); and other crazy stuff.
any ideas how we can nip this in the bud?
I've been trying to figure out why to use html_writer, and really I can only come up with because it's been decided to.
As to why it was made in the first place, I'm not sure. I think a programmer decided that HTML just wasn't complex enough. So we took something that was cascading and made it object-oriented.
I'm just waiting for them to finish css_writer so I can do this:
$css = css_writer::rule($color, 'background-color', '#page-header');
I kid, I kid...
Do you really think code like https://github.com/timhunt/moodle/blob/MOODLE_19_STABLE/question/type/questiontype.php#L931 is easy to work with?
How easy it is to convince youself that will always output valid HTML? The equivalent html_writer code is guaranteed to output valid HTML, with all argument values properly escaped, and all attributes correctly surrounded by quotes.
The corresponding code in 2.x is not exactly the same, because of other changes in the UI but it at https://github.com/timhunt/moodle/blob/master/question/engine/renderer.php#L287.
Also, in the days of XHTML, the recommendation was to write empty tags like <img ... />. Now with HTML5 the recommendation is to write <img ...>. If you have raw HTML throughout your code, making that change is hard. If you are using a funciton like html_writer::empty_tag everywhere, you only have to change one line of code.
I'm not entirely sold that the 1.9 version is "harder" to properly escape than the 2.0 - the benefit of the 2.0 version is debugging, or fatal error...
In the end, I wasn't really ragging too hard on html_writer. It's not that complex, or that hard to manage, but if you just take the face value of a tag and compare it to html_writer - it seems overly engineered.
Just realized I forgot this on my last post:
html_writer::tag('sarcasm', $content, array('class'=>'none'));
@danny -my suggestion to improve the syntax would be to have, like in the forms lib, a html_writer of type html
e.g.
html_writer::html("<sarcasm class='none'>$content</sarcasm>");
this would be of great benefit.
return html::div('editquestion', html::icon_link($editurl, 'edit', _('editquestion', 'question')));
return html::icon_link('editquestion', $editurl, 'edit', _('editquestion', 'question')));
An actual example that I've found in various renderers:
foreach ($nextstageurl->params() as $key=>$value) {
$form .= html_writer::empty_tag('input', array('type'=>'hidden', 'name'=>$key, 'value'=>$value));
}
Where the code is basically a verbose version of the output HTML:
<input name=contextid type=hidden value=2>
<input name=filepath type=hidden value=318aeb66dba730135ab93ba66f9dbea3>
<input name=stage type=hidden value=2>
And could have probably just as easily been written:
foreach ($nextstageurl->params() as $key=>$value) {
$form .= "<input type=hidden name=\"$key\" value=\"$value\">";
}
But since we've already introduced the PHP function and the concept of looping, and hidden inputs are fairly standard things I'd rather see:
html::hidden_inputs($nextstageurl->params());
or for a single input:
html::hidden_input($name, $value);
even though it might initially be a bit more opaque, it's much more readable once you understand it, and you can get a much better overview of what's going on rather than everything being hidden by the low-level details. And then you can get even more abstract and just pass the params into the function building the form, or just pass the moodle_url object that actually has both the URL and the params within it rather than extracting them out and working on them directly every time.
Did you look to see whether this already existed? https://github.com/moodle/moodle/blob/master/lib/outputcomponents.php#L1427
echo html_writer::input_hidden_params(new moodle_url($PAGE->url, array('sesskey' => sesskey(), 'return' => $return)));
I agree. I wish there was a single hidden input method, and also a hidden_inputs method that just took an array. Someone should code it and submit a patch.
@tim - for me the 1.9 example is much easier to work with.
It highlights well in an ide and dosn't cause me any cognative effort to understand. Its code you can use in any framework/cms and that is a huge bonus as we know so any developer would be able to work with your code.
You might find it simpler to concat the strings first then build the return object, especially if your iterating through a loop.
If you really need help identifying your variables, then maybe using {$tim -> getStuff($braces);} like zend etc might be useful to you? This also highlights nicely in most ide.
Looking at html_writer::tag am i write in saying its built that way because it fits with the syntax used by pear quickforms in moodle (cough!) and builds up yet another barrier to developers from outsiders of moodle while firmly placing moodle in the legacy code/over engineered camp it so often gets critisim for?
Be interested to see what stack overflow had to say about this...
Cheers
Stuart {boycoting the tinymce spellchecker}
html_writer has nothing to do with quickforms.
And the concept is not terribly novel. Many languages have similar liabraries.
(I found those in 5 mins with Google.)
Anyway, you don't like this coding style. I like it because I think it eliminates the potential for many bug. Niether of us is going to persuade the other, so let's stop this pintless discussion and get back to making Moodle better for users.
shortcode systems such http://lesscss.org/, http://coffeescript.org/ and jquery are great because they enable you to write less code in a much more understandable way to generate consistant code.
for example in jquery i can write $('#myid).function(do stuff); instead of the long form standard js way.
less/sass ae similar with css variables and mixins that as with coffeescript removes all the unnecesary stuff allowing you as the programmer to concentrate on the important maintainable code logic.
shortform generally tends to be shorter to write, not longer. Its intention is to make code more understandable and easier to write, not less understandable and more difficult to write.
markdown is a good example of html shortform. html_writer:: is not.
hope this makes sense!
"And the concept is not terribly novel. Many languages have similar liabraries. "
Yes, but those libraries have documentation (for instance, Codeigniter's HTML Helper). If you've got to hunt through class code to find out how to use HTML Writer then it becomes more time-consuming to use that than to write raw HTML. It's also bad for your successors who'll look at your code and wonder where the flip it comes from. Good documentation is the key to successful usage, in my experience.
Fred
Bravo Fred!
I think you have won the 'Star Answer Award' for today! Brilliant answer, thank you for making it so clear! That is just how I feel about HTML Writer. I struggle with it because there is no documentation.
Cheers
Mary
I have a renderer in an advanced grading plugin that uses HTMLWriter that includes textareas Hmmm, it would be nice if users had a proper editor instead (i.e. Atto/TinyMCE), but I have not been able to figure that out at all.
That would be useful!
Note, the PHPdocs in teh code are meant to be compiled into some nice HTML documentation pages. HQ have been planning to get that working for at least 5 years. It may happen one day.
I have just found this link...
http://www.collinsharper.com/documentation/moodle/classhtml__writer.html
which gives lots of detail but no examples (so far), but does lead off to other interesting files that store all the functions like this one...
http://www.collinsharper.com/documentation/moodle/outputcomponents_8php_source.html#l00907
which is, I suppose, where all the html_writer functions for Moodle emanate from?
Right. Moodle HQ should be publishing the PHPdocs like that.
They have never had time to set it up.
Ah bless their little cotton socks!
Could I do it...is it hard to do! LOL
I've never tried it. Google found me this: http://jpablobr.com/past/how-to-build-php-documentation-with-phpdocumentor Looks suprisingly short.
Official docs are here: http://www.phpdoc.org/docs/latest/guides/running-phpdocumentor.html
Thanks very much, Mary - that's a very handy reference, and saves having to RTFC to find out the syntax of html_writer.
Fred
Hello,
I've came across this post from a google search. Noticed that there hasn't been much activity in here since 2012 but seems relevant to the html_writer topic.
I'm trying to re-write the current php for the Scorm player. The problem, it's currently displaying the "Exit Activity" as a (a href) link. But I would like it to be displayed as a button, like the rest of the "edit buttons" in Moodle.
How do I go about doing that if this is the code...
if (empty($scorm->popup) || $displaymode == 'popup') {
$exitlink = html_writer::link($CFG->wwwroot.'/course/view.php?id='.$scorm->course, $strexit, array('title' => $strexit));
$PAGE->set_button($exitlink);
}
Any PHP experts out there? Thanks.
Hi Robert:
I have learned a lot about HTML writer since starting off this discussion.
Here is a link to one of the best references about the subject:
Here is the part that explains the link element:
As for how to make the link into a button depends largly on if you are using the most uptodate version of Moodle which uses Twitter Bootstrap 2.3.2 Buttons or are you just talking buttons in general?
Anyway here is how you would make this link into a button in Clean theme:
if (empty($scorm->popup) || $displaymode == 'popup') {
$url = $CFG->wwwroot. '/course/view.php?id='. $scorm->course;
$button = 'btn btn-default';
$exitlink = html_writer::link($url,
$strexit,
array('title' => $strexit, 'class' => $button));
$PAGE->set_button($exitlink);
}
At least I think this is correct?
Cheers
Mary
Hi Mary,
Thanks for sharing the resource! This is actually really helpful. I'm using 2.8 so it is using Bootstrap and your code works like a charm.
Best,
Robin
Hi,
So pleased it worked out OK.
Cheers
Mary
I found phpdocs invaluable for htmlwriter and other things. Unfortunately i havent been able to access it for months now. Phpdocs.moodle.org
Do other similar systems in PHP really just write plain HTML into their code? How is it possible for them to maintain consistency? Is that all done manually within the theme?
Just had a look at Wordpress, they seem to have a mix of templates that call functions from a standard API and functions that embed the HTML directly. The functions are overridden by themes. Then they also have the shortcode system to embed functions into content.
One pattern I see is that they use quite "programmery" things to to generate the list of classnames, then just insert the result in as text e.g.:
$css_class = implode( ' ', apply_filters( 'page_css_class', $css_class, $page, $depth, $args, $current_page ) );
$output .= $indent . '' . $link_before . apply_filters( 'the_title', $page->post_title, $page->ID ) . $link_after . '';
from: https://github.com/WordPress/WordPress/blob/master/wp-includes/post-template.php
I'd kind of been working on the principle that if you could cope with imploding filtered arrays then you'd be happy enough calling a function to generate the HTML. But maybe people just ignore the scarier bits and change the stuff they recognise?
// LESS
.rounded-corners (@radius: 5px) {
-webkit-border-radius: @radius;
-moz-border-radius: @radius;
-ms-border-radius: @radius;
-o-border-radius: @radius;
border-radius: @radius;
}
#header {
.rounded-corners;
}
#footer {
.rounded-corners(10px);
}
/* Compiled CSS */
#header {
-webkit-border-radius: 5px;
-moz-border-radius: 5px;
-ms-border-radius: 5px;
-o-border-radius: 5px;
border-radius: 5px;
}
#footer {
-webkit-border-radius: 10px;
-moz-border-radius: 10px;
-ms-border-radius: 10px;
-o-border-radius: 10px;
border-radius: 10px;
}
css vars are also in chrome canary - been having lots of fun using them