if you apply the page template to the page fragment then the popup in it becomes available. There is a strategy to launch template content on a parent page (you would do this by injecting a managed bean (view scope) from the parent to the task flow that contains APIs to call the popup), which however requires more "infrastructure" to be build into the task flows
Option 1. page template on the fragment (the popup is contained in the task flow and can be accessed easily and direct.
Option 2. page template on parent document (use a managed bean to inject a reference API to launching the popup)
there is no document I am aware of and I did not have time to write this up yet.
However, here's how I would do it:
1. Use page template on the parent document for popup information that is common (e.g. showing a static message) and that doesn't need to call back into the invoking page (e.g. OK button on dialog)
2. Use page template for page fragment for all other cases
3. The popup in the page fragment should have a facet so you can individually add e.g. a dialog or a note window
4. To launch the popup from Java, repeatedly call getParent() on whatever component you start with (e.g. command button action listener) until you find an instance of "RichPageTemplate". With this handle you can now call pageTemplate.findComponent("id_of_popup") and cast it to "RichPopup" Then call RichPopup.show(hint). The hints is an instance of an inner class from RichPopup.Hints