Poodll widgets (and players) are collections of javascript, CSS and HTML. In Javascript and HTML, the template author can include variables. At run time, when the widget is displayed, the variables will be replaced with values passed in to the template, or determined automatically.
So in a basic example the HTML for a youtube player template might look like this:
<iframe width="@@WIDTH@@" height="@@HEIGHT@@" src="https://www.youtube.com/embed/@@FILENAME@@" frameborder="0" allowfullscreen></iframe>
The template user would pass in the width and height and videoid, and Poodll would merge those with the template, to produce the HTML that is sent to the page. The template author can define default values for variables and there are numerous Poodll native variables that can be used too. In the above example width and height would probably have default values.
Templates work closely with the Poodll filter. The Poodll filter will either filter links in the page text, or Poodll filter strings, and replace them with the template content.
Filtering Links
This link:
<a href="https://mypoodll.com/nice.mp3">nice.mp3</a>
could be merged with this template
<audio id="@@AUTOID@@" controls="controls" controlsList="nodownload" class="nomediaplugin"> <source src="@@VIDEOURL@@" type="audio/mpeg"> Your browser does not support HTML5. </audio>
to produce this putput.
<audio id="poodll1234567" controls="controls" controlsList="nodownload" class="nomediaplugin"> <source src="https://mypoodll.com/nice.mp3" type="audio/mpeg"> Your browser does not support HTML5. </audio>
Filtering Filter Strings
This filter string:
{POODLL:type="warningbox",text="Here be dragons"}could be merged with this template
<div class="filter_poodll_warning"> <i class="fa fa-warning"></i> @@text@@ </div>
to produce this content.
<div class="filter_poodll_warning"> <i class="fa fa-warning"></i> Here be dragons </div>
Before attempting to author a template, it would be wise to become familiar with using them first. These articles should help:
Templates, widgets and players
The template settings
There are numerous fields on a template settings page.
Setting | Explanation | Can use variables? |
| Display name | The name of the template as seen in the user interface | NO |
| Key | The unique id for the template. Alphanumerics are ok, so it should be human readable. | NO |
| Version | A version number in xx.xx.xx format. This is used to semi-automate the updating of standard templates with newer versions. | NO |
| Instructions | Instructions or a description of the template. The instructions are shown beside lists of templates in admin settings and in the Atto editor icon popup. | NO |
| Show in Atto | Show the template as an option in the Atto editor icon popup. This marks the template as a "widget" because the user can set template variables manually and Poodll filter tags are inserted on the page from Atto. | NO |
| Show in Players list | Show the template as a player in the list of players, when allocating a player handler to a file extension. This marks the template as a "player." Players set certain template variable's automatically from the filtered URL text. | NO |
| The body | The body contains the html that is inserted on the page in place of the filtered text/link. | YES |
| End tags | In some cases you may wish to split the template html into two pieces. So that the user can place content in between the pieces e.g The image gallery template, allows the user to add images to the html area in between the tags. When the html is displayed, the images are shown in the gallery. | NO |
| Variable defaults | A comma separated list of variable names and default values. If the default value is a pipe delimited list of options, then it will be displayed as a dropdown on the Atto icon popup. | NO |
| Requires JS | The URL to any javascript library which your template needs. Whatever the library exports will be available in the Custom JS area as: requiredjs_[template key] | NO |
| Load via AMD | Your template javascript can be loaded as an AMD module, giving them access to jquery and jquery ui. Since Moodle 2.9 RequireJS is part of Moodle. This is an AMD implementation. If you set a javascript library in the "Requires JS" field (sorry for poor naming) it may detect the RequireJS environment and expect to be loaded as AMD (and throw an error if not). | NO |
| Shim export | To make a non AMD javascript library work as an AMD module, you can give it a name and Poodll will try and make a 'shim' for it. Whatever the library exports will be available in the Custom JS via the name. | NO |
| Custom JS | Any Custom JS you want to run in your template should go here. The code here is run once for each template instance on a page. | YES |
| Requires CSS | The URL to any CSS library which your template needs | NO |
| Custom CSS | CSS style declarations can go here. | NO |
| Dataset | If you wish the include the results of a database query in your template output, you can set the query here. This is passed straight to Moodle's get_records_sql function, so look to that for how to write your SQL. | NO |
| Dataset variables | Parameters (probably template variables) that should be passed to the dataset SQL query should be specified in a comma separated list here. This will be passed in as parameter 2 of the Moodle get_records_sql call. You can use template variables here so for example this would be ok: @@COURSE:id@@, @@USER:id@@ | YES |
| Alternate content | When the template content is displayed on the Moodle mobile app, some javascript may break and some html will not show as you expect. Set alternate "body" content for the Moodle mobile app here. | YES |
| Alternate content end tags | Set alternate "body end" tags/content here (if any). | NO |
Poodll Native Variables
Poodll makes available a number of variables for use in your template to make life easier. Note that when the Poodll filter parses a link it does its best to extract the relevant bits of the link that a player template would need. But this information will not be available if the parsed content was a Poodll filter string.
Variable | Description | Available |
| AUTOID | This is the most common variable. Use this in the "body" to assign a unique DOM id to html elements. Later in the JS you can select the element by using the AUTOID variable to add events or perform javascript operations on it. | Filter string, Link |
| WWWROOT | This returns the URL of the Moodle site. | Filter string, Link |
| MOODLEPAGEID | The value of the id parameter passed into the url of the current page(if present). | Filter string, Link |
| URLPARAM:xxxx | The value of a url param passed into the current page. xxxx= the url param. For filtered links, the url params are available as top level native variables, without the URLPARAM: bit. | Filter string |
| COURSE:xxxx | A value from the current course record. xxxx= the field of the course record | Filter string, Link |
| USER:xxxx | A value from the current user's user record. xxxx= the field of the user record | Filter string, Link |
| DATASET:xxx | A value from the result set of the SQL query used in the DATASET setting. If there is only one record in the result set, each record field is available at DATASET:xxx. If there are multiple records, then @@DATASET@@ is an array and you will need to manipulate it to get back the data in a way that is appropriate. | Filter string, Link |
| FILENAME | The filename part of the link URL. | Link |
| AUTOJPGFILENAME | The link URL filename but instead with a "jpg" extension | Link |
| AUTOMIME | File mime type as determined by filename extension | Link |
| AUTOPNGFILENAME | The link URL filename but instead with a "png" extension | Link |
| AUTOPOSTERURLJPG | The full link URL but with a jpg extension | Link |
| AUTOPOSTERURLPNG | The full link URL but with a png extension | Link |
| FILEEXT | The file extension of the linked file | Link |
| VIDEOURL | The full link URL. (It does not need to be a video) | Link |
| URLSTUB | The full URL minus the file extension | Link |
| TITLE | The linked text. | Link |
| WIDTH | The width of the video/widget | Link |
| HEIGHT | The height of the video/widget | Link |
Working with Capabilities
Sometimes you want to hide or show content depending on the user's role. To do that use either of these attributes on the filter string.
- viewcapability
- hidecapability
If present, the specified capability is checked against the logged in user and the course context. If the user has the capability, the filtered content is either shown(viewcapability) or hidden(hidecapability).
e.g
{POODLL:type="welcomeuser",viewcapability="moodle/course:manageactivities"}
OR
{POODLL:type="welcomeuser",hidecapability="moodle/course:manageactivities"}
It is better to work capabilities and not roles because there are custom roles and customized roles. On your own site you may be able to assume all, and only, teachers have the teacher role. But that is not true of all sites.
By default the capability "moodle/course:manageactivities" is basically equivalent to the "Teacher" or "Manager" role.
The capability "gradereport/grader:view" is similarly equivalent to the "Non Editing Teacher" role. (I think)
More References
Older but closely related documentation for the Generico and VideoEasy filters is available here. Poodll combines both these filters and provides a wide range of templates.
Without any doubt the best way to learn how to build templates is to look at existing template presets, and see how they work.