Hey, I ran into this problem myself today. Thanks, all, for spelling out all the issues and solutions.
Unsurprisingly, Chris was right - the field is there, but it took some serious searching to find it:
$contentletId is the identifier of the widget instance.
Also, note that this is useful if you need to get at the values and options of a Select or Multiselect, which are also 'crippled' in Widget/Container code. (calls to such a field return the selectedValue)
That is - $myselect would simply return 'yes' (which IS helpful most of the time), instead of referencing the normal $myselect.selectedValue.
Some code that shows this in action:
<div class="page-section">
<h2>$!title</h2>
$!copy
<div class="block-accordion-set">
#set ($puller=$dotcontent.find($contentletId))
##Now we have the widget as if it was in a normal velocity context, rather than in the Widget Context.
##E.g. $title above works, but it is also $puller.title, and we can extract the relationships properly.
#set ($accordions=$puller.accordionEntry)
#foreach ($accordion in $accordions)
<div class="accordion">
<input id="accordion-${velocityCount}" type="checkbox" class="hidden-check">
<label for="accordion-${velocityCount}">$accordion.heading</label>
<div class="expander-content">
<div class="expander-scroll">
<div class="section">
$accordion.copy
</div>
</div>
</div>
</div>
#end
</div>
</div>
Mark Pitely
Marywood University