Contributing Patternfly 3 Code Examples
Once patternfly-org is up and running, to contribute an existing patternfly example and code snippet to display on patternfly-org, a code.md file for that pattern must be created first.
For example purposes, the pattern - experimental features will be used. Inside of source/_includes/code/communication is where the experimental-features folder should be manually created along with an associated code.md file. This should be the first step done for every new code.md file introduced in patternfly-org.
Upon creating the pattern folder and associated code.md file, anything included inside of the code.md is what will be used to display on patternfly-org. Typically a code.md file includes:
- Links to jump to an example if a pattern has more than one variation
- Title of the pattern
- Example with the jekyll include reference
- Reference markup which toggles the expand/collapse for the code snippet
- Prettyprint markup using the same include from the example reference
The same classes and html structure as shown in the image above can be used for consistency purposes across code.md files.
Note: the include syntax structure for the examples are {% include widgets/{pattern-directory-name}/{html-file} %}
The patternfly-org build uses the repos/patternfly-core/tests/pages/_includes/widgets directory and ports it over to the _build/_includes/widgets directory which is how the patternfly-org _site is able to reference and include the html from patternfly-core into the code examples.
So because of this, in patternfly-core there needs to be an html file available in the tests/pages/_include/widgets directory for the particular pattern that you are trying to include on patternfly-org, or an issue will need to be a filed and PR submitted to the patternfly-core repo.
After creating your code.md file, in order to see your changes locally on patternfly-org there will need to be some changes made in the patternfly-design repo. When running the patternfly-org build, a repos folder gets generated through a grunt task which essentially clones each patternfly repo’s master branch and makes a copy of it inside of patternfly-org for reference which is also how the html for each pattern from patternfly-core is able to be included in the code examples. This can be noticed by looking inside of the _build/_includes/widgets directory in your code editor or looking at the gruntfile.js
Note: This generated folder may be hidden in some code editors, so check your editor settings. In order to test the changes made in the experimental features code.md, there will need to be some changes made inside of the site.md file of the patternfly-design repo. This can be done through the repos folder that gets generated from the build.
For the experimental features example this path would be: repos/patternfly-design/pattern-library/communication/experimental-features/site.md
The site.md of the patternfly-design repo contains all relevant information and assigned markdown files for any given pattern which is then consumed and utilized by patternfly-org to display pattern information inside of the overview, design, and code tabs on the patternfly-org website.
Each site.md contains jekyll YAML front matter which essentially is where predefined and custom variables are set and can be accessed in the layouts and pages where needed or used as includes.
In some patternfly-design site.md files you may see the variable: code: false which just means that there is no code for that pattern, but since a code.md has been created for experimental features, it can now be linked to the code_html variable.
Note: If there was a code: false variable present, this would need to be removed and replaced with code_html or the code tab on patternfly-org will be disabled and you will not be able to review your changes.
As the picture above shows, the variable code_html should then be assigned to the path containing the code.md that was created earlier. For this example the path would be: code/communication/experimental-features/code.md
Other variables you may come across:
-
impl_jquery- link to patternfly test pages example if available -
impl_angular- link to angular patternfly example if available -
impl_react- link to patternfly react example if available -
impl_ng- link to patternfly ng example if available
Once the code.md file path is assigned to the code_html variable, it should now be reflected and can be reviewed/tested as the site detects the local changes and rebuilds.
Some code examples on patternfly-org need additional information that is relevant to the pattern from a technical standpoint as in the case of the context selector, login pages, and a few others. Including some developer documentation to the patternfly-org code examples for each applicable pattern will be helpful to developers consuming the components.
For this example using the login page, a doc.md file should be created inside of source/code/application-framework/login-page/
The doc.md file should contain relevant and useful information and/or documentation that should be noted for that particular component such as the selector(s) involved, what it’s applied to, if it’s required, and a summary/general comments.
Note: Use the following html structure below as a template when setting up the doc.md:
<table class="pforg-code-usage-table">
<thead>
<tr>
<th>Selector</th>
<th>{.className}</th>
</tr>
</thead>
<tbody>
<tr>
<td>Applied to</td>
<td><code>{element}</code></td>
</tr>
<tr>
<td>Required</td>
<td><strong>{Yes/No}</strong></td>
</tr>
<tr>
<td>Summary</td>
<td>{Comments/Summary}</td>
</tr>
</tbody>
</table>
To build and preview locally go to:
repos/patternfly-design/pattern-library/application-framework/login-page/site.md the code_doc variable should be assigned to the doc.md path. The site should then detect the local changes and rebuild.
Changes should then be reflected locally and can be reviewed/tested.
Upon being satisfied with how the doc.md appears locally, changes can be saved and/or committed. Once the changes have been pushed up to your patternfly-org fork/clone, a PR can then be opened for review in the patternfly-org repo that includes the newly created doc.md file.
Note: Usage Notes and the Disclaimer are apart of the pf-org code page template and will appear with the doc.md file.
A separate PR in the patternfly-design repo will also need to be opened that includes changes to the site.md that assign the code_doc variable to the doc.md path.
Note: you may need to go back and change the site.md in the repos folder to how it was previously after commiting and finishing your review/testing or it can lead to errors with jekyll not finding the files if you create a new branch that doesn’t include the doc.md you created previously.
Some patternfly components are full pages such as the login pages and others. The steps to add the code to patternfly-org are similar to what is documented previously with some variation. Single Single On (SSO) will be used for this example.
First step is creating a html file for SSO inside of source/pattern-library/application-framework. In this example it is named: login-single-sign-on.html to match the naming convention in patternfly-core.
This file will include the jekyll YAML front matter and minimally include a:
- Title
- Author
- Layout
It will also contain an include that points to the path of the patternfly-core html file. In this example it points to: widgets/framework/login-single-sign-on.html which is essentially the same path here in patternfly-core and can be seen inside the _build/_includes/widgets directory in your code editor.
Some pages will need to include additional information such as showing/hiding submenus, icons, or javascript that the pattern is dependent on. For example the screenshot below has more variables in the front matter related to it. Essentially these html pages in pf-org are the same as the tests/pages html in patternfly-core so some may require additional front matter.
A code.md should then be created for SSO in the source/_includes/code/application-framework/single-sign-on directory. Note to always create the folder (single-sign-on for this example) for the pattern in addition to the code.md file inside of it.
When adding code examples for those components that are full pages, it will be included a bit differently than the others. The general structure of the html is still the same but inside of the <div class=”example-pf>, there is now an HTML iFrame. This is used to typically embed another html page into a current page which is good for those code examples that are full pages that need to be displayed on patternfly-org.
For patternfly-org, it generally follows this structure path:
{{ site.baseurl }}/pattern-library/[pattern-folder]/[pattern-name]/[html-file] (it points to the path of the html file created in the beginning steps). The width, height, scrolling, and seamless attributes are defined and included also as shown in the screenshot.
Under the iframe it should provide a link to the patternfly-core test page for the pattern to be viewed in its entirety. For this example it links to the SSO example on the test pages. The reference markup and pretty print include are still present as follows.
This can be viewed/tested by modifying the site.md file in the patternfly-design repos folder to include the code.md path as described in previous steps.