One of the first things you will learn about AEM's architecture are its three basic parts. The content repository, implemented by Jackrabbit Oak. The OSGi container, implemented by Apache Felix. And the RESTful framework provided by Apache Sling. They are all open source.
Then there is everything else Adobe bakes and ships with Adobe Experience Manager. Things like the Multi-Site Manager. Editable templates. Workflows. You know, all the things customers shell out big bucks for. These things are not open source. And their APIs rarely well documented. But with a little intuition, and some trial and error, you can make them work to your advantage.
The Editable Template
Imagine this use-case. You need to write a component that will traverse the page components. And build a list of all the title components. Sounds simple enough right. Lets do some TDD. Here is my test.
Based on this test, the list component will collect a title from any of the title components found on the page. Here is the sling model implementation using an AbstractResourceVisitor. It will traverse the resources of the current page. And collect the title from title components.
And now you can place the list component on either the template structure. Or on the content page. It doesn't matter. As long as the title components are all on the content page. For example on this template, the title list is a locked component. Followed by an unlocked container. On the content page, the author has placed 3 title components. The list component will pick them up.
Locking A Component
An interesting thing happens when you lock a title. When you edit the template, the list component will see the locked titles in the structure. As one would expect. The template would have no clue what pages have or don't have.
But, when you view the page, the list component will not pick up on the locked component. Even though it is there on the page. Locked.
The Structure Resources
You may have encountered this problem. You might choose to leave the titles unlocked. Or you might write extra code to search the template structure. But you can't help but feel the answer is staring you straight in the face. The components from the template and the page are some how merged and rendered in the correct order. How does Adobe do it?
The open source will only take you as far as the core page component's body.html. It uses com.day.cq.wcm.foundation.TemplatedContainer. The only thing we know from the JavaDoc is that it is a WCMUsePojo. This is where intuition kicks in. If there is a WCMUsePojo, there might be a helper. Or a manager.
Look at the Sling Adapters console. A resource resolver is adaptable to a TemplateManager. And it has a getStructureResources method. Again, its is not well documented.
After some trial and error, the sling model gets updated. It will now traverse the structure components.
Because the template manager is not open source, the wcm.io AEM mocks will not help you. You need to register a mock adapter. And make sure it returns some content structure.
Finally, when the list component renders, it will find all the title components. On the template and on the page.
Conclusion
We understand the role editable templates play in AEM. But because they are NOT open source, we understand very little about what is going on under the hood.
By getting the structure resources, you are getting a merged view of the page contents. It would be interesting to know the method by which Adobe merges the template and page. Unfortunately, it is proprietary software. Not meant for us to know.