From 53758f240e38dcf7207130755e53cd85ba6b7c84 Mon Sep 17 00:00:00 2001 From: Robert Landers Date: Thu, 12 Oct 2023 17:57:27 +0200 Subject: [PATCH] update documentation --- docs/README.md | 267 +++++++++++++++-------------------- src/Template/Traits/Htmx.php | 1 - 2 files changed, 112 insertions(+), 156 deletions(-) diff --git a/docs/README.md b/docs/README.md index 0246c84..97a6a89 100644 --- a/docs/README.md +++ b/docs/README.md @@ -9,7 +9,8 @@ while writing regular HTML and PHP, powered by [htmx](https://htmx.org/). The easiest way to get started is to use the [Swytch Template](https://github.com/bottledcode/swytch-template/generate). This is a ready-to-go template that you can use to get started with the Swytch Framework. -The template includes a `Dockerfile` that you can use to build and run your application. +The template includes a `Dockerfile` that you can use to build and run your application or as a template for how an +environment could be configured. ### The Index Component @@ -20,36 +21,35 @@ Every Swytch project requires a 'root component' and in this template, the root #[Component('index')] readonly class Index { - use RegularPHP; + use RegularPHP; - public function __construct( - private LanguageAcceptor $language, - private HeadTagFilter $htmlHead - ) {} + public function __construct(private LanguageAcceptor $language, private HeadTagFilter $htmlHead) + { + } - public function render() - { - $this->htmlHead->setTitle('Hello World'); + public function render() + { + $this->htmlHead->setTitle(__('Hello World')); - $this->begin(); - ?> + $this->begin(); + ?> - + -

Hello world

+

{}

- + -

404

+

{}

 - end(); - } + end(); + } } ``` @@ -64,54 +64,67 @@ The example `counter` component is a simple component that allows 'counting' a v #[Component('counter')] readonly class Counter { - use RegularPHP; - use Htmx; - - public function __construct( - private Headers $headers, - private Compiler $compiler - ) {} - - #[Route(Method::POST, '/api/count/add')] - public function add(int $count): string - { - return $this->render($count + 1); - } - - #[Route(Method::POST, '/api/count/sub')] - public function sub(int $count): string - { - return $this->render($count + 1); - } - - public function render(int $count = 0) - { - $this->begin(); - ?> -
-
- -

{} {}

- - -
+ use RegularPHP; + use Htmx; + + public function __construct(private Headers $headers, private StreamingCompiler $compiler) + { + } + + /** + * In real life, you would probably do a lot more in here. But this just show how it works. + * + * @param int $count The current count + * @return string The rendered HTML + */ + #[Route(Method::POST, '/api/count/add')] + public function add(int $count): string + { + // we want to place the fragment in the #count div + $this->retarget('#count'); + // now rerender the component but only the fragment with the id count-from + return $this->renderFragment('count-form', $this->render($count + 1)); + } + + public function render(int $count = 0) + { + $this->begin(); + ?> +
+ + +
+ +

{} {}

+ + +
+
- end(); - } + end(); + } + + #[Route(Method::POST, '/api/count/sub')] + public function sub(int $count): string + { + $this->retarget('#count'); + return $this->renderFragment('count-form', $this->render($count - 1)); + } } ``` ## What is this? The Swytch Framework was created out of frustration with having to create a front-end and back-end for every project. -Why not write it once? This framework will allow you to write you front-end and back-end in the same language, provide -an API for non-browser clients, and allow you to deliver value faster than ever. +Why not write it once in the same language? This framework will allow you to write you front-end and back-end in not +Javascript, provide an API for non-browser clients, and allow you to deliver value faster than ever. ## How does it work? Unlike other PHP frameworks with a dedicated templating language, the Swytch Framework's templatating language is HTML5. -Thus you can take advantage of PHP's built-in templating functionality to create your app. The browser side is powered +Thus, you can take advantage of PHP's built-in templating functionality to create your app. The browser side is powered by [htmx](https://htmx.org/). ## Escaping, CSRF, and Security @@ -164,12 +177,13 @@ class Example { } ``` -API endpoints also use the Symfony serializer so you can accept complex types as parameters that are composed via route -parameters and body parameters. +API endpoints also use the Symfony serializer, so you can accept complex types as parameters that are composed via route +parameters and body parameters. Note that API endpoints are expected to begin with `/api/`. This is currently a +hard-coded requirement; please open an issue if you have a use-case that requires this to be configurable. ## Context-Aware Escaping -The Swytch Framework automatically escapes all output inside `{` brackets `}` in your HTML. It is fully context-aware, +The Swytch Framework automatically escapes all output inside `{` brackets `}` in your output. It is fully context-aware, so it automatically knows to escape Javascript inside `