Document template-accessible vars.logged_in_user_hash or session.logged_in_user[_realm]?

[cxw42]

I am learning Dancer2 and find this module quite useful! I see that logged-in-user information is available in a TT2 template through vars and session. For example, both of these work:

[% if vars.logged_in_user_hash %]
  <p>(Hash) You are logged in as
  [% vars.logged_in_user_hash.name | html %]</p>
[% end %]

[% if session.logged_in_user %]
  <p>(Session) You are logged in as
  [% session.logged_in_user | html %]@[% session.logged_in_user_realm | html %]</p>
[% end %]

However, I do not see vars.logged_in_user_hash or session.logged_in{_user,_user_realm} documented in the POD for this module. Is any of those part of the public API of this module? If so, could they be documented? Thanks for considering this question!

[abeverley]

Hmmm, good question, and I think it would be worth documenting either way. I think avoiding vars would be sensible, but being able to use session makes more sense. Pending comments from anyone else, I'd be happy to merge a PR with such documentation changes.

[cxw42]

Thank you! The advantage of vars over session is that vars includes all the user information, not just the username. If I understand you correctly, you would prefer that feature remain undocumented, and that template calls manually pass logged_in_user. Is that correct? E.g., template 'foo'.tt => { current_user => logged_in_user }, and the template uses [% current_user.name %] instead of [% vars.logged_in_hash.name %].

If vars.logged_in_user_hash is indeed to be not part of the public API, should it be renamed to have a leading underscore?