This page is intended to be a guide to application development. It describes the design of the present documentation page and shows, how real life problems can easily be solved using the adventure php framework. Further, this page presents several source code examples to you, that can be used for your applications, as well.
At first, the article describes the software design of the page. After that, the dynamic perspective and view concept is discussed. Then, several examples are presented containing source code as well as some explanations on this issues.
As you have already mentioned, this page features two main layouts: the start page and the documentation pages. Some of the elements presented in those - we call them - perspectives are similar, some are not. The challenge is now, to structure the software in a way, that you don't have duplicate code. Let us at fist have a look at the two perspectives and the areas, that can be defined:
The areas have the following meaning:
On "real" content pages, the sidebar presents a quick navigation that eases navigation on the current page. The generic sidebar functions such as search are placed below the quick navi.
The software design of this documentation page differentiates between two structural elements: the areas and the views. The areas define the main parts of the page such as header and content area and the views represent the content.
Each area is realized by a simple <core:importdesign/> tag definition. The view itself is a template, that is intended to generate dynamic content. This concept makes the page flexible and easy to maintain and to extend in further times.
Within special views, the APFModel is used to decide, which content to display. This means, that the APFModel is used as a central view model.
To be able to reuse one template for several languages, the templates mentioned above are created language independent. This means, that every template contains place holders, that are filled with the language dependent values at transformation time. This can be achieved using the <html:getstring/> tags or simple place holders that are filled within a document controller. Please note, that this function can only be implemented in the way described before, because each APF DOM node knows about it's language. Setting the root node to a specific language, all the child nodes will be applied this language.
The fact of language inheritance within the APF DOM tree is also used here to control the language of the view templates. For this reason, a global front controller action is executed on each request that checks the language set in the bootstrap file and analyzes the url keywords and thus decides which language the page currently has got. The action then manipulates the language param of the front controller, and that way the language of the page's DOM tree, too.
As already mentioned above for some times, the documentation page features a dedicated business layer, that cares about the view to display and the current language of the page. It also handles the page sensitive information like html meta data (keywords, description, ...) that are used by the perspective controller to fill the meta data.
This is done by the SetModelAction that is statically registered with the front controller. Within this action, the current language, the content template to display and the meta information to place are evaluated.
A current copy of the code can also be checked out from the GitHub repository. To do so, please call
git clone https://github.com/AdventurePHP/docs.git <your_target_folder>