Running the Website
The UI5 Web Components Website app is the entry point of the UI5 Web Components project. The app includes documentation, API reference and samples for all the available web components.
The website can be run locally to test your changes and samples. In order to do so, you have to follow the steps below:
In your terminal, run the following commands:
yarn
yarn start:website
This will build all the necessary assets and will start local server on your machine and finally open the website in your browser.
Creating Website Samples
The website app is developed in its own package packages/website
. Components features or states are demonstrated via samples meant for consumers.
The samples are placed in the /packages/website/docs/_samples
folder.
For example:
The Button samples can be found in the /packages/website/docs/_samples/main/Button
folder.
Run the Website​
Runs project build + website start.
yarn start:website
However, in most cases you have the project built, so it would be faster to just start the website:
cd packages/website
yarn start
Note: In case of issues with the second flow, most likely you need yarn build
in the root.
Create New Sample​
A regular component sample consists of a folder + 3 files ({sample_name}.md
, main.js
and sample.html
) that you need to create. Let's go trough every one of them:
The main.js
file​
In the main.js
file, we import the components and assets (icons, illustration) required by the sample.
For example:
import "@ui5/webcomponents/dist/Button.js";
import "@ui5/webcomponents-icons/dist/edit.js";
import "@ui5/webcomponents-icons/dist/account.js";
The sample.html
file​
In the sample.html
file, we use the web components as in regular HTML page.
For example:
<!-- playground-fold -->
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<title>Sample</title>
</head>
<body style="background-color: var(--sapBackgroundColor)">
<!-- playground-fold-end -->
<ui5-button icon="sap-icon://edit" design="Default" tooltip="Edit Button"></ui5-button>
<ui5-button icon="sap-icon://account" design="Transparent" tooltip="Account Button"></ui5-button>
<!-- playground-fold -->
<script type="module" src="main.js"></script>
</body>
</html>
<!-- playground-fold-end -->
Note: The playground-fold
comments will fold this part of the code to highlight the important part - the components usage.
The {sample_name}.md
file​
In the .md
file we instantiate the Editor
component (file editor + preview) that will display your sample and show the code behind it.
For example:
import html from '!!raw-loader!./sample.html';
import js from '!!raw-loader!./main.js';
<Editor html={html} js={js} />
Show the Sample​
In the previous step we have created our sample. Now, it's time to show and document it.
-
Open the
packages/website/docs/_components_pages
folder. -
Find your component's
.mdx
file.
For example: packages/website/docs/_components_pages/main/Button.mdx
- Import the newly created sample.
For example:
import MyNewSample from "../../_samples/main/Button/MyNewSample/MyNewSample.md";`
- Instantiate the sample and add title + description.
For example:
### My New Sample
The Button supports several designs to indicate the priority or the nature of the action.
<MyNewSample />
Note: Changes in the sample files (.md
, .html
, .js
) are detected and the server reloads. However, changes in the .mdx
file are not watched - restart of the server is needed.
Conventions​
Sample Name​
-
The sample name and the folder that includes the sample files should match the
.md
file name (Button/IconOnly/IconOnly.md
). -
Regarding the naming, it's best to consult with KM and use existing ones as reference.
Sample Title and Description​
The title ("My New Sample") and the description ("The Button..") will be displayed at the top of the sample itself. Adding title and description is recommended - they help viewers better understand what they are looking at.
Sample Order​
Add new samples in the "More Samples" section where it best fits among the existing samples.
The "Basic" Sample​
All components have a sample called "Basic" used as the first sample displayed right-after the component's overview. Don't use "Basic" for other samples.