From 32c3bd721be8de4d1e5bef5b0f337298d8d50fba Mon Sep 17 00:00:00 2001 From: bidi Date: Fri, 11 Oct 2024 17:01:02 +0300 Subject: [PATCH 1/3] added how to pages Signed-off-by: bidi --- docs/book/v1/how-tos/create-pages.md | 82 +++++++++++++++++++ docs/book/v1/how-tos/edit-footer.md | 74 +++++++++++++++++ docs/book/v1/how-tos/edit-top-menu.md | 37 +++++++++ docs/book/v1/how-tos/manage-assets.md | 58 +++++++++++++ .../v1/how-tos/twitter-opengraph-cards.md | 28 +++++++ mkdocs.yml | 6 ++ 6 files changed, 285 insertions(+) create mode 100644 docs/book/v1/how-tos/create-pages.md create mode 100644 docs/book/v1/how-tos/edit-footer.md create mode 100644 docs/book/v1/how-tos/edit-top-menu.md create mode 100644 docs/book/v1/how-tos/manage-assets.md create mode 100644 docs/book/v1/how-tos/twitter-opengraph-cards.md diff --git a/docs/book/v1/how-tos/create-pages.md b/docs/book/v1/how-tos/create-pages.md new file mode 100644 index 0000000..b683a07 --- /dev/null +++ b/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 %} +
+
+

Add title here!

+
+
+ +
+ Add cool content here! +
+{% 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/examplePage`. + +> Because of the way routing works, you can also use `/page/example-page`. +> Dot '.', dash '-', underscore '_' are filtered from the `action` parameter in the routing `/page[/{action}]` and calls the `examplePageAction` function. diff --git a/docs/book/v1/how-tos/edit-footer.md b/docs/book/v1/how-tos/edit-footer.md new file mode 100644 index 0000000..6622cde --- /dev/null +++ b/docs/book/v1/how-tos/edit-footer.md @@ -0,0 +1,74 @@ +# Footer + +To edit the footer on all the pages, search for `
` 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 + +``` \ No newline at end of file diff --git a/docs/book/v1/how-tos/edit-top-menu.md b/docs/book/v1/how-tos/edit-top-menu.md new file mode 100644 index 0000000..0e7277f --- /dev/null +++ b/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 + +``` + +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. diff --git a/docs/book/v1/how-tos/manage-assets.md b/docs/book/v1/how-tos/manage-assets.md new file mode 100644 index 0000000..789ba76 --- /dev/null +++ b/docs/book/v1/how-tos/manage-assets.md @@ -0,0 +1,58 @@ +# 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 + +... + +``` + +> 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 + +... + +``` +> 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. diff --git a/docs/book/v1/how-tos/twitter-opengraph-cards.md b/docs/book/v1/how-tos/twitter-opengraph-cards.md new file mode 100644 index 0000000..807536c --- /dev/null +++ b/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 + + + + + + + + + + + + + + +``` + +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`. diff --git a/mkdocs.yml b/mkdocs.yml index 1504a0b..d3dc127 100644 --- a/mkdocs.yml +++ b/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" From aee50d796866e52f9322c6d3ce912b199b1926b7 Mon Sep 17 00:00:00 2001 From: bidi Date: Fri, 11 Oct 2024 17:04:59 +0300 Subject: [PATCH 2/3] linting fixes Signed-off-by: bidi --- docs/book/v1/how-tos/create-pages.md | 22 +++++++++---------- docs/book/v1/how-tos/edit-footer.md | 2 +- docs/book/v1/how-tos/manage-assets.md | 1 + .../v1/how-tos/twitter-opengraph-cards.md | 2 +- 4 files changed, 14 insertions(+), 13 deletions(-) diff --git a/docs/book/v1/how-tos/create-pages.md b/docs/book/v1/how-tos/create-pages.md index b683a07..c14e80d 100644 --- a/docs/book/v1/how-tos/create-pages.md +++ b/docs/book/v1/how-tos/create-pages.md @@ -36,7 +36,7 @@ The `content` block is where your page copy goes.
- Add cool content here! + Add cool content here!
{% endblock %} ``` @@ -62,16 +62,16 @@ If you intend to group your templates into more folders, simply add another elem > 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'], - ], - ]; - } +public function getTemplates(): array +{ + return [ + 'paths' => [ + 'page' => [__DIR__ . '/../templates/page'], + 'how-tos' => [__DIR__ . '/../templates/how-tos'], + 'info' => [__DIR__ . '/../templates/data'], + ], + ]; +} ``` ## Accessing the page diff --git a/docs/book/v1/how-tos/edit-footer.md b/docs/book/v1/how-tos/edit-footer.md index 6622cde..2bd0cb1 100644 --- a/docs/book/v1/how-tos/edit-footer.md +++ b/docs/book/v1/how-tos/edit-footer.md @@ -71,4 +71,4 @@ It also contains the copyright row.
-``` \ No newline at end of file +``` diff --git a/docs/book/v1/how-tos/manage-assets.md b/docs/book/v1/how-tos/manage-assets.md index 789ba76..e043f6f 100644 --- a/docs/book/v1/how-tos/manage-assets.md +++ b/docs/book/v1/how-tos/manage-assets.md @@ -54,5 +54,6 @@ Whenever you commit changes to those files, make sure to increase the value of t ... ``` + > 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. diff --git a/docs/book/v1/how-tos/twitter-opengraph-cards.md b/docs/book/v1/how-tos/twitter-opengraph-cards.md index 807536c..bcfb222 100644 --- a/docs/book/v1/how-tos/twitter-opengraph-cards.md +++ b/docs/book/v1/how-tos/twitter-opengraph-cards.md @@ -24,5 +24,5 @@ Make sure to update all items based on your page content. 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 `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`. From 9ad2188c11a146fa06d2cfd819416e3ce90dd7aa Mon Sep 17 00:00:00 2001 From: bidi Date: Fri, 11 Oct 2024 17:21:30 +0300 Subject: [PATCH 3/3] updated create pages Signed-off-by: bidi --- docs/book/v1/how-tos/create-pages.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/book/v1/how-tos/create-pages.md b/docs/book/v1/how-tos/create-pages.md index c14e80d..b64c310 100644 --- a/docs/book/v1/how-tos/create-pages.md +++ b/docs/book/v1/how-tos/create-pages.md @@ -76,7 +76,7 @@ public function getTemplates(): array ## Accessing the page -The url for the new page in this example is `/page/examplePage`. +The url for the new page in this example is `/page/example-page`. -> Because of the way routing works, you can also use `/page/example-page`. -> Dot '.', dash '-', underscore '_' are filtered from the `action` parameter in the routing `/page[/{action}]` and calls the `examplePageAction` function. +> 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.