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

How to handle MP3

How to make a widget template

How to make a player template

How to use template bundles


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 interfaceNO
Key  The unique id for the template. Alphanumerics are ok, so it should be human readable.NO
VersionA version number in xx.xx.xx format. This is used to semi-automate the updating of standard templates with newer versions.NO
InstructionsInstructions 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 AttoShow 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 listShow 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 bodyThe body contains the html that is inserted on the page in place of the filtered text/link.YES
End tagsIn 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 defaultsA 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 JSThe 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 AMDYour 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 exportTo 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 JSAny 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 CSSThe URL to any CSS library which your template needsNO
Custom CSSCSS style declarations can go here.NO
DatasetIf 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 variablesParameters (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 contentWhen 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 tagsSet 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
AUTOIDThis 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
WWWROOTThis returns the URL of the Moodle site.Filter string, Link
MOODLEPAGEIDThe value of the id parameter passed into the url of the current page(if present).Filter string, Link
URLPARAM:xxxxThe 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:xxxxA value from the current course record. xxxx= the field of the course recordFilter string, Link
USER:xxxxA value from the current user's user record. xxxx= the field of the user recordFilter string, Link
DATASET:xxxA 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
FILENAMEThe filename part of the link URL.Link
AUTOJPGFILENAMEThe link URL filename but instead with a "jpg" extensionLink
AUTOMIMEFile mime type as determined by filename extensionLink
AUTOPNGFILENAMEThe link URL filename but instead with a "png" extensionLink
AUTOPOSTERURLJPGThe full link URL but with a jpg extensionLink
AUTOPOSTERURLPNGThe full link URL but with a png extensionLink
FILEEXTThe file extension of the linked fileLink
VIDEOURLThe full link URL. (It does not need to be a video)Link
URLSTUBThe full URL minus the file extensionLink
TITLEThe linked text.Link
WIDTHThe width of the video/widgetLink
HEIGHTThe height of the video/widgetLink


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.