Merge pull request #2 from dotkernel/howto

Howto pages

docs/book/v1/how-tos/create-pages.md

@@ -0,0 +1,82 @@
+# Creating pages
+
+## The `action` function
+
+The first step is to add the new pages in `src/Page/src/Controller/PageController.php`.
+This means adding an `Action` function for each page, as seen below.
+
+```php
+    public function examplePageAction(): ResponseInterface
+    {
+        return new HtmlResponse(
+            $this->template->render('page::example-template')
+        );
+    }
+```
+
+## The page content
+
+Each page has its own template, so the next step is to create the template files in the `src/Page/templates/page/` folder.
+For the example above, the `src/Page/templates/page/example-template.html.twig` file was created.
+We won't include the entire code here, just the basic building blocks.
+The `content` block is where your page copy goes.
+
+```twig
+{% extends '@layout/default.html.twig' %}
+
+{% block title %}Page Title{% endblock %}
+
+{% block page_title %}{% endblock %}
+
+{% block content %}
+    <div class="page-intro">
+        <div class="container">
+            <h2>Add title here!</h2>
+        </div>
+    </div>
+
+    <div>
+        Add cool content here!
+    </div>
+{% endblock %}
+```
+
+### Grouping templates
+
+The default grouping is under the `page` folder.
+This item is defined in `src/Page/src/ConfigProvider.php` in `getTemplates()`, like seen below.
+
+```php
+    public function getTemplates(): array
+    {
+        return [
+            'paths' => [
+                'page' => [__DIR__ . '/../templates/page'],
+            ],
+        ];
+    }
+```
+
+If you intend to group your templates into more folders, simply add another element under `paths`.
+
+> It's not necessary to match the key name with the folder name.
+
+```php
+public function getTemplates(): array
+{
+    return [
+        'paths' => [
+            'page'    => [__DIR__ . '/../templates/page'],
+            'how-tos' => [__DIR__ . '/../templates/how-tos'],
+            'info'    => [__DIR__ . '/../templates/data'],
+        ],
+    ];
+}
+```
+
+## Accessing the page
+
+The url for the new page in this example is `/page/example-page`.
+
+> Because of the way routing works, dot (.), dash (-), underscore (_) are filtered from the `action` parameter in the routing `/page[/{action}]`.
+> As a result, the `examplePageAction` function in called.

docs/book/v1/how-tos/edit-footer.md

@@ -0,0 +1,74 @@
+# Footer
+
+To edit the footer on all the pages, search for `<footer class="app-footer">` in the `src/App/templates/layout/default.html.twig` template.
+The content is usually basic `HTML` and `CSS` with `twig`.
+
+Below is an example of a footer that groups urls under two categories and columns.
+It also contains the copyright row.
+
+```twig
+<footer class="app-footer">
+    <div class="container container-border">
+        <div class="row">
+            <div class="col-md-9">
+                <div class="footer_head">
+                    <h2>Category 1</h2>
+                </div>
+                <div class="row">
+                    <div class="col-md-6 dk_widget">
+                        <p class="footer-item-title">
+                            Column 1
+                        </p>
+                        <p class="footer-item-link margin-small">
+                            <a href="https://first.example.com/" target="_blank">
+                                <img src="{{ asset('images/app/icon/hand.svg') }}">
+                                First Link
+                            </a>
+                        </p>
+                        <p class="footer-item-link margin-small">
+                            <a href="https://second.example.com/" target="_blank">
+                                <img src="{{ asset('images/app/icon/hand.svg') }}">
+                                Second Link
+                            </a>
+                        </p>
+                    </div>
+                    <div class="col-md-6 dk_widget">
+                        <p class="footer-item-title">
+                            Column 2
+                        </p>
+                        <p class="footer-item-link margin-large">
+                            <a href="https://third.example.com/" target="_blank">
+                                <img src="{{ asset('images/app/icon/hand.svg') }}">
+                                Third Link
+                            </a>
+                        </p>
+                    </div>
+                </div>
+            </div>
+            <div class="col-md-3">
+                <div class="footer_head">
+                    <h2>Category 2</h2>
+                </div>
+                <p class="footer-item-support margin-small">
+                    <a href="https://fourth.example.com/" target="_blank">
+                        <img src="{{ asset('images/app/icon/hand.svg') }}">
+                        Fourth Link
+                    </a>
+                </p>
+                <p class="footer-item-support margin-small">
+                    <a href="https://fifth.example.com/" target="_blank">
+                        <img src="{{ asset('images/app/icon/hand.svg') }}">
+                        Fifth Link
+                    </a>
+                </p>
+            </div>
+        </div>
+
+        <div class="row">
+            <p class="footer-headline">
+                © {{ 'now' | date('Y') }} by <a href="{{ url('home') }}">My Project</a>
+            </p>
+        </div>
+    </div>
+</footer>
+```

docs/book/v1/how-tos/edit-top-menu.md

@@ -0,0 +1,37 @@
+# Edit the top menu
+
+The top menu is displayed on all the pages, in the header.
+To edit it, go to `src/App/templates/layout/default.html.twig` and update the items under `id="navbarHeader"`.
+
+You can use the below as an example.
+
+```twig
+<div class="menu" id="navbarHeader">
+    <ul class="navbar-nav mr-auto">
+      <li class="nav-item dropdown">
+        <a class="nav-link dropdown-toggle" href="#" id="pageDropdown" data-bs-toggle="dropdown" aria-haspopup="true" aria-expanded="false">Grouped Pages</a>
+        <div class="dropdown-menu" aria-labelledby="pageDropdown">
+          <a class="dropdown-item" href="{{ url('page', {action: 'home'}) }}">Home</a>
+          <a class="dropdown-item" href="https://www.example.com/docs">Docs</a>
+        </div>
+      </li>
+      <li class="nav-item">
+          <a class="nav-link" target="_blank" href="{{ url('page', {action: 'firstLink'}) }}">First Link</a>
+      </li>
+      <li class="nav-item">
+          <a class="nav-link" target="_blank" href="https://second.example.com/">Second Link</a>
+      </li>
+    </ul>
+</div>
+```
+
+Each `li` element is listed as an item in the top menu.
+
+There are two different types of elements in the example:
+
+- The `Grouped Pages` group several urls.
+When you click on the item, the elements grouped under it are listed and can be accessed.
+They can be internal and/or external links.
+- The `First Link` and `Second Link` are regular links, one an internal link and the other an external one.
+
+> You can also replace the `nav-item` class for the `li` elements with `button-border` for a link that looks more like a button.

docs/book/v1/how-tos/manage-assets.md

@@ -0,0 +1,59 @@
+# Manage Assets
+
+If you haven't already done so, make sure `npm` is installed.
+You can keep it running during your updates with `npm run watch` or run this command after the edits are completed `npm run prod`.
+
+## What are assets?
+
+Assets are various files used by your content:
+
+- Images,
+- Fonts,
+- JavaScript codes,
+- SCSS.
+
+## Assets source and destination
+
+The source of these files is the `src/App/assets/` folder:
+
+- src/App/assets/images
+- src/App/assets/fonts
+- src/App/assets/js
+- src/App/assets/scss
+
+The `npm` script processes these files and copies or builds files under the `public` folder.
+
+> You should not manage the items from the above folders manually.
+> The `npm` script will delete/replace the files when run.
+
+While the `images` and `fonts` folders are copied as is, the `js` and `scss` are minimized:
+
+- `scss` files are minimized under `public/js/app.css`.
+- `js` files are minimized under `public/js/app.js`.
+
+The above items are by default used in the `src/App/templates/layout/default.html.twig` file.
+
+```twig
+<link href="{{ asset('css/app.css') }}" rel="stylesheet" />
+...
+<script src="{{ asset('js/app.js') }}"></script>
+```
+
+> The source and destination folders are configured in the `webpack.config.js` file.
+
+## Browser caching of `js` and `css`
+
+One thing of note is that browsers cache the `js` and `css` files.
+When you push changes to one or both the files, you may notice that updating the site keeps the old version of the files.
+
+A simple solution to force the browsers to download the newer version of the files is to add a version parameter in the url.
+Whenever you commit changes to those files, make sure to increase the value of the `v` parameter.
+
+```twig
+<link href="{{ asset('css/cls_dk.css?v=3') }}" rel="stylesheet" />
+...
+<script src="{{ asset('js/cls_dk.js?v=5') }}"></script>
+```
+
+> The values 3 and 5 are provided as an example.
+> The important thing is to use values for each file that you haven't used before, so incrementing the value for `v` is a simple way to track each change.

docs/book/v1/how-tos/twitter-opengraph-cards.md

@@ -0,0 +1,28 @@
+# Twitter and OpenGraph cards
+
+If you want to promote your pages on other platforms, you can post Twitter (X) and OpenGraph cards in the header section in the `src/App/templates/layout/default.html.twig` file.
+
+Make sure to update all items based on your page content.
+
+```twig
+<!-- Twitter card -->
+<meta name="twitter:card" content="summary_large_image">
+<meta name="twitter:site" content="@example">
+<meta name="twitter:title" content="Page title">
+<meta name="twitter:description" content="Basic description">
+<meta name="twitter:image" content="{{ url('home') }}images/app/My-image.png">
+<meta name="twitter:image:alt" content="Image alt">
+
+<!-- OpenGraph card -->
+<meta property="og:title" content="Page title"/>
+<meta property="og:type" content="website"/>
+<meta property="og:url" content="{{ url('home') }}"/>
+<meta property="og:image" content="{{ url('home') }}images/app/My-image.png"/>
+<meta property="og:description" content="Basic description"/>
+```
+
+In the example:
+
+- {{ url('home') }} is the URL for the homepage, but you can also use this code to generate the url for other pages, just like in the canonical URL `{% block canonical %}{{ url(routeName ?? null) }}{% endblock %}`.
+    - The `block` item is present to mitigate for not-found pages, e.g. when the url is typed incorrectly.
+- The image from `{{ url('home') }}images/app/My-image.png` is found in `public/images/app/PHP-REST-API.png`, but it is copied there by the `npm` script from `src/App/assets/images/PHP-REST-API.png`.

mkdocs.yml

@@ -22,6 +22,12 @@ nav:
           - "FAQ": v1/installation/faq.md
       - Core Features:
           - "NPM Commands": v1/core-features/npm-commands.md
+      - How tos:
+          - "Create Pages": v1/core-features/create-pages.md
+          - "Set Up Twitter and OpenGraph Cards": v1/core-features/twitter-opengraph-cards.md
+          - "Edit the Top Menu": v1/core-features/edit-top-menu.md
+          - "Edit the Footer": v1/core-features/edit-footer.md
+          - "Manage Assets": v1/core-features/manage-assets.md
 site_name: light
 site_description: "DotKernel Light"
 repo_url: "https://github.com/dotkernel/light"