diff --git a/docs/.nojekyll b/docs/.nojekyll new file mode 100644 index 0000000..e69de29 diff --git a/docs/README.md b/docs/README.md new file mode 100644 index 0000000..76dc5c8 --- /dev/null +++ b/docs/README.md @@ -0,0 +1,147 @@ +

+ Marten Turbo Logo + Marten Turbo +

+ +[![GitHub Release](https://img.shields.io/github/v/release/treagod/marten-turbo?style=flat)](https://github.com/treagod/marten-turbo/releases) +[![Marten Turbo Specs](https://github.com/treagod/marten-turbo/actions/workflows/specs.yml/badge.svg)](https://github.com/treagod/marten-turbo/actions/workflows/specs.yml) +[![QA](https://github.com/treagod/marten-turbo/actions/workflows/qa.yml/badge.svg)](https://github.com/treagod/marten-turbo/actions/workflows/qa.yml) + +Marten Turbo provides helpers to interact with Turbo applications using the Marten Framework. + +## Installation + +Simply add the following entry to your project's `shard.yml`: + +```yaml +dependencies: + marten_turbo: + github: treagod/marten-turbo +``` + +And run `shards install` afterward. + +First, add the following requirement to your project's `src/project.cr` file: + +```crystal +require "marten_turbo" +``` + +Afterwards you can use the template helper `dom_id` and the turbo handlers. + +## Tags + +Marten Turbo introduces a new template tag `dom_id`, which supports the creation of turbo frame ids for Marten models + +```html +{% for article in articles %} +
+ +
+{% endfor %} + +
+ + +
+``` + +Identifier will respect your namespace of the model. I.e. if you have an Article model in the app blogging the generated id will be `blogging_article_1`. + +Marten Turbo also provides a turbo stream tag helper + +```html +{% turbo_stream 'append' "articles" do %} +
+ {{ article.name }} +
+{% end_turbo_stream %} + + + + +{% turbo_stream 'append' "articles" template: "articles/article.html" %} + + + +{% turbo_stream 'remove' article %} + +``` + + +## Handlers + +Marten Turbo provides an extension to the generic Marten handlers: + +__Record Creation__: To create a record, use + +```crystal +class ArticleCreateHandler < MartenTurbo::Handlers::RecordCreate + model Article + schema ArticleSchema + template_name "articles/create.html" + turbo_stream_name "articles/create.turbo_stream.html" + success_route_name "articles" +end +``` + +Notice how we use `MartenTurbo::Handlers::RecordCreate` instead of `Marten::Handlers::RecordCreate`. +Also the `#turbo_stream_name` class method gives you the option to define a turbo stream template which is +rendered instead of the normal template if a turbo request is made. + +__Record Update__: To update a record, use + +```crystal +class ArticleUpdateHandler < MartenTurbo::Handlers::RecordUpdate + model Article + schema ArticleSchema + template_name "articles/update.html" + turbo_stream_name "articles/update.turbo_stream.html" + success_route_name "articles" +end +``` + +__Record Deletion__: It's also possible to define a `turbo_stream` method + +```crystal +class ArticleDeleteHandler < MartenTurbo::Handlers::RecordDelete + model Article + template_name "articles/delete.html" + success_route_name "articles" + + def turbo_stream + MartenTurbo::TurboStream.remove(record) + end +end +``` + +## Turbo Native + +Marten Turbo lets you check if a request is from a Turbo Native Application. To check, just check the `request.turbo_native_app?` variable. + +A context producer also adds the `turbo_native?` variable to your templates to adjust your HTML. For the context producer you have to insert `MartenTurbo::Template::ContextProducer::TurboNative` into your context producer array. + +You could add a custom class to your body if a turbo native app hits your application: + +```html + + … + +``` diff --git a/docs/_navbar.md b/docs/_navbar.md new file mode 100644 index 0000000..d589529 --- /dev/null +++ b/docs/_navbar.md @@ -0,0 +1,4 @@ +* [Overview](/) +* [Installation](installation.md) +* [Usage](usage.md) +* [Changelog](changelog.md) diff --git a/docs/changelog.md b/docs/changelog.md new file mode 100644 index 0000000..09e56e4 --- /dev/null +++ b/docs/changelog.md @@ -0,0 +1,45 @@ +# Changelog + +All notable changes to this project will be documented in this file. + +The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/), and this project adheres to [Semantic Versioning](https://semver.org/). + +## [Unreleased] + +### Added +- `MartenTurbo::TurboStream.new` now accepts a block which can be used to create multiple stream tags. + +### Changed +- `dom_id` is now more general and accepts `Marten::Model` or anything that responds to `#to_s`. + +### Deprecated +- Renamed `create_dom_id` to `dom_id` to better fit the template tag naming convention. + +## [0.2.1] - 2024-06-17 + +### Fixed +- `TurboStream` can now correctly create target IDs from a `Marten::Model`. + +## [0.2.0] - 2024-06-13 + +### Added +- New `MartenTurbo::TurboStream` class: Introduced a new `TurboStream` class to streamline the creation of Turbo Streams. This class provides a convenient API to generate various Turbo Stream actions. +- Turbo Handlers Enhancement: Turbo handlers now support a `turbo_stream` method. This method should return a string that will be rendered instead of a template. It takes precedence over the `turbo_stream_name` attribute, offering greater flexibility in handling Turbo Stream responses. +- `MartenTurbo::Handlers::TurboFrame` concern: Added a new concern, TurboFrame, which can be included to track Turbo-Frame requests. This enhancement simplifies the detection and handling of Turbo Frame specific requests. This adds the `turbo_frame_request?` and `turbo_frame_request_id` methods to your handler. + +### Changed +- `RecordDelete` Enhancement: The `RecordDelete` handler now forwards a `DELETE` request to post, improving consistency and reliability in handling delete operations. + +### Breaking Changes +- End Tag Update: The end tag for Turbo Streams has been updated from `{% end_turbostream %}` to `{% end_turbo_stream %}`. This change aligns the syntax with Marten’s end tags, enhancing readability and consistency across the codebase. + +## [0.1.1] - 2024-03-20 + +### Changed +- Updated shard name. + +## [0.1.0] - 2024-03-20 + +### Added +- Initial release of Marten Turbo. +- Handlers for record creation, updating, and deletion with Turbo Streams. diff --git a/docs/index.html b/docs/index.html new file mode 100644 index 0000000..64cacf7 --- /dev/null +++ b/docs/index.html @@ -0,0 +1,28 @@ + + + + + Document + + + + + + + +
+ + + + + diff --git a/docs/installation.md b/docs/installation.md new file mode 100644 index 0000000..4ee809f --- /dev/null +++ b/docs/installation.md @@ -0,0 +1,45 @@ +# Installation + +## Prerequisites + +Before you begin, ensure you have the following installed: + +- **Crystal** programming language: [Installation Guide](https://crystal-lang.org/install/) +- **Marten Framework**: Make sure your project is set up with the Marten framework. + +## Installation Steps + +To install Marten Turbo in your project, follow these steps: + +1. **Update your `shard.yml` file:** + +Add the following dependency to your `shard.yml` file: + +```yaml +dependencies: + marten_turbo: + github: treagod/marten-turbo +``` + +2. **Install the dependencies:** + +After updating shard.yml, run the following command to install the dependencies: + +```bash +shards install +``` + +3. **Add Marten Turbo to your project:** + +In your main project file (usually src/project.cr), require the Marten Turbo library by adding the following line: + +```crystal +require "marten_turbo" +``` + +## Post-Installation + +Once the installation is complete, you can start using Marten Turbo’s features in your project. For example, you can now use the `dom_id` template helper and Turbo handlers in your Marten framework application. + + +For detailed usage instructions, refer to the [Usage Guide](usage.md). diff --git a/docs/usage.md b/docs/usage.md new file mode 100644 index 0000000..4d7c51e --- /dev/null +++ b/docs/usage.md @@ -0,0 +1,142 @@ +# Usage + +## Template Helpers + +Marten Turbo provides a `dom_id` template helper, which simplifies generating unique DOM IDs for your elements. This is especially useful when working with Turbo Streams. + +### Example Usage + +To generate a unique DOM ID for an `article` object, you can use the following syntax in your template: + +```html +
+ +
+``` + +If the article object is new and does not yet have an ID, the `dom_id` helper will generate an ID like new_article. + +### Namespacing + +The `dom_id` will respect the namespace of your model. For example, if your `Article` model is within a Blogging namespace, the generated ID would be blogging_article_1. + +```html +
+ +
+``` + +## Turbo Stream Helpers + +Marten Turbo also provides helpers to work with Turbo Streams, allowing you to update parts of your page dynamically. + +### Example: Appending Content + +To append content to an existing element with the ID articles, you can use the turbo_stream helper like this: + +```html +{% turbo_stream 'append' "articles" do %} +
+ {{ article.name }} +
+{% end_turbo_stream %} +```` + +This will generate the following HTML: + +```html + + + +``` + +### Example: Removing Content + +To remove an element corresponding to a specific article, you can use: + +```html +{% turbo_stream 'remove' article %} +``` + +This will generate: + +```html + + +``` + +## Handlers + +Marten Turbo extends the generic Marten handlers to work seamlessly with Turbo Streams. Here’s how to use them for common tasks. + +### Record creation + +To create a record and handle Turbo Stream responses, use the `MartenTurbo::Handlers::RecordCreate` handler: + +```crystal +class ArticleCreateHandler < MartenTurbo::Handlers::RecordCreate + model Article + schema ArticleSchema + template_name "articles/create.html" + turbo_stream_name "articles/create.turbo_stream.html" + success_route_name "articles" +end +``` + +### Record Update + +Similarly, to update a record: + +```crystal +class ArticleUpdateHandler < MartenTurbo::Handlers::RecordUpdate + model Article + schema ArticleSchema + template_name "articles/update.html" + turbo_stream_name "articles/update.turbo_stream.html" + success_route_name "articles" +end +``` + +### Record deletion + +For record deletion, you could define a custom `turbo_stream` method to avoid creating a single file for a short stream tag: + +```crystal +class ArticleDeleteHandler < MartenTurbo::Handlers::RecordDelete + model Article + template_name "articles/delete.html" + success_route_name "articles" + + def turbo_stream + MartenTurbo::TurboStream.remove(record) + end +end +``` + +## Turbo Native + +Marten Turbo allows you to detect requests from Turbo Native applications easily. + +### Checking for Turbo Native Requests + +You can check if a request comes from a Turbo Native app by using the `request.turbo_native_app?` method: + +```crystal +if request.turbo_native_app? + # Handle Turbo Native request +end +``` + +You can also adjust your HTML templates based on whether the request is from a Turbo Native app: + +```html + + + +``` + +This allows you to tailor your application’s behavior and appearance specifically for Turbo Native applications.