patternfly templates for patternfly org
This document provides guidelines on how to write templates on patternfly test pages that can be immediately consumed by patternfly-org.
The patternfly-org repo is the source for the patternfly.org website. Every time a component is presented as a "live example" in the website, patternfly-org is consuming a template from the patternfly repo, and the component can be seen in patternfly test pages. The code consumed by patternfly-org can be a full page template, or a component template.
A full page layout is displayed as live example in the pattern page. Example: Login Page.
Patternfly-org uses an include to call for the login.html template, which is a full page layout that can be seen on patternfly test pages.
The template file is located in the patternfly repo: patternfly/tests/pages/_includes/widgets/framework/
A component is displayed as live example in the pattern page. Example: Left Description and Right Label component in the Utilization Bar Card page.
Patternfly-org uses an include to call for the utilization-bar-side-labels.html template, which is a component available inside the cards page in patternfly test pages.
The template file is located in the patternfly repo: patternfly/tests/pages/_includes/widgets/cards/
Whenever you write a new test page in patternfly, keep in mind that pieces of the code might be needed by patternfly-org. If that is the case, follow these steps:
The components that will also be displayed in patternfly.org need to be writen as templates to be consumed as includes. This way we avoid replicated code, and the same template is called both by the test page in patternfly and by the pattern page in patternfly-org via include.
The template is a html file stored inside the widgets folder in the patternfly repo.
For example, the Inline Notifications page presents 6 different components (alerts) as live examples.
They were written as templates. In patternfly-org, they are consumed via includes:
The same templates are consumed in the patternfly Alerts test page via includes.
Note that some elements that are exclusively presented in this test page are coded in the page itself. Unless they are use somewhere else, they don't need to be written in a separate file as a template and called via include.
The javascript of our examples should be authored in a sufficiently robust manner that they won’t fail in the presence of un-anticipated HTML markup, nor conflict with other scripts. These conflicts can occur with site code/markup, from other examples, or even from multiple inclusions of the example itself.
In practice this means that selectors you need to write the code in a way that the include works when added at least twice in the same page. Special attention needs to be taken with ids and javascript, since the repetition of an id or a javascript can make the component malfunction. Similarly jQuery selectors need to be sufficiently specific to be isolated to the example at hand (eg. not selecting all checkboxes on a page, but rather those from a particular container).
In the Utilization Trend Card page, the donut and sparkline charts are included more than once in the page. Note that the three tabs (Overview, Design and Code) are the same page. These components depends on an exclusive id to work. If ids are repeated, they don't render in the page.
To solve this problem, the components used in the page need to have the ids declared as parameters in patternfly:
This way, it is possible to declare a different id each time the template is included in the page in patternfly-org, which guarantee that they will render.
The same thing happens with other components that depend on the id to work, such as:
- Modals (About Modal and Wizard pages)
- Charts
- Date-picker
- Field Level Help
- Time Picker
Originally, the component toolbar.html had a <script> code in it to show / hide the find dialog.
This was working fine in the patternfly test page, but when I included it in the Toolbar page in patternfly.org, the find dialog was no longer opening.
Since the include toolbar.html was imported twice in the page, the javascript was also being imported twice, and this was the problem. The adopted solution was to remove the javascript from the include and add it to the test page in patternfly, and to the page itself in patternfly-org. Another possibility would be to use ids in the javascript and keep it in the template.
Toolbar.html page in patternfly. View code in GitHub
A very simple way to test if your code will work on patternfly-org is to call the same include more than one time in the page. If it works, it will probably work on patternfly-org. If not, you probably need to adjust some id or javascript issue.