+
+
@@ -40,4 +46,7 @@ Marten provides various tools and mechanisms that you can leverage in order to d
+
+
diff --git a/docs/versioned_docs/version-0.1/development/applications.md b/docs/versioned_docs/version-0.4/development/applications.md
similarity index 75%
rename from docs/versioned_docs/version-0.1/development/applications.md
rename to docs/versioned_docs/version-0.4/development/applications.md
index 389ff5293..73e4dba9e 100644
--- a/docs/versioned_docs/version-0.1/development/applications.md
+++ b/docs/versioned_docs/version-0.4/development/applications.md
@@ -4,11 +4,11 @@ description: Learn how to leverage applications to structure your projects.
sidebar_label: Applications
---
-Marten projects can be organized into logical and reusable components called "applications". These applications can contribute specific behaviors and abstractions to a project, including [models](../models-and-databases.mdx), [handlers](../handlers-and-http.mdx), and [templates](../templates.mdx). They can be packaged and reused across various projects as well.
+Marten projects can be organized into logical and reusable components called "applications". These applications can contribute specific behaviors and abstractions to a project, including [models](../models-and-databases.mdx), [handlers](../handlers-and-http.mdx), [schemas](../schemas/introduction.md), [emails](../emailing/introduction.md), and [templates](../templates.mdx). They can be packaged and reused across various projects as well.
## Overview
-A Marten **application** is a set of abstractions (defined under a dedicated and unique folder) that provides some set of features. These abstractions can correspond to [models](../models-and-databases.mdx), [handlers](../handlers-and-http.mdx), [templates](../templates.mdx), [schemas](../schemas.mdx), etc.
+A Marten **application** is a set of abstractions (defined under a dedicated and unique folder) that provides some set of features. These abstractions can correspond to [models](../models-and-databases.mdx), [handlers](../handlers-and-http.mdx), [templates](../templates.mdx), [schemas](../schemas.mdx), [emails](../emailing/introduction.md), etc.
Marten projects always use one or many applications. Indeed, each Marten project comes with a default [main application](#the-main-application) that corresponds to the standard `src` folder: models, migrations, or other classes defined in this folder are associated with the main application by default (unless they are part of another _explicitly defined_ application). As projects grow in size and scope, it is generally encouraged to start thinking in terms of applications and how to split models, handlers, or features across multiple apps depending on their intended responsibilities.
@@ -18,7 +18,7 @@ Another benefit of applications is that they can be packaged and reused across m
The use of applications must be manually enabled within projects: this is done through the use of the [`installed_apps`](./reference/settings.md#installedapps) setting.
-This setting corresponds to an array of installed app classes. Indeed, each Marten application must define a subclass of [`Marten::App`](pathname:///api/0.1/Marten/App.html) to specify a few things such as the application label (see [Creating applications](#creating-applications) for more information about this). When those subclasses are specified in the `installed_apps` setting, the applications' models, migrations, assets, and templates will be made available to the considered project.
+This setting corresponds to an array of installed app classes. Indeed, each Marten application must define a subclass of [`Marten::App`](pathname:///api/0.4/Marten/App.html) to specify a few things such as the application label (see [Creating applications](#creating-applications) for more information about this). When those subclasses are specified in the `installed_apps` setting, the applications' models, migrations, assets, and templates will be made available to the considered project.
For example:
@@ -60,16 +60,17 @@ This is why it is always important to _namespace_ abstractions, assets, template
## Creating applications
-Creating applications can be done very easily through the use of the [`new`](./reference/management-commands.md#new) management command. For example:
+Creating applications can be done very easily through the use of the [`app`](./reference/generators.md#app) generator. For example:
```bash
-marten new app blog src/blog
+marten gen app blog
```
-Running such a command will usually create the following directory structure:
+Running such a command will add a new `blog` application to the current project with the following structure:
```
src/blog
+├── emails
├── handlers
├── migrations
├── models
@@ -83,21 +84,33 @@ These files and folders are described below:
| Path | Description |
| ----------- | ----------- |
-| handlers/ | Empty directory where the request handlers of the application will be defined. |
-| migrations/ | Empty directory that will store the migrations that will be generated for the models of the application. |
-| models/ | Empty directory where the models of the application will be defined. |
-| schemas/ | Empty directory where the schemas of the application will be defined. |
-| templates/ | Empty directory where the templates of the application will be defined. |
-| app.cr | Definition of the application configuration abstraction; this is also where application files requirements should be defined. |
-| cli.cr | Requirements of CLI-related files, such as migrations for example. |
+| `emails/` | Empty directory where the [emails](../emailing/introduction.md) of the application will be defined. |
+| `handlers/` | Empty directory where the [request handlers](../handlers-and-http/introduction.md) of the application will be defined. |
+| `migrations/` | Empty directory that will store the [migrations](../models-and-databases/migrations.md) that will be generated for the models of the application. |
+| `models/` | Empty directory where the [models](../models-and-databases/introduction.md) of the application will be defined. |
+| `schemas/` | Empty directory where the [schemas](../schemas/introduction.md) of the application will be defined. |
+| `templates/` | Empty directory where the [templates](../templates/introduction.md) of the application will be defined. |
+| `app.cr` | Definition of the application configuration abstraction; this is also where application-specific file requirements should be made. |
+| `cli.cr` | Requirements of CLI-related files, such as migrations for example. |
+| `routes.cr` | Module containing the [routes](../handlers-and-http/routing.md) of the application. |
+
+:::tip
+The [`app`](./reference/generators.md#app) generator automatically ensures that:
+
+* The newly created application is added to the [`installed_apps`](./reference/settings.md#installed_apps) setting.
+* Requirements for the application itself are added to the `src/project.cr` and `src/cli.cr` files.
+* The application's routes are included in the main routes map (which lives in the `config/routes.cr` file).
+:::
-The most important file of an application is the `app.cr` one. This file usually includes all the app requirements and defines the application configuration class itself, which must be a subclass of the [`Marten::App`](pathname:///api/0.1/Marten/App.html) abstract class. This class allows mainly to define the "label" identifier of the application (through the use of the [`#label`](pathname:///api/0.1/Marten/Apps/Config.html#label(label%3AString|Symbol)-class-method) class method): this identifier must be unique across all the installed applications of a project and is used to generate things like model table names or migration classes.
+The most important file of an application is the `app.cr` one. This file usually includes all the app requirements and defines the application configuration class itself, which must be a subclass of the [`Marten::App`](pathname:///api/0.4/Marten/App.html) abstract class. This class allows mainly to define the "label" identifier of the application (through the use of the [`#label`](pathname:///api/0.4/Marten/Apps/Config.html#label(label%3AString|Symbol)-class-method) class method): this identifier must be unique across all the installed applications of a project and is used to generate things like model table names or migration classes.
Here is an example `app.cr` file content for a hypothetic "blog" app:
```crystal
+require "./emails/**"
require "./handlers/**"
require "./models/**"
+require "./routes"
require "./schemas/**"
module Blog
diff --git a/docs/versioned_docs/version-0.4/development/generators.md b/docs/versioned_docs/version-0.4/development/generators.md
new file mode 100644
index 000000000..54c1b6457
--- /dev/null
+++ b/docs/versioned_docs/version-0.4/development/generators.md
@@ -0,0 +1,107 @@
+---
+title: Generators
+description: Learn how to use generators in Marten.
+---
+
+Marten features a generator mechanism that simplifies the creation of various abstractions, files, and structures within an existing project. This feature facilitates the generation of key components such as [models](../models-and-databases/introduction.md), [schemas](../schemas/introduction.md), [emails](../emailing/introduction.md), or [applications](./applications.md). By leveraging generators, developers can improve their workflow and speed up the development of their Marten projects while following best practices.
+
+## Usage
+
+Generators can be invoked by leveraging the [`marten gen`](./reference/management-commands.md#gen) management command. This command is intended to be used as follows:
+
+```bash
+marten gen [generator] [options] [arguments]
+```
+
+As you can see, the `marten gen` command must be used with a specific **generator** name, possibly followed by **options** and **arguments** (which may be required or not depending on the considered generator). All the built-in generators are listed in the [generators reference](./reference/generators.md).
+
+### Displaying help information
+
+You can display help information about a specific generator by using the `marten gen` command as follows:
+
+```bash
+marten gen [generator] --help
+```
+
+### Listing generators
+
+It is possible to list all the available generators within a project by running the `marten gen` command as follows:
+
+```bash
+marten gen
+```
+
+This should output something like this:
+
+```
+Usage: marten gen [options] [generator]
+
+Generate various structures, abstractions, and values within an existing project.
+
+Arguments:
+ generator Name of the generator to use
+
+Options:
+ --error-trace Show full error trace (if a compilation is involved)
+ --no-color Disable colored output
+ -h, --help Show this help
+
+Available generators are listed below.
+
+[marten]
+
+ › app
+ › auth
+ › email
+ › handler
+ › model
+ › schema
+ › secretkey
+
+Run a generator followed by --help to see generator specific information, ex:
+marten gen [generator] --help
+```
+
+## Examples
+
+### Generating a model
+
+Generating a model can be achieved with the [`model`](./reference/generators.md#model) generator:
+
+```bash
+# Generate a model in the main app:
+marten gen model User name:string email:string
+
+# Generate a model in the admin app:
+marten gen model User name:string email:string --app admin
+
+# Generate a model with a many-to-one reference:
+marten gen model Article label:string body:text author:many_to_one{User}
+
+# Generate a model with a parent class:
+marten gen model Admin::User name:string email:string --parent User
+
+# Generate a model without timestamps:
+marten gen model User name:string email:string --no-timestamps
+```
+
+### Generating an email
+
+Generating an email can be achieved with the [`email`](./reference/generators.md#email) generator:
+
+```bash
+marten gen email TestEmail # Generate a new TestEmail email in the main application
+marten gen email TestEmail --app blog # Generate a new TestEmail email in the blog application
+```
+
+### Generating an application
+
+Generating an application can be achieved with the [`app`](./reference/generators.md#app) generator:
+
+```bash
+marten gen app blogging # Generate a new 'blogging' application
+```
+
+## Available generators
+
+Please head over to the [generators reference](./reference/generators.md) to see a list of all the available generators.
diff --git a/docs/versioned_docs/version-0.4/development/how-to/configure-database-backends.md b/docs/versioned_docs/version-0.4/development/how-to/configure-database-backends.md
new file mode 100644
index 000000000..e6dd701aa
--- /dev/null
+++ b/docs/versioned_docs/version-0.4/development/how-to/configure-database-backends.md
@@ -0,0 +1,155 @@
+---
+title: Configure database backends
+description: How to configure database backends.
+---
+
+This guide provides instructions on configuring new database backends or changing the existing database backend within your existing Marten projects.
+
+## Context
+
+Marten officially supports **MySQL**, **PostgreSQL**, and **SQLite3** databases. New Marten projects default to utilizing a SQLite3 database, a lightweight serverless database application that is typically pre-installed on most existing operating systems. This makes it an excellent choice for a development or testing database, but you may want to use a more powerful database such as MySQL or PostgreSQL. In this light, this guide explains what steps should be taken in order to use your database backend of choice in a Marten project.
+
+## Prerequisites
+
+This guide presupposes that you already have a functional Marten project available. If you don't, you can easily create one using the following command:
+
+```bash
+marten new project
+```
+
+Furthermore, it assumes that your preferred database is properly configured and ready for use. If this isn't the case, please consult the respective official documentation to install your chosen database:
+
+* [PostgreSQL Installation Guide](https://wiki.postgresql.org/wiki/Detailed_installation_guides)
+* [MySQL Installation Guide](https://dev.mysql.com/doc/refman/8.0/en/installing.html)
+* [SQLite Installation Guide](https://www.tutorialspoint.com/sqlite/sqlite_installation.htm)
+
+## Installing the right database shard
+
+For each database, a dedicated Crystal shard is required. Depending on your chosen database, you must include one of the following entries in your project's `shard.yml` file:
+
+* [crystal-pg](https://github.com/will/crystal-pg) (required for PostgreSQL databases)
+* [crystal-mysql](https://github.com/crystal-lang/crystal-mysql) (required for MySQL databases)
+* [crystal-sqlite3](https://github.com/crystal-lang/crystal-sqlite3) (required for SQLite3 databases)
+
+This means that your `shard.yml` file should resemble one of the following examples:
+
+### MySQL
+
+```yaml
+name: myproject
+version: 0.1.0
+
+dependencies:
+ marten:
+ github: martenframework/marten
+ // highlight-next-line
+ mysql:
+ // highlight-next-line
+ github: crystal-lang/crystal-mysql
+```
+
+### PostgreSQL
+
+```yaml
+name: myproject
+version: 0.1.0
+
+dependencies:
+ marten:
+ github: martenframework/marten
+ // highlight-next-line
+ pg:
+ // highlight-next-line
+ github: will/crystal-pg
+```
+
+### SQLite3
+
+```yaml
+name: myproject
+version: 0.1.0
+
+dependencies:
+ marten:
+ github: martenframework/marten
+ // highlight-next-line
+ sqlite3:
+ // highlight-next-line
+ github: crystal-lang/crystal-sqlite3
+```
+
+## Adding the right DB Crystal requirement
+
+After you've included the correct Crystal shard in your project's `shard.yml` file, the subsequent task is to add the corresponding requirement in the `src/project.cr` file. This file contains all the requirements of your project (including Marten itself) and is automatically generated by the [`new`](../reference/management-commands.md#new) management command.
+
+Please consult the examples below to determine which requirement you should include based on your selected database backend:
+
+### MySQL
+
+```crystal
+# Third party requirements.
+require "marten"
+// highlight-next-line
+require "mysql"
+
+# Project requirements.
+# [...]
+
+# Configuration requirements.
+# [...]
+```
+
+### PostgreSQL
+
+```crystal
+# Third party requirements.
+require "marten"
+// highlight-next-line
+require "pg"
+```
+
+### SQLite3
+
+```crystal
+# Third party requirements.
+require "marten"
+// highlight-next-line
+require "sqlite3"
+```
+
+## Configuring your database
+
+The last step involves configuring database settings so that they target the database you intend to use with your Marten project. While a comprehensive list of configuration options is available in the [Database settings reference](../reference/settings.md#database-settings), the following sections offer example configurations tailored to each supported database backend.
+
+### MySQL
+
+```crystal
+config.database do |db|
+ db.backend = :mysql
+ db.host = "localhost"
+ db.name = "my_db"
+ db.user = "my_user"
+ db.password = "insecure"
+end
+```
+
+### PostgreSQL
+
+```crystal
+config.database do |db|
+ db.backend = :postgresql
+ db.host = "localhost"
+ db.name = "my_db"
+ db.user = "my_user"
+ db.password = "insecure"
+end
+```
+
+### SQLite3
+
+```crystal
+config.database do |db|
+ db.backend = :sqlite
+ db.name = "my_db.db"
+end
+```
diff --git a/docs/versioned_docs/version-0.1/development/how-to/create-custom-commands.md b/docs/versioned_docs/version-0.4/development/how-to/create-custom-commands.md
similarity index 85%
rename from docs/versioned_docs/version-0.1/development/how-to/create-custom-commands.md
rename to docs/versioned_docs/version-0.4/development/how-to/create-custom-commands.md
index 61f5538dd..3282f6784 100644
--- a/docs/versioned_docs/version-0.1/development/how-to/create-custom-commands.md
+++ b/docs/versioned_docs/version-0.4/development/how-to/create-custom-commands.md
@@ -7,9 +7,9 @@ Marten lets you create custom management commands as part of your [applications]
## Basic management command definition
-Custom management commands are defined as subclasses of the [`Marten::CLI::Command`](pathname:///api/0.1/Marten/CLI/Manage/Command/Base.html) abstract class. Such subclasses should be defined in a `cli/` folder at the root of the application, and it should be ensured that they are required by your `cli.cr` file (see [Creating applications](../applications.md#creating-applications) for more details regarding the structure of an application).
+Custom management commands are defined as subclasses of the [`Marten::CLI::Command`](pathname:///api/0.4/Marten/CLI/Manage/Command/Base.html) abstract class. Such subclasses should be defined in a `cli/` folder at the root of the application, and it should be ensured that they are required by your `cli.cr` file (see [Creating applications](../applications.md#creating-applications) for more details regarding the structure of an application).
-Management command classes must at least define a [`#run`](pathname:///api/0.1/Marten/CLI/Manage/Command/Base.html#run-instance-method) method, which will be called when the subcommand is executed:
+Management command classes must at least define a [`#run`](pathname:///api/0.4/Marten/CLI/Manage/Command/Base.html#run-instance-method) method, which will be called when the subcommand is executed:
```crystal
class MyCommand < Marten::CLI::Command
@@ -21,7 +21,7 @@ class MyCommand < Marten::CLI::Command
end
```
-As you can see in the previous example, the [`#help`](pathname:///api/0.1/Marten/CLI/Manage/Command/Base.html#help(help%3AString)-class-method) class method allows setting a "help text" that will be displayed when the help information of the command is requested.
+As you can see in the previous example, the [`#help`](pathname:///api/0.4/Marten/CLI/Manage/Command/Base.html#help(help%3AString)-class-method) class method allows setting a "help text" that will be displayed when the help information of the command is requested.
If the above command was part of an installed application, it could be executed by using the Marten CLI as follows:
@@ -38,7 +38,7 @@ Marten management commands can accept options and arguments. These differ and ma
By default options and arguments are always optional. That being said, they can be made mandatory in the command execution logic if needed.
-Both options and arguments must be specified in the optional [`#setup`](pathname:///api/0.1/Marten/CLI/Manage/Command/Base.html#setup-instance-method) method: this method will be called to prepare the definition of the command, including its arguments and options.
+Both options and arguments must be specified in the optional [`#setup`](pathname:///api/0.4/Marten/CLI/Manage/Command/Base.html#setup-instance-method) method: this method will be called to prepare the definition of the command, including its arguments and options.
For example:
@@ -60,7 +60,7 @@ class MyCommand < Marten::CLI::Command
end
```
-In the above example, the [`#on_argument`](pathname:///api/0.1/Marten/CLI/Manage/Command/Base.html#on_argument(name%3AString|Symbol%2Cdescription%3AString%2C%26block%3AString->)-instance-method) instance method is used to define an `arg1` argument. This method requires an argument name, an associated help text, and a proc where the value of the argument will be forwarded at execution time (which allows you to assign it to an instance variable or process it if you wish to). Similarly, the [`#on_option`](pathname:///api/0.1/Marten/CLI/Manage/Command/Base.html#on_option(flag%3AString|Symbol%2Cdescription%3AString%2C%26block%3AString->)-instance-method) instance method is used to define an `example` option. In this case, the name of the option and its associated help text must be specified, and a proc can be defined to identify that the option was specified at execution time (which can be used to set a related boolean instance variable for example).
+In the above example, the [`#on_argument`](pathname:///api/0.4/Marten/CLI/Manage/Command/Base.html#on_argument(name%3AString|Symbol%2Cdescription%3AString%2C%26block%3AString->)-instance-method) instance method is used to define an `arg1` argument. This method requires an argument name, an associated help text, and a proc where the value of the argument will be forwarded at execution time (which allows you to assign it to an instance variable or process it if you wish to). Similarly, the [`#on_option`](pathname:///api/0.4/Marten/CLI/Manage/Command/Base.html#on_option(flag%3AString|Symbol%2Cdescription%3AString%2C%26block%3AString->)-instance-method) instance method is used to define an `example` option. In this case, the name of the option and its associated help text must be specified, and a proc can be defined to identify that the option was specified at execution time (which can be used to set a related boolean instance variable for example).
The above command would produce the following help information:
@@ -81,7 +81,7 @@ Options:
### Configuring options
-As mentioned previously, it is possible to make use of the [`#on_option`](pathname:///api/0.1/Marten/CLI/Manage/Command/Base.html#on_option(flag%3AString|Symbol%2Cdescription%3AString%2C%26block%3AString->)-instance-method) instance method to configure a specific command option (eg. `--option`). It expects a flag name and a description, and it yields a block to let the command properly assign the option value to the command object at execution time:
+As mentioned previously, it is possible to make use of the [`#on_option`](pathname:///api/0.4/Marten/CLI/Manage/Command/Base.html#on_option(flag%3AString|Symbol%2Cdescription%3AString%2C%26block%3AString->)-instance-method) instance method to configure a specific command option (eg. `--option`). It expects a flag name and a description, and it yields a block to let the command properly assign the option value to the command object at execution time:
```crystal
on_option("example", "An example option") { @example = true }
@@ -97,7 +97,7 @@ on_option("e", "example", "An example option") { @example = true }
### Configuring options that accept arguments
-It is possible to make use of the [`#on_option_with_arg`](pathname:///api/0.1/Marten/CLI/Manage/Command/Base.html#on_option_with_arg(flag%3AString|Symbol%2Carg%3AString|Symbol%2Cdescription%3AString%2C%26block%3AString->)-instance-method) instance method to configure a specific command option with an associated argument. This method will configure a command option (eg. `--option`) and an associated argument. It expects a flag name, an argument name, and a description. It yields a block to let the command properly assign the option to the command object at execution time:
+It is possible to make use of the [`#on_option_with_arg`](pathname:///api/0.4/Marten/CLI/Manage/Command/Base.html#on_option_with_arg(flag%3AString|Symbol%2Carg%3AString|Symbol%2Cdescription%3AString%2C%26block%3AString->)-instance-method) instance method to configure a specific command option with an associated argument. This method will configure a command option (eg. `--option`) and an associated argument. It expects a flag name, an argument name, and a description. It yields a block to let the command properly assign the option to the command object at execution time:
```crystal
on_option_with_arg(:option, :arg, "The name of the option") { @arg = arg }
@@ -111,7 +111,7 @@ on_option_with_arg("o", "option", "arg", "The name of the option") { |arg| @arg
### Configuring arguments
-As mentioned previously, it is possible to make use of the [`#on_argument`](pathname:///api/0.1/Marten/CLI/Manage/Command/Base.html#on_argument(name%3AString|Symbol%2Cdescription%3AString%2C%26block%3AString->)-instance-method) instance method in order to configure a specific command argument. This method expects an argument name and a description, and it yields a block to let the command properly assign the argument value to the command object at execution time:
+As mentioned previously, it is possible to make use of the [`#on_argument`](pathname:///api/0.4/Marten/CLI/Manage/Command/Base.html#on_argument(name%3AString|Symbol%2Cdescription%3AString%2C%26block%3AString->)-instance-method) instance method in order to configure a specific command argument. This method expects an argument name and a description, and it yields a block to let the command properly assign the argument value to the command object at execution time:
```crystal
on_argument(:arg, "The name of the argument") { |value| @arg_var = value }
@@ -123,7 +123,7 @@ It should be noted that the order in which arguments are defined is important: t
## Outputting text contents
-When writing management commands, you will likely need to write text contents to the output file descriptor. To do so, you can make use of the [`#print`](pathname:///api/0.1/Marten/CLI/Manage/Command/Base.html#print(msg%2Cending%3D"\n")-instance-method) instance method:
+When writing management commands, you will likely need to write text contents to the output file descriptor. To do so, you can make use of the [`#print`](pathname:///api/0.4/Marten/CLI/Manage/Command/Base.html#print(msg%2Cending%3D"\n")-instance-method) instance method:
```crystal
class HelloWorldCommand < Marten::CLI::Command
@@ -135,7 +135,7 @@ class HelloWorldCommand < Marten::CLI::Command
end
```
-It should be noted that you can also choose to "style" the content you specify to [`#print`](pathname:///api/0.1/Marten/CLI/Manage/Command/Base.html#print(msg%2Cending%3D"\n")-instance-method) by wrapping your string with a call to the [`#style`](pathname:///api/0.1/Marten/CLI/Manage/Command/Base.html#style(msg%2Cfore%3Dnil%2Cmode%3Dnil)-instance-method) method. For example:
+It should be noted that you can also choose to "style" the content you specify to [`#print`](pathname:///api/0.4/Marten/CLI/Manage/Command/Base.html#print(msg%2Cending%3D"\n")-instance-method) by wrapping your string with a call to the [`#style`](pathname:///api/0.4/Marten/CLI/Manage/Command/Base.html#style(msg%2Cfore%3Dnil%2Cmode%3Dnil)-instance-method) method. For example:
```crystal
class HelloWorldCommand < Marten::CLI::Command
@@ -147,11 +147,11 @@ class HelloWorldCommand < Marten::CLI::Command
end
```
-As you can see, the [`#style`](pathname:///api/0.1/Marten/CLI/Manage/Command/Base.html#style(msg%2Cfore%3Dnil%2Cmode%3Dnil)-instance-method) method can be used to apply `fore` and `mode` styles to a specific text value. The values you can use for the `fore` and `mode` arguments are the same as the ones that you can use with the [`Colorize`](https://crystal-lang.org/api/Colorize.html) module (which comes with the standard library).
+As you can see, the [`#style`](pathname:///api/0.4/Marten/CLI/Manage/Command/Base.html#style(msg%2Cfore%3Dnil%2Cmode%3Dnil)-instance-method) method can be used to apply `fore` and `mode` styles to a specific text value. The values you can use for the `fore` and `mode` arguments are the same as the ones that you can use with the [`Colorize`](https://crystal-lang.org/api/Colorize.html) module (which comes with the standard library).
## Handling error cases
-You will likely want to handle error situations when writing management commands. For example, to return error messages if a specified argument is not provided or if it is invalid. To do so you can make use of the [`#print_error`](pathname:///api/0.1/Marten/CLI/Manage/Command/Base.html#print_error(msg)-instance-method) helper method, which will print the passed string to the error file descriptor:
+You will likely want to handle error situations when writing management commands. For example, to return error messages if a specified argument is not provided or if it is invalid. To do so you can make use of the [`#print_error`](pathname:///api/0.4/Marten/CLI/Manage/Command/Base.html#print_error(msg)-instance-method) helper method, which will print the passed string to the error file descriptor:
```crystal
class HelloWorldCommand < Marten::CLI::Command
@@ -173,11 +173,11 @@ class HelloWorldCommand < Marten::CLI::Command
end
```
-Alternatively, you can make use of the [`#print_error_and_exit`](pathname:///api/0.1/Marten/CLI/Manage/Command/Base.html#print_error_and_exit(msg%2Cexit_code%3D1)-instance-method) method to print a message to the error file descriptor and to exit the execution of the command.
+Alternatively, you can make use of the [`#print_error_and_exit`](pathname:///api/0.4/Marten/CLI/Manage/Command/Base.html#print_error_and_exit(msg%2Cexit_code%3D1)-instance-method) method to print a message to the error file descriptor and to exit the execution of the command.
## Customizing the subcommand name
-By default, management command names are inferred by using their associated class names (eg. a `MyCommand` command class would translate to a `my_command` subcommand). That being said, it should be noted that you can define a custom subcommand name by leveraging the [`#command_name`](pathname:///api/0.1/Marten/CLI/Manage/Command/Base.html#command_name(name%3AString|Symbol)-class-method) class method:
+By default, management command names are inferred by using their associated class names (eg. a `MyCommand` command class would translate to a `my_command` subcommand). That being said, it should be noted that you can define a custom subcommand name by leveraging the [`#command_name`](pathname:///api/0.4/Marten/CLI/Manage/Command/Base.html#command_name(name%3AString|Symbol)-class-method) class method:
```crystal
class MyCommand < Marten::CLI::Command
@@ -189,3 +189,17 @@ class MyCommand < Marten::CLI::Command
end
end
```
+
+It is also worth mentioning that command aliases can be configured easily by using the [`#command_aliases`](pathname:///api/0.4/Marten/CLI/Manage/Command/Base.html#command_aliases(*aliases%3AString|Symbol)-class-method) helper method. For example:
+
+```crystal
+class MyCommand < Marten::CLI::Command
+ command_name :test
+ command_aliases :t
+ help "Command that does something"
+
+ def run
+ # Do something
+ end
+end
+```
diff --git a/docs/versioned_docs/version-0.1/development/management-commands.md b/docs/versioned_docs/version-0.4/development/management-commands.md
similarity index 78%
rename from docs/versioned_docs/version-0.1/development/management-commands.md
rename to docs/versioned_docs/version-0.4/development/management-commands.md
index 3dc71ba07..35657d0f4 100644
--- a/docs/versioned_docs/version-0.1/development/management-commands.md
+++ b/docs/versioned_docs/version-0.4/development/management-commands.md
@@ -40,20 +40,23 @@ marten help
This should output something like this:
```bash
-Usage: marten [command] [arguments]
+Usage: marten [command] [options] [arguments]
Available commands:
[marten]
- › collectassets
- › genmigrations
- › listmigrations
- › migrate
- › new
- › resetmigrations
- › routes
- › serve
- › version
+
+ › clearsessions Clear all expired sessions.
+ › collectassets Collect all the assets and copy them in a unique storage.
+ › gen / g Generate various structures, abstractions, and values within an existing project.
+ › genmigrations Generate new database migrations.
+ › listmigrations List all database migrations.
+ › migrate Run database migrations.
+ › new Initialize a new Marten project or application repository.
+ › resetmigrations Reset an existing set of migrations into a single one.
+ › routes Display all the routes of the application.
+ › serve / s Start a development server that is automatically recompiled when source files change.
+ › version Show the Marten version.
Run a command followed by --help to see command specific information, ex:
marten [command] --help
diff --git a/docs/versioned_docs/version-0.4/development/reference/generators.md b/docs/versioned_docs/version-0.4/development/reference/generators.md
new file mode 100644
index 000000000..e47959df8
--- /dev/null
+++ b/docs/versioned_docs/version-0.4/development/reference/generators.md
@@ -0,0 +1,194 @@
+---
+title: Generators
+description: Generators reference.
+toc_max_heading_level: 2
+---
+
+This page provides a reference for all the available generators and their options.
+
+## `app`
+
+**Usage:** `marten gen app [options] [label]`
+
+Add and configure a new [application](../applications.md) to the current project.
+
+:::info
+This generator will attempt to add the generated application to the [`installed_apps`](./settings.md#installed_apps) setting and will also configure Crystal requirements for it (in the `src/project.cr` and `src/cli.cr` files).
+:::
+
+### Arguments
+
+* `label` - Label of the application to generate
+
+### Examples
+
+```bash
+marten gen app blogging # Generate a new 'blogging' application
+```
+
+## `auth`
+
+**Usage:** `marten gen auth [options] [label]`
+
+Generate and configure a fully functional authentication application for your project. Please refer to [Authentication](../../authentication.mdx) to learn more about authentication in Marten, and to [Generated files](../../authentication/reference/generated-files.md) to see a list of the files generated for the authentication app specifically.
+
+:::info
+This generator will attempt to add the generated application to the [`installed_apps`](./settings.md#installed_apps) setting and will also configure Crystal requirements for it (in the `src/project.cr` and `src/cli.cr` files). It will also add authentication-related settings to your base settings file and will add the [`marten-auth`](https://github.com/martenframework/marten-auth) shard to your project's `shard.yml`.
+:::
+
+### Arguments
+
+* `label` - Label of the authentication application to generate (default to "auth")
+
+### Examples
+
+```bash
+marten gen auth # Generate a new authentication app with the 'auth' label
+marten gen auth my_auth # Generate a new authentication app with the 'my_auth' label
+```
+
+## `email`
+
+**Usage:** `marten gen email [options] [name]`
+
+Generate an email. Please refer to [Emailing](../../emailing.mdx) to learn more about emailing in Marten.
+
+### Options
+
+* `--app=APP` - Target app where the email should be created (default to the [main app](../applications.md#the-main-application))
+* `--parent=PARENT` - Parent class name for the generated email
+
+### Arguments
+
+* `name` - Name of the email to generate (must be CamelCase)
+
+### Examples
+
+```bash
+marten gen email TestEmail # Generate a new TestEmail email in the main application
+marten gen email TestEmail --app blog # Generate a new TestEmail email in the blog application
+```
+
+## `handler`
+
+Generate a handler. Please refer to [Handlers](../../handlers-and-http/introduction.md) to learn more about handlers.
+
+### Options
+
+* `--app=APP` - Target app where the handler should be created (default to the [main app](../applications.md#the-main-application))
+* `--parent=PARENT` - Parent class name for the generated handler
+
+### Arguments
+
+* `name` - Name of the handler to generate (must be CamelCase)
+
+### Examples
+
+```bash
+marten gen handler TestHandler # Generate a new TestHandler handler in the main application
+marten gen handler TestHandler --app blog # Generate a new TestHandler handler in the blog application
+```
+
+## `model`
+
+Generate a model. Please refer to [Models](../../models-and-databases/introduction.md) to learn more about models.
+
+### Options
+
+* `--app=APP` - Target app where model handler should be created (default to the [main app](../applications.md#the-main-application))
+* `--parent=PARENT` - Parent class name for the generated model
+* `--no-timestamps` - Do not include timestamp fields in the generated model
+
+### Arguments
+
+* `name` - Name of the model to generate (must be CamelCase)
+* `field_definitions` - Field definitions of the model to generate
+
+### Details
+
+This generator can generate a model with the specified name and field definitions. The model is generated in the app specified by the `--app` option or in the [main app](../applications.md#the-main-application) if no app is specified.
+
+Field definitions can be specified using the following formats:
+
+```
+name:type
+name:type{qualifier}
+name:type:modifier:modifier
+```
+
+Where `name` is the name of the field and `type` is the type of the field.
+
+`qualifier` can be required depending on the considered field type; when this is the case, it corresponds to a mandatory field option. For example, `label:string{128}` will produce a [string field](../../models-and-databases/reference/fields.md#string) whose `max_size` option is set to `128`. Another example: `author:many_to_one{User}` will produce a [many-to-one field](../../models-and-databases/reference/fields.md#many_to_one) whose `to` option is set to target the `User` model.
+
+`modifier` is an optional field modifier. Field modifiers are used to specify additional (but non-mandatory) field options. For example: `name:string:uniq` will produce a [string field](../../models-and-databases/reference/fields.md#string) whose `unique` option is set to `true`. Another example: `name:string:uniq:index` will produce a [string field](../../models-and-databases/reference/fields.md#string) whose `unique` and `index` options are set to `true`.
+
+### Examples
+
+```bash
+# Generate a model in the main app:
+marten gen model User name:string email:string
+
+# Generate a model in the admin app:
+marten gen model User name:string email:string --app admin
+
+# Generate a model with a many-to-one reference:
+marten gen model Article label:string body:text author:many_to_one{User}
+
+# Generate a model with a parent class:
+marten gen model Admin::User name:string email:string --parent User
+
+# Generate a model without timestamps:
+marten gen model User name:string email:string --no-timestamps
+```
+
+## `schema`
+
+Generate a schema. Please refer to [Schemas](../../schemas/introduction.md) to learn more about schemas.
+
+### Options
+
+* `--app=APP` - Target app where schema should be created (default to the [main app](../applications.md#the-main-application))
+* `--parent=PARENT` - Parent class name for the generated schema
+
+### Arguments
+
+* `name` - Name of the schema to generate (must be CamelCase)
+* `field_definitions` - Field definitions of the schema to generate
+
+### Details
+
+This generator can generate a schema with the specified name and field definitions. The schema is generated in the app specified by the `--app` option or in the [main app](../applications.md#the-main-application) if no app is specified.
+
+Field definitions can be specified using the following formats:
+
+```
+name:type
+name:type:modifier:modifier
+```
+
+Where `name` is the name of the field and `type` is the type of the field.
+
+`modifier` is an optional field modifier. Field modifiers are used to specify additional (but non-mandatory) field options. For example: `name:string:optional` will produce a [string field](../../schemas/reference/fields.md#string) whose `required` option is set to `false`.
+
+### Examples
+
+```bash
+# Generate a schema in the main app:
+marten gen schema ArticleSchema title:string body:string
+
+# Generate a schema in the blog app:
+marten gen schema ArticleSchema title:string body:string --app admin
+
+# Generate a schema with a parent class:
+marten gen schema ArticleSchema title:string body:string --parent BaseSchema
+```
+
+## `secretkey`
+
+Generate a new secret key value that can be used in the [`secret_key`](./settings.md#secret_key) setting.
+
+### Examples
+
+```bash
+marten gen secretkey
+```
diff --git a/docs/versioned_docs/version-0.1/development/reference/management-commands.md b/docs/versioned_docs/version-0.4/development/reference/management-commands.md
similarity index 58%
rename from docs/versioned_docs/version-0.1/development/reference/management-commands.md
rename to docs/versioned_docs/version-0.4/development/reference/management-commands.md
index 653105272..28ac6dd13 100644
--- a/docs/versioned_docs/version-0.1/development/reference/management-commands.md
+++ b/docs/versioned_docs/version-0.4/development/reference/management-commands.md
@@ -6,13 +6,32 @@ toc_max_heading_level: 2
This page provides a reference for all the available management commands and their options.
+## `clearsessions`
+
+**Usage:** `marten clearsessions [options]`
+
+Clears all expired sessions for the configured session store.
+
+Please refer to [Sessions](../../handlers-and-http/sessions.md) to learn more about sessions.
+
+### Options
+
+* `--no-input` - Does not show prompts to the user
+
+### Examples
+
+```bash
+marten clearsessions # Clears all expired sessions
+marten clearsessions --no-input # Clears all expired sessions without any prompts
+```
+
## `collectassets`
**Usage:** `marten collectassets [options]`
Collects all the assets and copies them into a unique storage.
-Please refer to [Asset handling](../../files/asset-handling) to learn more about when and how assets are "collected".
+Please refer to [Asset handling](../../assets/introduction.md) to learn more about when and how assets are "collected".
### Options
@@ -25,6 +44,39 @@ marten collectassets # Collects all the assets
marten collectassets --no-input # Collects all the assets without any prompts
```
+## `gen`
+
+**Usage:** `marten gen [options] [generator] [arguments]`
+
+Generate various structures, abstractions, and values within an existing project.
+
+### Options
+
+Generators support their own specific options. For an exact list of generator options, please refer to the [Generators reference](./generators.md).
+
+### Arguments
+
+* `generator` - Name of the generator to use
+* `arguments` - Generator-specific arguments
+
+Generators support their own specific arguments. For an exact list of generator arguments, please refer to the [Generators reference](./generators.md).
+
+### Examples
+
+```bash
+marten gen secretkey # Generate a secret key value
+marten gen email WelcomeEmail # Generate a WelcomeEmail email in the main application
+marten gen handler MyHandler --app=blog # Generate a MyHandler handler in the blog application
+```
+
+:::tip
+You can also use the alias `g` to execute specific generators:
+
+```bash
+marten g model Test label:string:uniq
+```
+:::
+
## `genmigrations`
**Usage:** `marten genmigrations [options] [app_label]`
@@ -83,6 +135,7 @@ The `migrate` command allows you to apply (or unapply) migrations to your databa
### Options
* `--fake` - Allows marking migrations as applied or unapplied without actually running them
+* `--plan` - Provides a comprehensive overview of the operations that will be performed by the applied or unapplied migrations
* `--db=ALIAS` - Allows specifying the alias of the database on which migrations will be applied or unapplied (default to `default`)
### Arguments
@@ -100,26 +153,35 @@ marten migrate foo 202203111821451 # Applies (or unapply) migrations for the "fo
## `new`
-**Usage:** `marten new [options] [type] [name] [dir]`
+**Usage:** `marten new [options] [type] [name]`
-Initializes a new Marten project or application structure.
+Initializes a new Marten project or application repository structure.
-The `new` management command can be used to create either a new project structure or a new [application](../applications.md) structure. This can be handy when creating new projects or when introducing new applications into an existing project, as it ensures you are following Marten's best practices and conventions.
+The `new` management command can be used to create either a new project repository or a new [application](../applications.md) repository. This can be handy when creating new projects, or when creating new applications that are intended to be distributed as dedicated shards, as it ensures you are following Marten's best practices and conventions.
The command allows you to fully define the name of your project or application, and in which folder it should be created.
+### Options
+
+* `-d DIR, --dir=DIR` - An optional destination directory
+* `--with-auth` - Adds an authentication application to newly created projects. See [Authentication](../../authentication.mdx) to learn more about this capability
+* `--database` - Preconfigures the application database. Currently `mysql`, `postgresq` and `sqlite3` are supported. See [Database settings](../../development/reference/settings.md#database-settings) for more information.
+
### Arguments
* `type` - The type of structure to create (must be either `project` or `app`)
* `name` - The name of the project or app to create
-* `dir` - A destination directory (optional)
+
+:::tip
+The `type` and `name` arguments are optional: if they are not provided, an interactive mode will be used and the command will prompt the user for inputting the structure type, the app or project name, and whether the auth app should be generated.
+:::
### Examples
```bash
-marten new project myblog # Creates a "myblog" project
-marten new project myblog ./projects/myblog # Creates a "myblog" project in the "./projects/myblog" folder
-marten new app auth # Creates an "auth" application
+marten new project myblog # Creates a "myblog" project repository structure
+marten new project myblog --dir=./projects/myblog # Creates a "myblog" project in the "./projects/myblog" folder
+marten new app auth # Creates an "auth" application repository structure
```
## `resetmigrations`
@@ -150,6 +212,26 @@ Displays all the routes of the application.
Starts a development server that is automatically recompiled when source files change.
+### Options
+
+* `-b HOST, --bind=HOST` - Allows specifying a custom host to bind
+* `-p PORT, --port=PORT` - Allows specifying a custom port to listen for connections
+
+### Examples
+
+```bash
+marten serve # Starts a development server using the configured host and port
+marten serve -p 3000 # Starts a development server by overriding the port
+```
+
+:::tip
+You can also use the alias `s` to start the development server:
+
+```bash
+marten s
+```
+:::
+
## `version`
**Usage:** `marten version [options]`
diff --git a/docs/versioned_docs/version-0.1/development/reference/settings.md b/docs/versioned_docs/version-0.4/development/reference/settings.md
similarity index 68%
rename from docs/versioned_docs/version-0.1/development/reference/settings.md
rename to docs/versioned_docs/version-0.4/development/reference/settings.md
index 50e5d35a9..0bd9115a6 100644
--- a/docs/versioned_docs/version-0.1/development/reference/settings.md
+++ b/docs/versioned_docs/version-0.4/development/reference/settings.md
@@ -24,6 +24,16 @@ It should be noted that this setting is automatically set to the following array
[".localhost", "127.0.0.1", "[::1]"]
```
+### `cache_store`
+
+Default: `Marten::Cache::Store::Memory.new`
+
+The global cache store instance.
+
+This setting allows to configure the cache store returned by the [`Marten#cache`](pathname:///api/0.4/Marten.html#cache%3ACache%3A%3AStore%3A%3ABase-class-method) method (which can be used to perform low-level caching operations), and which is also leveraged for other caching features such as template fragment caching. Please refer to [Caching](../../caching.mdx) to learn more about the caching features provided by Marten.
+
+By default, the global cache store is set to be an in-memory cache (instance of [`Marten::Cache::Store::Memory`](pathname:///api/0.4/Marten/Cache/Store/Memory.html)). In test environments you might want to use the "null store" by assigning an instance of the [`Marten::Cache::Store::Null](pathname:///api/0.4/Marten/Cache/Store/Null.html) to this setting. Additional caching store shards are also maintained under the umbrella of the Marten project or by the community itself and can be used as part of your application depending on your caching requirements. These backends are listed in the [caching stores backend reference](../../caching/reference/stores.md).
+
### `debug`
Default: `false`
@@ -42,7 +52,7 @@ The host the HTTP server running the application will be listening on.
Default: `[] of Marten::Apps::Config.class`
-An array of the installed app classes. Each Marten application must define a subclass of [`Marten::Apps::Config`](pathname:///api/0.1/Marten/Apps/Config.html). When those subclasses are specified in the `installed_apps` setting, the applications' models, migrations, assets, and templates will be made available to the considered project. Please refer to [Applications](../applications.md) to learn more about applications.
+An array of the installed app classes. Each Marten application must define a subclass of [`Marten::Apps::Config`](pathname:///api/0.4/Marten/Apps/Config.html). When those subclasses are specified in the `installed_apps` setting, the applications' models, migrations, assets, and templates will be made available to the considered project. Please refer to [Applications](../applications.md) to learn more about applications.
### `log_backend`
@@ -92,6 +102,20 @@ The maximum number of allowed parameters per request (such as GET or POST parame
A large number of parameters will require more time to process and might be the sign of a denial-of-service attack, which is why this setting can be used. This protection can also be disabled by setting `request_max_parameters` to `nil`.
+### `root_path`
+
+Default: `nil`
+
+The root path of the application.
+
+The root path of the application specifies the actual location of the project sources in your system. This can prove helpful in scenarios where the project was compiled in a specific location different from the final destination where the project sources (and the `lib` folder) are copied. For instance, platforms like Heroku often fall under this category. By configuring the root path, you can ensure that your application correctly locates the required project sources and avoids any discrepancies arising from inconsistent source paths. This can prevent issues related to missing dependencies or missing app-related files (eg. locales, assets, or templates) and make your application more robust and reliable.
+
+For example, deploying a Marten app on Heroku will usually involves setting the root path as follows:
+
+```crystal
+config.root_path = "/app"
+```
+
### `secret_key`
Default: `""`
@@ -160,7 +184,7 @@ The value to use for the X-Frame-Options header when the associated middleware i
## Assets settings
-Assets settings allow configuring how Marten should interact with [assets](../../files/asset-handling). These settings are all available under the `assets` namespace:
+Assets settings allow configuring how Marten should interact with [assets](../../assets/introduction.md). These settings are all available under the `assets` namespace:
```crystal
config.assets.root = "assets"
@@ -171,7 +195,7 @@ config.assets.url = "/assets/"
Default: `true`
-A boolean indicating whether assets should be looked for inside installed application folders. When this setting is set to `true`, this means that assets provided by installed applications will be collected by the `collectassets` command (please refer to [Asset handling](../../files/asset-handling) for more details regarding how to manage assets in your project).
+A boolean indicating whether assets should be looked for inside installed application folders. When this setting is set to `true`, this means that assets provided by installed applications will be collected by the `collectassets` command (please refer to [Asset handling](../../assets/introduction.md) for more details regarding how to manage assets in your project).
### `dirs`
@@ -208,9 +232,9 @@ This setting is only used if `assets.storage` is `nil`.
Default: `nil`
-An optional storage object, which must be an instance of a subclass of [`Marten::Core::Store::Base`](pathname:///api/0.1/Marten/Core/Storage/Base.html). This storage object will be used when collecting asset files to persist them in a given location.
+An optional storage object, which must be an instance of a subclass of [`Marten::Core::Store::Base`](pathname:///api/0.4/Marten/Core/Storage/Base.html). This storage object will be used when collecting asset files to persist them in a given location.
-By default this setting value is set to `nil`, which means that a [`Marten::Core::Store::FileSystem`](pathname:///api/0.1/Marten/Core/Storage/FileSystem.html) storage is automatically constructed by using the `assets.root` and `assets.url` setting values: in this situation, asset files are collected and persisted in a local directory, and it is expected that they will be served from this directory by the web server running the application.
+By default this setting value is set to `nil`, which means that a [`Marten::Core::Store::FileSystem`](pathname:///api/0.4/Marten/Core/Storage/FileSystem.html) storage is automatically constructed by using the `assets.root` and `assets.url` setting values: in this situation, asset files are collected and persisted in a local directory, and it is expected that they will be served from this directory by the web server running the application.
A specific storage can be set instead to ensure that collected assets are persisted somewhere else in the cloud and served from there (for example in an Amazon's S3 bucket). When this is the case, the `assets.root` and `assets.url` setting values are basically ignored and are overridden by the use of the specified storage.
@@ -218,7 +242,7 @@ A specific storage can be set instead to ensure that collected assets are persis
Default: `"/assets/"`
-The base URL to use when exposing asset URLs. This base URL will be used by the default [`Marten::Core::Store::FileSystem`](pathname:///api/0.1/Marten/Core/Storage/FileSystem.html) storage to construct asset URLs. For example, requesting a `css/App.css` asset might generate a `/assets/css/App.css` URL by default.
+The base URL to use when exposing asset URLs. This base URL will be used by the default [`Marten::Core::Store::FileSystem`](pathname:///api/0.4/Marten/Core/Storage/FileSystem.html) storage to construct asset URLs. For example, requesting a `css/App.css` asset might generate a `/assets/css/App.css` URL by default.
:::info
This setting is only used if `assets.storage` is `nil`.
@@ -294,6 +318,52 @@ config.csrf.trusted_origins = [
]
```
+## Content-Security-Policy settings
+
+These settings allow configuring how the [`Marten::Middleware::ContentSecurityPolicy`](../../handlers-and-http/reference/middlewares.md#content-security-policy-middleware) middleware behaves and the actual directives of the Content-Security-Policy header that are set by this middleware.
+
+```crystal
+config.content_security_policy.report_only = true
+config.content_security_policy.default_policy.default_src = [:self, "other"]
+```
+
+Please refer to [Content Security Policy](../../security/content-security-policy.md) to learn more about the Content-Security-Policy header protection.
+
+:::tip
+[Content-Security-Policy](https://www.w3.org/TR/CSP/) is a complicated header and there are possibly many values you may need to tweak. Make sure you understand it before configuring the below settings.
+:::
+
+### `default_policy`
+
+Default: `Marten::HTTP::ContentSecurityPolicy.new`
+
+The default Content-Security-Policy object.
+
+This [`Marten::HTTP::ContentSecurityPolicy`](pathname:///api/0.4/Marten/HTTP/ContentSecurityPolicy.html) object will be used to set the Content-Security-Policy header when the [`Marten::Middleware::ContentSecurityPolicy`](../../handlers-and-http/reference/middlewares.md#content-security-policy-middleware) middleware is used.
+
+All the attributes that can be set on this [`Marten::HTTP::ContentSecurityPolicy`](pathname:///api/0.4/Marten/HTTP/ContentSecurityPolicy.html) object through the use of methods such as [`#default_src=`](pathname:///api/0.4/Marten/HTTP/ContentSecurityPolicy.html#default_src%3D(value%3AArray|Nil|String|Symbol|Tuple)-instance-method) or [`#frame_src=`](pathname:///api/0.4/Marten/HTTP/ContentSecurityPolicy.html#frame_src%3D(value%3AArray|Nil|String|Symbol|Tuple)-instance-method) can also be used directly on the `content_security_policy` setting object. For example:
+
+```crystal
+config.content_security_policy.default_src = [:self, "other"]
+config.content_security_policy.block_all_mixed_content = true
+```
+
+### `nonce_directives`
+
+Default: `["script-src", "style-src"]`
+
+An array of directives where a dynamically-generated nonce will be included.
+
+For example, if this setting is set to `["script-src"]`, a `nonce-
+
+
+
+
+
+
+## How-to's
+
+
+
+
+
+
+## Reference
+
+
+
+
+
diff --git a/docs/versioned_docs/version-0.4/emailing/callbacks.md b/docs/versioned_docs/version-0.4/emailing/callbacks.md
new file mode 100644
index 000000000..26b134807
--- /dev/null
+++ b/docs/versioned_docs/version-0.4/emailing/callbacks.md
@@ -0,0 +1,111 @@
+---
+title: Email callbacks
+description: Learn how to define email callbacks.
+sidebar_label: Callbacks
+---
+
+Callbacks enable you to define logic that is triggered at different stages of an email's lifecycle. This document covers the available callbacks and introduces you to the associated API, which you can use to define hooks in your emails.
+
+## Overview
+
+As stated above, callbacks are methods that will be called when specific events occur for a specific email instance. They need to be registered explicitly in your email classes.
+
+Registering a callback is as simple as calling the right callback macro (eg. `#before_deliver`) with a symbol of the name of the method to call when the callback is executed.
+
+For example, the following email leverages the [`#after_deliver`](#after_deliver) callback in order to emit a specific StatsD metric:
+
+```crystal
+require "statsd"
+
+statsd = Statsd::Client.new
+
+class WelcomeEmail < Marten::Email
+ from "no-reply@martenframework.com"
+ to @user.email
+ subject "Hello!"
+ template_name "emails/welcome_email.html"
+
+ after_deliver :emit_delivered_welcome_email_metric
+
+ def initialize(@user : User)
+ end
+
+ private def emit_delivered_welcome_email_metric
+ statsd.increment "email.welcome.delivered", tags: ["app:myapp"]
+ end
+end
+```
+
+## Available callbacks
+
+### `before_deliver`
+
+`before_deliver` callbacks are executed _before_ an email is delivered (as part of the email's [`#deliver`](pathname:///api/0.4/Marten/Emailing/Email.html#deliver-instance-method) method). For example, this capability can be leveraged to mutate the considered email instance before the actual email gets delivered:
+
+```crystal
+class WelcomeEmail < Marten::Email
+ from "no-reply@martenframework.com"
+ to @user.email
+ subject "Hello!"
+ template_name "emails/welcome_email.html"
+
+ before_deliver :set_header
+
+ def initialize(@user : User)
+ end
+
+ private def set_header
+ headers["X-Debug"] = "True" if Marten.env.staging?
+ end
+end
+```
+
+### `after_deliver`
+
+`after_deliver` callbacks are executed _after_ an email is delivered (as part of the email's [`#deliver`](pathname:///api/0.4/Marten/Emailing/Email.html#deliver-instance-method) method). For example, such callbacks can be leveraged to increment email-specific metrics:
+
+```crystal
+require "statsd"
+
+statsd = Statsd::Client.new
+
+class WelcomeEmail < Marten::Email
+ from "no-reply@martenframework.com"
+ to @user.email
+ subject "Hello!"
+ template_name "emails/welcome_email.html"
+
+ after_deliver :emit_delivered_welcome_email_metric
+
+ def initialize(@user : User)
+ end
+
+ private def emit_delivered_welcome_email_metric
+ statsd.increment "email.welcome.delivered", tags: ["app:myapp"]
+ end
+end
+```
+
+### `before_render`
+
+`before_render` callbacks are invoked prior to rendering a template when generating the HTML or text body of the email. This means that these callbacks are executed when calling either the [`#deliver`](pathname:///api/0.4/Marten/Emailing/Email.html#deliver-instance-method), [`#html_body`](pathname:///api/0.4/Marten/Emailing/Email.html#html_body%3AString|Nil-instance-method), or [`#text_body`](pathname:///api/0.4/Marten/Emailing/Email.html#text_body%3AString|Nil-instance-method) methods.
+
+Typically, these callbacks can be used to add new variables to the global email template context, in order to make them available to the template runtime. This can be useful if your email has some instance variables that you want to expose to your email template. For example:
+
+```crystal
+class WelcomeEmail < Marten::Email
+ from "no-reply@martenframework.com"
+ to @user.email
+ subject "Hello!"
+ template_name "emails/welcome_email.html"
+
+ before_render :prepare_context
+
+ def initialize(@user : User)
+ end
+
+ private def prepare_context
+ context[:user] = @user
+ end
+end
+```
diff --git a/docs/versioned_docs/version-0.4/emailing/how-to/create-custom-emailing-backends.md b/docs/versioned_docs/version-0.4/emailing/how-to/create-custom-emailing-backends.md
new file mode 100644
index 000000000..6f3fea07a
--- /dev/null
+++ b/docs/versioned_docs/version-0.4/emailing/how-to/create-custom-emailing-backends.md
@@ -0,0 +1,30 @@
+---
+title: Create emailing backends
+description: How to create custom emailing backends.
+---
+
+Marten lets you easily create custom [emailing backends](../introduction.md#emailing-backends) that you can then use as part of your application when it comes to sending emails.
+
+## Basic backend definition
+
+Defining an emailing backend is as simple as creating a class that inherits from the [`Marten::Emailing::Backend::Base`](pathname:///api/0.4/Marten/Emailing/Backend/Base.html) abstract class and that implements a unique `#deliver` method. This method takes a single `email` argument (instance of [`Marten::Emailing::Email`](pathname:///api/0.4/Marten/Emailing/Email.html)), corresponding to the email to deliver.
+
+For example:
+
+```crystal
+class CustomEmailingBackend < Marten::Emailing::Backend::Base
+ def deliver(email : Email)
+ # Deliver the email!
+ end
+end
+```
+
+## Enabling the use of custom emailing backends
+
+Custom emailing backends can be used by assigning an instance of the corresponding class to the [`emailing.backend`](../../development/reference/settings.md#backend-1) setting.
+
+For example:
+
+```crystal
+config.emailing.backend = CustomEmailingBackend.new
+```
diff --git a/docs/versioned_docs/version-0.4/emailing/introduction.md b/docs/versioned_docs/version-0.4/emailing/introduction.md
new file mode 100644
index 000000000..e5cfb4132
--- /dev/null
+++ b/docs/versioned_docs/version-0.4/emailing/introduction.md
@@ -0,0 +1,170 @@
+---
+title: Introduction to emails
+description: Learn how to define emails in a Marten project and how to deliver them.
+sidebar_label: Introduction
+---
+
+Marten lets you define emails in a very declarative way and gives you the ability to fully customize the content of these emails, their properties and associated header values, and obviously how they should be delivered.
+
+## Email definition
+
+Emails must be defined as subclasses of the [`Emailing::Email`](pathname:///api/0.4/Marten/Emailing/Email.html) abstract class and they usually live in an `emails` folder at the root of an application. These classes can define to which email addresses the email is sent (including CC or BCC addresses) and with which [templates](../templates.mdx) the body of the email (HTML or plain text) is rendered.
+
+For example, the following snippet defines a simple email that is sent to a specific user's email address:
+
+```crystal
+class WelcomeEmail < Marten::Email
+ from "no-reply@martenframework.com"
+ to @user.email
+ subject "Hello!"
+ template_name "emails/welcome_email.html"
+
+ def initialize(@user : User)
+ end
+end
+```
+
+:::info
+It is not necessary to systematically specify the `from` email address with the [`#from`](pathname:///api/0.4/Marten/Emailing/Email.html#from(value)-macro) macro. Indeed, unless specified, the default "from" email address that is defined in the [`emailing.from_address`](../development/reference/settings.md#from_address) setting is automatically used.
+:::
+
+In the above snippet, a `WelcomeEmail` email class is defined by inheriting from the [`Emailing::Email`](pathname:///api/0.4/Marten/Emailing/Email.html) abstract class. This email is initialized with a hypothetical `User` record, and this user's email address is used as the recipient email (through the use of the [`#to`](pathname:///api/0.4/Marten/Emailing/Email.html#to(value)-macro) macro). Other email properties are also defined in the above snippet, such as the "from" email address ([`#from`](pathname:///api/0.4/Marten/Emailing/Email.html#from(value)-macro) macro) and the subject of the email ([`#subject`](pathname:///api/0.4/Marten/Emailing/Email.html#subject(value)-macro) macro).
+
+### Specifying email properties
+
+Most email properties (eg. from address, recipient addresses, etc) can be specified in two ways:
+
+* through the use of a dedicated macro
+* by overriding a corresponding method in the email class
+
+Indeed, it is convenient to define email properties through the use of the dedicated macros: [`#from`](pathname:///api/0.4/Marten/Emailing/Email.html#from(value)-macro) for the sender email, [`#to`](pathname:///api/0.4/Marten/Emailing/Email.html#to(value)-macro) for the recipient addresses, [`#cc`](pathname:///api/0.4/Marten/Emailing/Email.html#cc(value)-macro) for the CC addresses, [`#bcc`](pathname:///api/0.4/Marten/Emailing/Email.html#bcc(value)-macro) for the BCC addresses, [`#reply_to`](pathname:///api/0.4/Marten/Emailing/Email.html#reply_to(value)-macro) for the Reply-To address, and [`#subject`](pathname:///api/0.4/Marten/Emailing/Email.html#subject(value)-macro) for the email subject.
+
+That being said, if more complicated logics need to be implemented to generate these email properties, it is perfectly possible to simply override the corresponding method in the considered email class. For example:
+
+```crystal
+class WelcomeEmail < Marten::Email
+ from "no-reply@martenframework.com"
+ to @user.email
+ template_name "emails/welcome_email.html"
+
+ def initialize(@user : User)
+ end
+
+ def subject
+ if @user.referred?
+ "Glad to see you here!"
+ else
+ "Welcome to the app!"
+ end
+ end
+end
+```
+
+### Defining HTML and text bodies
+
+The HTML body (and optionally text body) of the email is rendered using a [template](../templates.mdx) whose name can be specified by using the [`#template_name`](pathname:///api/0.4/Marten/Emailing/Email.html#template_name(template_name%3AString%3F%2Ccontent_type%3AContentType|String|Symbol%3DContentType%3A%3AHTML)%3ANil-class-method) class method. By default, unless explicitly specified, it is assumed that the template specified to this method is used for rendering the HTML body of the email. That being said, it is possible to explicitly specify for which content type the template should be used by specifying an optional `content_type` argument as follows:
+
+```crystal
+class WelcomeEmail < Marten::Email
+ to @user.email
+ subject "Hello!"
+ template_name "emails/welcome_email.html", content_type: :html
+ template_name "emails/welcome_email.txt", content_type: :text
+
+ def initialize(@user : User)
+ end
+end
+```
+
+Note that it is perfectly valid to specify one template for rendering the HTML body AND another one for rendering the text body (like in the above example).
+
+:::info
+Note that you can define [`#html_body`](pathname:///api/0.4/Marten/Emailing/Email.html#html_body%3AString%3F-instance-method) and [`#text_body`](pathname:///api/0.4/Marten/Emailing/Email.html#html_body%3AString%3F-instance-method) methods if you need to override the logic that allows generating the HTML or text body of your email.
+:::
+
+### Modifying the template context
+
+All emails have access to a [`#context`](pathname:///api/0.4/Marten/Emailing/Email.html#context-instance-method) method that returns a [template](../templates/introduction.md) context object. This "global" context object is available for the lifetime of the considered email and can be mutated in order to define which variables are made available to the template runtime when rendering templates in order to generate the HTML/text bodies of your email (which happens when [sending the email](#sending-emails)).
+
+To modify this context object effectively, it's recommended to utilize [`before_render`](./callbacks.md#before_render) callbacks, which are invoked just before rendering a template within your email. For example, this can be achieved as follows:
+
+```crystal
+class WelcomeEmail < Marten::Email
+ from "no-reply@martenframework.com"
+ to @user.email
+ subject "Hello!"
+ template_name "emails/welcome_email.html"
+
+ before_render :prepare_context
+
+ def initialize(@user : User)
+ end
+
+ private def prepare_context
+ context[:user] = @user
+ end
+end
+```
+
+In the above example, the [`before_render`](./callbacks.md#before_render) callback simply assigns a new `user` variable to the email template context. Consequently, a corresponding `{{ user }}` variable will be available in the template configured for this email (`emails/welcome_email.html` in this case).
+
+### Defining custom headers
+
+If you need to insert custom headers into your emails, then you can easily do so by defining a `#headers` method in your email class. This method must return a hash of string keys and values.
+
+For example:
+
+```crystal
+class WelcomeEmail < Marten::Email
+ to @user.email
+ template_name "emails/welcome_email.html"
+
+ def initialize(@user : User)
+ end
+
+ def headers
+ {"X-Foo" => "bar"}
+ end
+end
+```
+
+## Sending emails
+
+Emails are sent _synchronously_ through the use of the [`#deliver`](pathname:///api/0.4/Marten/Emailing/Email.html#deliver-instance-method). For example, the `WelcomeEmail` email defined in the previous sections could be initialized and delivered by doing:
+
+```crystal
+email = WelcomeEmail.new(user)
+email.deliver
+```
+
+When calling [`#deliver`](pathname:///api/0.4/Marten/Emailing/Email.html#deliver-instance-method), the considered email will be delivered by using the currently configured [emailing backend](#emailing-backends).
+
+## Emailing backends
+
+Emailing backends define _how_ emails are actually sent when [`#deliver`](pathname:///api/0.4/Marten/Emailing/Email.html#deliver-instance-method) gets called. For example, a [development backend](./reference/backends.md#development-backend) might simply "collect" the sent emails and print their information to the standard output. Other backends might also integrate with existing email services or interact with an SMTP server to ensure email delivery.
+
+Which backend is used when sending emails is something that is controlled by the [`emailing.backend`](../development/reference/settings.md#backend-1) setting. All the available emailing backends are listed in the [emailing backend reference](./reference/backends.md).
+
+:::tip
+If necessary, it is also possible to override which emailing backend is used on a per-email basis by leveraging the [`#backend`](pathname:///api/0.4/Marten/Emailing/Email.html#backend(backend%3ABackend%3A%3ABase)%3ANil-class-method) class method. For example:
+
+```crystal
+class WelcomeEmail < Marten::Email
+ from "no-reply@martenframework.com"
+ to @user.email
+ subject "Hello!"
+ template_name "emails/welcome_email.html"
+
+ backend Marten::Emailing::Backend::Development.new(print_emails: true)
+
+ def initialize(@user : User)
+ end
+end
+```
+:::
+
+## Callbacks
+
+It is possible to define callbacks in order to bind methods and logics to specific events in the lifecycle of your emails. For example, it is possible to define callbacks that run before or after an email gets delivered.
+
+Please head over to the [Email callbacks](./callbacks.md) guide in order to learn more about email callbacks.
diff --git a/docs/versioned_docs/version-0.4/emailing/reference/backends.md b/docs/versioned_docs/version-0.4/emailing/reference/backends.md
new file mode 100644
index 000000000..31fb6d474
--- /dev/null
+++ b/docs/versioned_docs/version-0.4/emailing/reference/backends.md
@@ -0,0 +1,31 @@
+---
+title: Emailing backends
+description: Emailing backends reference.
+sidebar_label: Backends
+---
+
+## Built-in backends
+
+### Development backend
+
+This is the default backend used as part of the [`emailing.backend`](../../development/reference/settings.md#backend-1) setting.
+
+This backend "collects" all the emails that are "delivered", which can be used in specs in order to test sent emails. This "collect" behavior can be disabled if necessary, and the backend can also be configured to print email details to the standard output.
+
+For example:
+
+```crystal
+config.emailing.backend = Marten::Emailing::Backend::Development.new(print_emails: true, collect_emails: false)
+```
+
+## Other backends
+
+Additional emailing backend shards are also maintained under the umbrella of the Marten project or by the community itself and can be used as part of your application depending on your specific email sending requirements:
+
+* [`marten-smtp-emailing`](https://github.com/martenframework/marten-smtp-emailing) provides an SMTP emailing backend
+* [`marten-sendgrid-emailing`](https://github.com/martenframework/marten-sendgrid-emailing) provides a [Sendgrid](https://sendgrid.com/) emailing backend
+* [`marten-mailgun-emailing`](https://github.com/martenframework/marten-mailgun-emailing) provides a [Mailgun](https://www.mailgun.com/) emailing backend
+
+:::info
+Feel free to contribute to this page and add links to your shards if you've created emailing backends that are not listed here!
+:::
diff --git a/docs/versioned_docs/version-0.1/files.mdx b/docs/versioned_docs/version-0.4/files.mdx
similarity index 62%
rename from docs/versioned_docs/version-0.1/files.mdx
rename to docs/versioned_docs/version-0.4/files.mdx
index d44af57d6..1ec2b505c 100644
--- a/docs/versioned_docs/version-0.1/files.mdx
+++ b/docs/versioned_docs/version-0.4/files.mdx
@@ -4,7 +4,7 @@ title: Files
import DocCard from '@theme/DocCard';
-Dealing with files is a common requirement for web applications. This section covers how to handle uploaded files and static assets.
+Dealing with files is a common requirement for web applications. This section covers how to upload and manage files.
## Guides
@@ -15,7 +15,12 @@ Dealing with files is a common requirement for web applications. This section co
+
+
diff --git a/docs/versioned_docs/version-0.4/files/how-to/create-custom-file-storages.md b/docs/versioned_docs/version-0.4/files/how-to/create-custom-file-storages.md
new file mode 100644
index 000000000..9f9240015
--- /dev/null
+++ b/docs/versioned_docs/version-0.4/files/how-to/create-custom-file-storages.md
@@ -0,0 +1,78 @@
+---
+title: Create custom file storages
+description: Learn how to create custom file storages.
+---
+
+Marten uses a file storage mechanism to perform file operations like saving files, deleting files, generating URLs, ... This file storages mechanism allows to save files in different backends by leveraging a standardized API. You can leverage this capability to implement custom file storages (which you can then use for [assets](../../assets/introduction.md) or as part of [file model fields](../uploading-files.md#persisting-uploaded-files-in-model-records)).
+
+## Basic file storage implementation
+
+File storages are implemented as subclasses of the [`Marten::Core::Storage::Base`](pathname:///api/0.4/Marten/Core/Storage/Base.html) abstract class. As such, they must implement a set of mandatory methods which provide the following functionalities:
+
+* saving files ([`#save`](pathname:///api/0.4/Marten/Core/Storage/Base.html#save(filepath%3AString%2Ccontent%3AIO)%3AString-instance-method))
+* deleting files ([`#delete`](pathname:///api/0.4/Marten/Core/Storage/Base.html#delete(filepath%3AString)%3ANil-instance-method))
+* opening files ([`#open`](pathname:///api/0.4/Marten/Core/Storage/Base.html#open(filepath%3AString)%3AIO-instance-method))
+* verifying that files exist ([`#exist?`](pathname:///api/0.4/Marten/Core/Storage/Base.html#exists%3F(filepath%3AString)%3ABool-instance-method))
+* retrieving file sizes ([`#size`](pathname:///api/0.4/Marten/Core/Storage/Base.html#size(filepath%3AString)%3AInt64-instance-method))
+* retrieving file URLs ([`#url`](pathname:///api/0.4/Marten/Core/Storage/Base.html#url(filepath%3AString)%3AString-instance-method))
+
+Note that you can fully customize how file storage objects are initialized.
+
+For example, a custom-made "file system" storage (that reads and writes files in a specific folder of the local file system) could be implemented as follows:
+
+```crystal
+require "file_utils"
+
+class FileSystem < Marten::Core::Storage::Base
+ def initialize(@root : String, @base_url : String)
+ end
+
+ def delete(filepath : String) : Nil
+ File.delete(path(filepath))
+ rescue File::NotFoundError
+ raise Marten::Core::Storage::Errors::FileNotFound.new("File '#{filepath}' cannot be found")
+ end
+
+ def exists?(filepath : String) : Bool
+ File.exists?(path(filepath))
+ end
+
+ def open(filepath : String) : IO
+ File.open(path(filepath), mode: "rb")
+ rescue File::NotFoundError
+ raise Marten::Core::Storage::Errors::FileNotFound.new("File '#{filepath}' cannot be found")
+ end
+
+ def size(filepath : String) : Int64
+ File.size(path(filepath))
+ end
+
+ def url(filepath : String) : String
+ File.join(base_url, URI.encode_path(filepath))
+ end
+
+ def write(filepath : String, content : IO) : Nil
+ new_path = path(filepath)
+
+ FileUtils.mkdir_p(Path[new_path].dirname)
+
+ File.open(new_path, "wb") do |new_file|
+ IO.copy(content, new_file)
+ end
+ end
+
+ private getter root
+ private getter base_url
+
+ private def path(filepath)
+ File.join(root, filepath)
+ end
+end
+```
+
+## Using custom file storages
+
+You have many options when it comes to using your custom file storage classes, and those depend on what you are trying to do:
+
+* if you want to use a custom storage for [assets](../../assets/introduction.md), then you will likely want to assign an instance of your custom storage class to the [`assets.storage`](../../development/reference/settings.md#storage) setting (see [Assets storage](../../assets/introduction.md#assets-storage) to learn more about assets storages specifically)
+* if you want to use a custom storage for all your [file model fields](../../models-and-databases/reference/fields.md#file), then you will likely want to assign an instance of your custom storage class to the [`media_files.storage`](../../development/reference/settings.md#storage-1) setting (see [File storages](../managing-files.md#file-storages) to learn more about file storages specifically)
diff --git a/docs/versioned_docs/version-0.1/files/managing-files.md b/docs/versioned_docs/version-0.4/files/managing-files.md
similarity index 90%
rename from docs/versioned_docs/version-0.1/files/managing-files.md
rename to docs/versioned_docs/version-0.4/files/managing-files.md
index e29255a30..0c1d3f059 100644
--- a/docs/versioned_docs/version-0.1/files/managing-files.md
+++ b/docs/versioned_docs/version-0.4/files/managing-files.md
@@ -30,7 +30,7 @@ attachment.file.size # => 5796929
attachment.file.url # => "/media/test.txt"
```
-The object returned by the `Attachment#file` method is a "file object": an instance of [`Marten::DB::Field::File::File`](pathname:///api/0.1/Marten/DB/Field/File/File.html). These objects and their associated capabilities are described below in [File objects](#file-objects).
+The object returned by the `Attachment#file` method is a "file object": an instance of [`Marten::DB::Field::File::File`](pathname:///api/0.4/Marten/DB/Field/File/File.html). These objects and their associated capabilities are described below in [File objects](#file-objects).
:::tip Under which path are files persisted?
Files are stored at the root of the media [storage](#file-storages) by default. It should be noted that the path used to persist files in storages can be configured by setting the `upload_to` [`file`](../models-and-databases/reference/fields.md#file) field option.
@@ -71,14 +71,14 @@ You don't need to take care of possible collisions between attached file names:
## File objects
-As mentioned previously, file objects are used internally by Marten to allow interacting with files that are associated with model records. These objects are instances of the [`Marten::DB::Field::File::File`](pathname:///api/0.1/Marten/DB/Field/File/File.html) class. They give access to basic file properties and they allow to interact with the associated IO.
+As mentioned previously, file objects are used internally by Marten to allow interacting with files that are associated with model records. These objects are instances of the [`Marten::DB::Field::File::File`](pathname:///api/0.4/Marten/DB/Field/File/File.html) class. They give access to basic file properties and they allow to interact with the associated IO.
It should be noted that these "file objects" are **always** associated with a model record (persisted or not), and as such, they are only used in the context of the [`file`](../models-and-databases/reference/fields.md#file) model field.
Finally, it's worth mentioning that file objects can be **attached** and/or **committed**:
-* an **attached** file object has an associated file set: in that case, its [`#attached?`](pathname:///api/0.1/Marten/DB/Field/File/File.html#attached%3F-instance-method) method returns `true`
-* a **committed** file object has an associated file that is _persisted_ to the underlying [storage](#file-storages): in that case, its [`#committed?`](pathname:///api/0.1/Marten/DB/Field/File/File.html#committed%3F%3ABool-instance-method) method returns `true`
+* an **attached** file object has an associated file set: in that case, its [`#attached?`](pathname:///api/0.4/Marten/DB/Field/File/File.html#attached%3F-instance-method) method returns `true`
+* a **committed** file object has an associated file that is _persisted_ to the underlying [storage](#file-storages): in that case, its [`#committed?`](pathname:///api/0.4/Marten/DB/Field/File/File.html#committed%3F%3ABool-instance-method) method returns `true`
For example:
@@ -94,14 +94,14 @@ File objects give access to basic file properties through the use of the followi
| Method | Description |
| ----------- | ----------- |
-| `#file` | Returns the associated / "wrapped" file object. This can be a real [`File`](https://crystal-lang.org/api/File.html) object, an uploaded file (instance of [`Marten::HTTP::UploadedFile`](pathname:///api/0.1/Marten/HTTP/UploadedFile.html)), or `nil` if no file is associated yet. |
+| `#file` | Returns the associated / "wrapped" file object. This can be a real [`File`](https://crystal-lang.org/api/File.html) object, an uploaded file (instance of [`Marten::HTTP::UploadedFile`](pathname:///api/0.4/Marten/HTTP/UploadedFile.html)), or `nil` if no file is associated yet. |
| `#name` | Returns the name of the file. |
| `#size` | Returns the size of the file, using the associated [storage](#file-storages). |
| `#url` | Returns the URL of the file, using the associated [storage](#file-storages). |
### Accessing the underlying file content
-File objects allow you to access the underlying file content through the use of the [`#open`](pathname:///api/0.1/Marten/DB/Field/File/File.html#open%3AIO-instance-method) method. This method returns an [`IO`](https://crystal-lang.org/api/IO.html) object.
+File objects allow you to access the underlying file content through the use of the [`#open`](pathname:///api/0.4/Marten/DB/Field/File/File.html#open%3AIO-instance-method) method. This method returns an [`IO`](https://crystal-lang.org/api/IO.html) object.
For example:
@@ -113,7 +113,7 @@ puts file_io.gets_to_end
### Updating the attached file
-It is possible to update the actual file of a "file object" by using the [`#save`](pathname:///api/0.1/Marten/DB/Field/File/File.html#save(filepath%3A%3A%3AString%2Ccontent%3AIO%2Csave%3Dfalse)%3ANil-instance-method) method. This method allows saving the content of a specified [`IO`](https://crystal-lang.org/api/IO.html) object and associating it with a specific file path in the underlying [storage](#file-storages).
+It is possible to update the actual file of a "file object" by using the [`#save`](pathname:///api/0.4/Marten/DB/Field/File/File.html#save(filepath%3A%3A%3AString%2Ccontent%3AIO%2Csave%3Dfalse)%3ANil-instance-method) method. This method allows saving the content of a specified [`IO`](https://crystal-lang.org/api/IO.html) object and associating it with a specific file path in the underlying [storage](#file-storages).
For example:
@@ -130,7 +130,7 @@ attachment.file.url # => "/media/path/to/test.txt"
### Deleting the attached file
-It is also possible to manually "delete" the file associated with the "file object". To do so, the [`#delete`](pathname:///api/0.1/Marten/DB/Field/File/File.html#delete(save%3Dfalse)%3ANil-instance-method) method can be used. It should be noted that calling this method will remove the association between the model record and the file AND will also delete the file in the considered [storage](#file-storages).
+It is also possible to manually "delete" the file associated with the "file object". To do so, the [`#delete`](pathname:///api/0.4/Marten/DB/Field/File/File.html#delete(save%3Dfalse)%3ANil-instance-method) method can be used. It should be noted that calling this method will remove the association between the model record and the file AND will also delete the file in the considered [storage](#file-storages).
For example:
@@ -145,18 +145,18 @@ attachment.file.committed? # => false
Marten uses a file storage mechanism to perform file operations like saving files, deleting files, generating URLs, ... This file storages mechanism allows to save files in different backends by leveraging a standardized API (eg. in the local file system, in a cloud bucket, etc).
-By default, [`file`](../models-and-databases/reference/fields.md#file) model fields make use of the configured "media" storage. This storage uses the [`settings.media_files`](../development/reference/settings.md#media-files-settings) settings to determine what storage backend to use, and where to persist files. By default, the media storage uses the [`Marten::Core::Store::FileSystem`](pathname:///api/0.1/Marten/Core/Storage/FileSystem.html) storage backend, which ensures that files are persisted in the local file system, where the Marten application is running.
+By default, [`file`](../models-and-databases/reference/fields.md#file) model fields make use of the configured "media" storage. This storage uses the [`settings.media_files`](../development/reference/settings.md#media-files-settings) settings to determine what storage backend to use, and where to persist files. By default, the media storage uses the [`Marten::Core::Store::FileSystem`](pathname:///api/0.4/Marten/Core/Storage/FileSystem.html) storage backend, which ensures that files are persisted in the local file system, where the Marten application is running.
### Interacting with the media file storage
-You won't usually need to interact directly with the file storage, but it's worth mentioning that storage objects share the same API. Indeed, the class of these storage objects must inherit from the [`Marten::Core::Storage::Base`](pathname:///api/0.1/Marten/Core/Storage/Base.html) abstract class and implement a set of mandatory methods which provide the following functionalities:
+You won't usually need to interact directly with the file storage, but it's worth mentioning that storage objects share the same API. Indeed, the class of these storage objects must inherit from the [`Marten::Core::Storage::Base`](pathname:///api/0.4/Marten/Core/Storage/Base.html) abstract class and implement a set of mandatory methods which provide the following functionalities:
-* saving files ([`#save`](pathname:///api/0.1/Marten/Core/Storage/Base.html#save(filepath%3AString%2Ccontent%3AIO)%3AString-instance-method))
-* deleting files ([`#delete`](pathname:///api/0.1/Marten/Core/Storage/Base.html#delete(filepath%3AString)%3ANil-instance-method))
-* opening files ([`#open`](pathname:///api/0.1/Marten/Core/Storage/Base.html#open(filepath%3AString)%3AIO-instance-method))
-* verifying that files exist ([`#exist?`](pathname:///api/0.1/Marten/Core/Storage/Base.html#exists%3F(filepath%3AString)%3ABool-instance-method))
-* retrieving file sizes ([`#size`](pathname:///api/0.1/Marten/Core/Storage/Base.html#size(filepath%3AString)%3AInt64-instance-method))
-* retrieving file URLs ([`#url`](pathname:///api/0.1/Marten/Core/Storage/Base.html#url(filepath%3AString)%3AString-instance-method))
+* saving files ([`#save`](pathname:///api/0.4/Marten/Core/Storage/Base.html#save(filepath%3AString%2Ccontent%3AIO)%3AString-instance-method))
+* deleting files ([`#delete`](pathname:///api/0.4/Marten/Core/Storage/Base.html#delete(filepath%3AString)%3ANil-instance-method))
+* opening files ([`#open`](pathname:///api/0.4/Marten/Core/Storage/Base.html#open(filepath%3AString)%3AIO-instance-method))
+* verifying that files exist ([`#exist?`](pathname:///api/0.4/Marten/Core/Storage/Base.html#exists%3F(filepath%3AString)%3ABool-instance-method))
+* retrieving file sizes ([`#size`](pathname:///api/0.4/Marten/Core/Storage/Base.html#size(filepath%3AString)%3AInt64-instance-method))
+* retrieving file URLs ([`#url`](pathname:///api/0.4/Marten/Core/Storage/Base.html#url(filepath%3AString)%3AString-instance-method))
These capabilities are highlighted with the following example, where the media storage is used to interact with files:
@@ -207,7 +207,7 @@ When doing this, all the file operations will be done using the configured stora
## Serving uploaded files during development
-Marten provides a handler that you can use to serve media files in development environments only. This handler ([`Marten::Handlers::Defaults::Development::ServeMediaFile`](pathname:///api/0.1/Marten/Handlers/Defaults/Development/ServeMediaFile.html)) is automatically mapped to a route when creating new projects through the use of the [`new`](../development/reference/management-commands.md#new) management command:
+Marten provides a handler that you can use to serve media files in development environments only. This handler ([`Marten::Handlers::Defaults::Development::ServeMediaFile`](pathname:///api/0.4/Marten/Handlers/Defaults/Development/ServeMediaFile.html)) is automatically mapped to a route when creating new projects through the use of the [`new`](../development/reference/management-commands.md#new) management command:
```crystal
Marten.routes.draw do
@@ -222,5 +222,5 @@ end
As you can see, this route will automatically use the URL that is configured as part of the [`url`](../development/reference/settings.md#url-1) media files setting. For example, this means that a `foo/bar.txt` media file would be served by the `/media/foo/bar.txt` route in development if the [`url`](../development/reference/settings.md#url-1) setting is set to `/media/`.
:::warning
-It is very important to understand that this handler should **only** be used in development environments. Indeed, the [`Marten::Handlers::Defaults::Development::ServeMediaFile`](pathname:///api/0.1/Marten/Handlers/Defaults/Development/ServeMediaFile.html) handler is not suited for production environments as it is not really efficient or secure. A better way to serve uploaded files is to leverage a web server or a cloud bucket for example (depending on the configured media files storage).
+It is very important to understand that this handler should **only** be used in development environments. Indeed, the [`Marten::Handlers::Defaults::Development::ServeMediaFile`](pathname:///api/0.4/Marten/Handlers/Defaults/Development/ServeMediaFile.html) handler is not suited for production environments as it is not really efficient or secure. A better way to serve uploaded files is to leverage a web server or a cloud bucket for example (depending on the configured media files storage).
:::
diff --git a/docs/versioned_docs/version-0.1/files/uploading-files.md b/docs/versioned_docs/version-0.4/files/uploading-files.md
similarity index 90%
rename from docs/versioned_docs/version-0.1/files/uploading-files.md
rename to docs/versioned_docs/version-0.4/files/uploading-files.md
index 164490248..87c5d5c2b 100644
--- a/docs/versioned_docs/version-0.1/files/uploading-files.md
+++ b/docs/versioned_docs/version-0.4/files/uploading-files.md
@@ -8,7 +8,7 @@ Marten gives you the ability to interact with uploaded files. These files are ma
## Accessing uploaded files
-Uploaded files are made available in the [`#data`](pathname:///api/0.1/Marten/HTTP/Request.html#data%3AParams%3A%3AData-instance-method) hash-like object of any HTTP request object (instance of [`Marten::HTTP::Request`](pathname:///api/0.1/Marten/HTTP/Request.html)). These file objects are instances of the [`Marten::HTTP::UploadedFile`](pathname:///api/0.1/Marten/HTTP/UploadedFile.html) class.
+Uploaded files are made available in the [`#data`](pathname:///api/0.4/Marten/HTTP/Request.html#data%3AParams%3A%3AData-instance-method) hash-like object of any HTTP request object (instance of [`Marten::HTTP::Request`](pathname:///api/0.4/Marten/HTTP/Request.html)). These file objects are instances of the [`Marten::HTTP::UploadedFile`](pathname:///api/0.4/Marten/HTTP/UploadedFile.html) class.
For example, you could access and process a `file` file originating from an HTML form using a handler like this:
@@ -21,7 +21,7 @@ class ProcessUploadedFileHandler < Marten::Handler
end
```
-[`Marten::HTTP::UploadedFile`](pathname:///api/0.1/Marten/HTTP/UploadedFile.html) objects give you access to the following key methods, which allow you to interact with the uploaded file and its content:
+[`Marten::HTTP::UploadedFile`](pathname:///api/0.4/Marten/HTTP/UploadedFile.html) objects give you access to the following key methods, which allow you to interact with the uploaded file and its content:
* `#filename` returns the name of the uploaded file
* `#size` returns the size of the uploaded file
@@ -84,4 +84,4 @@ class UploadFileHandler < Marten::Handlers::Schema
end
```
-Here, the `UploadFileHandler` inherits from the [`Marten::Handlers::Schema`](pathname:///api/0.1/Marten/Handlers/Schema.html) generic handler. It would also make sense to leverage the [`Marten::Handlers::RecordCreate`](pathname:///api/0.1/Marten/Handlers/RecordCreate.html) generic handler to process the schema and create the `Attachment` record at the same time.
+Here, the `UploadFileHandler` inherits from the [`Marten::Handlers::Schema`](pathname:///api/0.4/Marten/Handlers/Schema.html) generic handler. It would also make sense to leverage the [`Marten::Handlers::RecordCreate`](pathname:///api/0.4/Marten/Handlers/RecordCreate.html) generic handler to process the schema and create the `Attachment` record at the same time.
diff --git a/docs/versioned_docs/version-0.1/getting-started.mdx b/docs/versioned_docs/version-0.4/getting-started.mdx
similarity index 100%
rename from docs/versioned_docs/version-0.1/getting-started.mdx
rename to docs/versioned_docs/version-0.4/getting-started.mdx
diff --git a/docs/versioned_docs/version-0.1/getting-started/installation.md b/docs/versioned_docs/version-0.4/getting-started/installation.md
similarity index 65%
rename from docs/versioned_docs/version-0.1/getting-started/installation.md
rename to docs/versioned_docs/version-0.4/getting-started/installation.md
index 62aec745e..cc44cbcfb 100644
--- a/docs/versioned_docs/version-0.1/getting-started/installation.md
+++ b/docs/versioned_docs/version-0.4/getting-started/installation.md
@@ -3,7 +3,6 @@ title: Installation
description: Get started by installing Marten and its dependencies.
---
-
This guide will help you get started in order to install Marten and its dependencies. Let's get started!
## Install Crystal
@@ -26,9 +25,17 @@ On Ubuntu, Debian or any other Linux distribution using the APT package manager,
curl -fsSL https://crystal-lang.org/install.sh | sudo bash
```
+### Using pacman
+
+On ArchLinux and derivates you can install Crystal and the `shards` command line tool through Pacman:
+
+```bash
+sudo pacman -S crystal shards
+```
+
## Install a database
-New Marten projects will use a SQLite database by default: this lightweight serverless database application is usually already pre-installed on most of the existing operating systems, which makes it an ideal candidate for a development or a testing database. As such, if you choose to use SQLite for your new Marten project, you can very probably skip this section.
+Marten officially supports **MySQL**, **PostgreSQL**, and **SQLite3** databases. New Marten projects will use a SQLite database by default: this lightweight serverless database application is usually already pre-installed on most of the existing operating systems, which makes it an ideal candidate for a development or a testing database. As such, if you choose to use SQLite for your new Marten project, you can very probably skip this section.
Marten also has built-in support for PostgreSQL and MySQL. Please refer to the applicable official documentation to install your database of choice:
@@ -36,11 +43,7 @@ Marten also has built-in support for PostgreSQL and MySQL. Please refer to the a
* [MySQL Installation Guide](https://dev.mysql.com/doc/refman/8.0/en/installing.html)
* [SQLite Installation Guide](https://www.tutorialspoint.com/sqlite/sqlite_installation.htm)
-Each database requires the use of a dedicated shard (package of Crystal code). You don't have to install any of these right now if you are just starting with the framework or if you are planning to follow the [tutorial](./tutorial.md), but you may have to add one of the following entries to your project's `shard.yml` file later:
-
-* [crystal-pg](https://github.com/will/crystal-pg) (needed when using PostgreSQL databases)
-* [crystal-mysql](https://github.com/crystal-lang/crystal-mysql) (needed when using MySQL databases)
-* [crystal-sqlite3](https://github.com/crystal-lang/crystal-sqlite3) (needed when using SQLite3 databases)
+Each database necessitates the use of a dedicated shard (a package of Crystal code). If you're just beginning with the framework or planning to follow the [tutorial](./tutorial.md), there's no immediate need to install these shards. However, if you intend to employ other databases like MySQL or PostgreSQL, you may need to install database-specific shards. You can find instructions on how to do this in the [Configure database backends](../development/how-to/configure-database-backends.md) section.
## Install Marten
@@ -55,6 +58,14 @@ brew tap martenframework/marten
brew install marten
```
+### Using AUR on ArchLinux and derivates
+
+Assuming you use some AUR helper (`yay` in this example) it will be as simple as:
+
+```bash
+yay -S marten
+```
+
Once the installation is complete, you should be able to use the `marten` command:
```bash
@@ -66,7 +77,7 @@ marten -v
Marten can be installed from the sources by running the following commands:
```bash
-git clone --branch v0.1.x https://github.com/martenframework/marten
+git clone https://github.com/martenframework/marten
cd marten
shards install
crystal build src/marten_cli.cr -o bin/marten
diff --git a/docs/versioned_docs/version-0.1/getting-started/tutorial.md b/docs/versioned_docs/version-0.4/getting-started/tutorial.md
similarity index 88%
rename from docs/versioned_docs/version-0.1/getting-started/tutorial.md
rename to docs/versioned_docs/version-0.4/getting-started/tutorial.md
index 537076eb0..e55a77f2b 100644
--- a/docs/versioned_docs/version-0.1/getting-started/tutorial.md
+++ b/docs/versioned_docs/version-0.4/getting-started/tutorial.md
@@ -44,6 +44,8 @@ myblog/
├── spec
│ └── spec_helper.cr
├── src
+│ ├── assets
+│ ├── emails
│ ├── handlers
│ ├── migrations
│ ├── models
@@ -52,6 +54,8 @@ myblog/
│ ├── cli.cr
│ ├── project.cr
│ └── server.cr
+├── .editorconfig
+├── .gitignore
├── manage.cr
└── shard.yml
```
@@ -62,7 +66,8 @@ These files and folders are described below:
| ----------- | ----------- |
| config/ | Contains the configuration of the project. This includes environment-specific Marten configuration settings, initializers, and web application routes. |
| spec/ | Contains the project specs, allowing you to test your application. |
-| src/ | Contains the source code of the application. By default this folder will include a `project.cr` file (where all dependencies - including Marten itself - are required), a `server.cr` file (which starts the Marten web server), a `cli.cr` file (where migrations and CLI-related abstractions are required), and empty `handlers`, `migrations`, `models`, `schemas`, and `templates` folders. |
+| src/ | Contains the source code of the application. By default this folder will include a `project.cr` file (where all dependencies - including Marten itself - are required), a `server.cr` file (which starts the Marten web server), a `cli.cr` file (where migrations and CLI-related abstractions are required), and `assets`, `emails`, `handlers`, `migrations`, `models`, `schemas`, and `templates` folders. |
+| .editorconfig | Regular `.editorconfig` which file defines basic indentation coding styles for Crystal. |
| .gitignore | Regular `.gitignore` file which tells git the files and directories that should be ignored. |
| manage.cr | This file defines a CLI that lets you interact with your Marten project in order to perform various actions (e.g. running database migrations, collecting assets, etc). |
| shard.yml | The standard [shard.yml](https://crystal-lang.org/reference/the_shards_command/index.html) file, that lists the dependencies that are required to build your application. |
@@ -315,25 +320,35 @@ Templates provide a convenient way for defining the presentation logic of a web
Let's define the expected template for our home handler by creating a `src/templates/home.html` file with the following content:
```html title="src/templates/home.html"
-My blog
-Articles:
--
-{% for article in articles %}
-
- {{ article.title }} -{% endfor %} -
My blog
+Articles:
+-
+ {% for article in articles %}
+
- {{ article.title }} + {% endfor %} +
{{ article.title }}
-{{ article.content }}
+{% extend "base.html" %} + +{% block content %} +{{ article.title }}
+{{ article.content }}
+{% endblock %} ``` Now if you try to access [http://localhost:8000/article/1](http://localhost:8000/article/1), you will be able to see the content of the `Article` record with ID 1. @@ -394,20 +413,24 @@ Now if you try to access [http://localhost:8000/article/1](http://localhost:8000 There is something missing though: the home page does not link to the "detail" page of each article. To remediate this, we can modify the `src/templates/home.html` template file as follows: ```html title="src/templates/home.html" -My blog
-Articles:
--
-{% for article in articles %}
-// highlight-next-line
-
- -// highlight-next-line - {{ article.title }} -// highlight-next-line - ‐ View -// highlight-next-line - -{% endfor %} -
My blog
+Articles:
+-
+ {% for article in articles %}
+ // highlight-next-line
+
- + // highlight-next-line + {{ article.title }} + // highlight-next-line + ‐ View + // highlight-next-line + + {% endfor %} +
Create a new article
- + + +{% endblock %} ``` As you can see, the above snippet defines a form that includes two fields: one for the `title` schema field and the other one for the `content` schema field. Each schema field can be errored depending on the result of a validation, and this is why specific field errors are (optionally) displayed as well. @@ -517,19 +538,22 @@ Now if you open your browser at [http://localhost:8000/article/create](http://lo Obviously, we still need to a link somewhere in our application to be able to easily access the article creation form. In this light, we can modify the `home.html` template file as follows: ```html title="src/templates/home.html" -My blog
-// highlight-next-line -Create new article -Articles:
--
-{% for article in articles %}
-
- - {{ article.title }} - ‐ View - -{% endfor %} -
My blog
+ // highlight-next-line + Create new article +Articles:
+-
+ {% for article in articles %}
+
- + {{ article.title }} + ‐ View + + {% endfor %} +
Update article "{{ article.title }}"
- + + +{% endblock %} ``` As you can see, this looks very similar to what we did previously with the `article_create.html` template file. @@ -627,19 +649,23 @@ Now if you open your browser at [http://localhost:8000/article/1/update](http:// We can also add a link somewhere in the home page of the application to be able to easily access the update form for existing articles. In this light, we can modify the `home.html` template file as follows: ```html title="src/templates/home.html" -My blog
-Create new article -Articles:
--
-{% for article in articles %}
-
- - {{ article.title }} - ‐ View - // highlight-next-line - ‐ Update - -{% endfor %} -
My blog
+ Create new article +Articles:
+-
+ {% for article in articles %}
+
- + {{ article.title }} + ‐ View + // highlight-next-line + ‐ Update + + {% endfor %} +
Delete article "{{ article.title }}"
-Are you sure?
- +{% extend "base.html" %} + +{% block content %} +Delete article "{{ article.title }}"
+Are you sure?
+ +{% endblock %} ``` This template simply asks the user for confirmation and displays a confirmation button embedded in a form to issue the POST request that will actually delete the record. @@ -707,20 +737,24 @@ Now if you open your browser at [http://localhost:8000/article/1/delete](http:// We can also add a link somewhere in the home page of the application to be able to easily access the delete confirmation page for existing articles. In this light, we can modify the `home.html` template file as follows: ```html title="src/templates/home.html" -My blog
-Create new article -Articles:
--
-{% for article in articles %}
-
- - {{ article.title }} - ‐ View - ‐ Update - // highlight-next-line - ‐ Delete - -{% endfor %} -
My blog
+ Create new article +Articles:
+-
+ {% for article in articles %}
+
- + {{ article.title }} + ‐ View + ‐ Update + // highlight-next-line + ‐ Delete + + {% endfor %} +
Create a new article
-{% include "partials/article_form.html" %} +{% extend "base.html" %} + +{% block content %} +Create a new article
+ {% include "partials/article_form.html" %} +{% endblock %} ``` ```html title="src/templates/article_update.html" -Update article "{{ article.title }}"
-{% include "partials/article_form.html" %} +{% extend "base.html" %} + +{% block content %} +Update article "{{ article.title }}"
+ {% include "partials/article_form.html" %} +{% endblock %} ``` As you can see, the creation and update templates are now much more simple. @@ -773,7 +809,7 @@ The handlers we implemented previously map to common web development use cases: We could definitely leverage these generic handlers as part of our weblog application. -In this light, let's start with the `HomeHandler` class we implemented earlier: this handler essentially retrieves all the `Article` records and makes this list available to the `home.html` template. This pattern is enabled by the [`Marten::Handlers::RecordList`](pathname:///api/0.1/Marten/Handlers/RecordList.html) generic handler. In order to use it, let's modify the `src/handlers/home_handler.cr` file as follows: +In this light, let's start with the `HomeHandler` class we implemented earlier: this handler essentially retrieves all the `Article` records and makes this list available to the `home.html` template. This pattern is enabled by the [`Marten::Handlers::RecordList`](pathname:///api/0.4/Marten/Handlers/RecordList.html) generic handler. In order to use it, let's modify the `src/handlers/home_handler.cr` file as follows: ```crystal title="src/handlers/home_handler.cr" class HomeHandler < Marten::Handlers::RecordList @@ -785,7 +821,7 @@ end In the above snippet we use a few class methods in order to define how the handler should behave: `#model` allows to define the model class that should be used to retrieve the record, `#template_name` allows to define the name of the template to render, and `#list_context_name` allows to define the name of the record list variable in the template context. -Let's continue with the `ArticleDetailHandler` class: this handler retrieves a specific `Article` record from a `pk` route parameter, and "renders" it using a specific template. This pattern is enabled by the [`Marten::Handlers::RecordDetail`](pathname:///api/0.1/Marten/Handlers/RecordDetail.html) generic handler. In order to use it, let's modify the `src/handlers/article_detail_handler.cr` file as follows: +Let's continue with the `ArticleDetailHandler` class: this handler retrieves a specific `Article` record from a `pk` route parameter, and "renders" it using a specific template. This pattern is enabled by the [`Marten::Handlers::RecordDetail`](pathname:///api/0.4/Marten/Handlers/RecordDetail.html) generic handler. In order to use it, let's modify the `src/handlers/article_detail_handler.cr` file as follows: ```crystal title="src/handlers/article_detail_handler.cr" class ArticleDetailHandler < Marten::Handlers::RecordDetail @@ -797,7 +833,7 @@ end In order to configure how the handler should behave, we make use of a few class methods here as well: `#model` allows to define the model class of the record that should be retrieved, `#template_name` defines the template to render, and `#record_context_name` defines the name of the record variable in the template context. -Now let's look at the `ArticleCreateHandler` class: this class displays a form when processing GET requests, and it validates a schema that is used to create a specific record when processing POST requests. This exact pattern is enabled by the [`Marten::Handlers::RecordCreate`](pathname:///api/0.1/Marten/Handlers/RecordCreate.html) generic handler. In order to use it, we can modify the `src/handlers/article_create_handler.cr` file as follows: +Now let's look at the `ArticleCreateHandler` class: this class displays a form when processing GET requests, and it validates a schema that is used to create a specific record when processing POST requests. This exact pattern is enabled by the [`Marten::Handlers::RecordCreate`](pathname:///api/0.4/Marten/Handlers/RecordCreate.html) generic handler. In order to use it, we can modify the `src/handlers/article_create_handler.cr` file as follows: ```crystal title="src/handlers/article_create_handler.cr" class ArticleCreateHandler < Marten::Handlers::RecordCreate @@ -810,7 +846,7 @@ end Here, `#model` allows to define the model class to use to create the new record, `#schema` is the schema class that should be used to validated the incoming data, `#template_name` defines the name of the template to render, and `#success_route_name` is the name of the route to redirect to after a successful record creation. -We can now look at the `ArticleUpdateHandler` class: this class retrieves a specific record and displays a form when processing GET requests, and it validates a schema whose data is used to update the record when processing POST requests. This pattern is enabled by the [`Marten::Handlers::RecordUpdate`](pathname:///api/0.1/Marten/Handlers/RecordUpdate.html) generic handler. Let's use it and let's modify the `src/handlers/article_update_handler.cr` file as follows: +We can now look at the `ArticleUpdateHandler` class: this class retrieves a specific record and displays a form when processing GET requests, and it validates a schema whose data is used to update the record when processing POST requests. This pattern is enabled by the [`Marten::Handlers::RecordUpdate`](pathname:///api/0.4/Marten/Handlers/RecordUpdate.html) generic handler. Let's use it and let's modify the `src/handlers/article_update_handler.cr` file as follows: ```crystal title="src/handlers/article_update_handler.cr" class ArticleUpdateHandler < Marten::Handlers::RecordUpdate @@ -824,7 +860,7 @@ end Here, `#model` allows to define the model class to use to retrieve and update the record, `#schema` is the schema class that should be used to validated the incoming data, `#template_name` defines the name of the template to render, `#success_route_name` is the name of the route to redirect to after a successful record update, and `#record_context_name` is the name of the record variable in the template context. -Finally, let's look at the `ArticleDeleteHandler` class: this handler renders a template when processing GET requests, and performs the deletion of the considered record when processing POST requests. This pattern is provided by the [`Marten::Handlers::RecordDelete`](pathname:///api/0.1/Marten/Handlers/RecordDelete.html) generic handler. In order to use it, let's modify the `src/handlers/article_delete_handler.cr` file as follows: +Finally, let's look at the `ArticleDeleteHandler` class: this handler renders a template when processing GET requests, and performs the deletion of the considered record when processing POST requests. This pattern is provided by the [`Marten::Handlers::RecordDelete`](pathname:///api/0.4/Marten/Handlers/RecordDelete.html) generic handler. In order to use it, let's modify the `src/handlers/article_delete_handler.cr` file as follows: ```crystal title="src/handlers/article_delete_handler.cr" class ArticleDeleteHandler < Marten::Handlers::RecordDelete diff --git a/docs/versioned_docs/version-0.1/handlers-and-http.mdx b/docs/versioned_docs/version-0.4/handlers-and-http.mdx similarity index 84% rename from docs/versioned_docs/version-0.1/handlers-and-http.mdx rename to docs/versioned_docs/version-0.4/handlers-and-http.mdx index 12a5613ca..de4f76bdf 100644 --- a/docs/versioned_docs/version-0.1/handlers-and-http.mdx +++ b/docs/versioned_docs/version-0.4/handlers-and-http.mdx @@ -21,11 +21,17 @@ Handlers are classes that process a web request and return a response. They impl
+ 
+
+
+
**Marten** is a Crystal Web framework that enables pragmatic development and rapid prototyping. It provides a consistent and extensible set of tools that developers can leverage to build web applications without reinventing the wheel.
@@ -21,4 +46,4 @@ The Marten documentation contains multiple pages and references that don't neces
* **Reference pages** provide a curated technical reference of the framework APIs
* **How-to guides** document how to solve common problems when working with the framework. Those can cover things like deployments, app development, etc
-Additionally, an automatically-generated [API reference](pathname:///api/0.1/index.html) is also available to dig into Marten's internals.
+Additionally, an automatically-generated [API reference](pathname:///api/0.4/index.html) is also available to dig into Marten's internals.
diff --git a/docs/versioned_docs/version-0.1/schemas.mdx b/docs/versioned_docs/version-0.4/schemas.mdx
similarity index 100%
rename from docs/versioned_docs/version-0.1/schemas.mdx
rename to docs/versioned_docs/version-0.4/schemas.mdx
diff --git a/docs/versioned_docs/version-0.1/schemas/how-to/create-custom-schema-fields.md b/docs/versioned_docs/version-0.4/schemas/how-to/create-custom-schema-fields.md
similarity index 97%
rename from docs/versioned_docs/version-0.1/schemas/how-to/create-custom-schema-fields.md
rename to docs/versioned_docs/version-0.4/schemas/how-to/create-custom-schema-fields.md
index 78d8c7808..971cf524c 100644
--- a/docs/versioned_docs/version-0.1/schemas/how-to/create-custom-schema-fields.md
+++ b/docs/versioned_docs/version-0.4/schemas/how-to/create-custom-schema-fields.md
@@ -21,7 +21,7 @@ When creating a custom schema field, there are usually two approaches that you c
Regardless of the approach you take in order to define new schema field classes ([subclassing built-in fields](#subclassing-existing-schema-fields), or [creating new ones from scratch](#creating-new-schema-fields-from-scratch)), these classes must be registered to the Marten's global fields registry in order to make them available for use when defining schemas.
-To do so, you will have to call the [`Marten::Schema::Field#register`](pathname:///api/0.1/Marten/Schema/Field.html#register(id%2Cfield_klass)-macro) method with the identifier of the field you wish to use, and the actual field class. For example:
+To do so, you will have to call the [`Marten::Schema::Field#register`](pathname:///api/0.4/Marten/Schema/Field.html#register(id%2Cfield_klass)-macro) method with the identifier of the field you wish to use, and the actual field class. For example:
```crystal
Marten::Schema::Field.register(:foo, FooField)
@@ -43,7 +43,7 @@ The call to `#register` can be made from anywhere in your codebase, but obviousl
This is probably the easiest way to create a custom field: if the field you want to create can be derived from one of the [built-in schema fields](../reference/fields.md) (usually those correspond to primitive types), then you can easily subclass the corresponding class and customize it so that it suits your needs.
-For example, implementing a custom "email" field could be done by subclassing the existing [`Marten::Schema::Field::String`](pathname:///api/0.1/Marten/Schema/Field/String.html) class. Indeed, an "email" field is essentially a string with a pre-defined maximum size and some additional validation logic:
+For example, implementing a custom "email" field could be done by subclassing the existing [`Marten::Schema::Field::String`](pathname:///api/0.4/Marten/Schema/Field/String.html) class. Indeed, an "email" field is essentially a string with a pre-defined maximum size and some additional validation logic:
```crystal
class EmailField < Marten::Schema::Field::String
@@ -75,7 +75,7 @@ Everything that is described in the following section about [creating schema fie
## Creating new schema fields from scratch
-Creating new schema fields from scratch involves subclassing the [`Marten::Schema::Field::Base`](pathname:///api/0.1/Marten/Schema/Field/Base.html) abstract class. Because of this, the new field class is required to implement a set of mandatory methods. These mandatory methods, and some other ones that are optional (but interesting in terms of capabilities), are described in the following sections.
+Creating new schema fields from scratch involves subclassing the [`Marten::Schema::Field::Base`](pathname:///api/0.4/Marten/Schema/Field/Base.html) abstract class. Because of this, the new field class is required to implement a set of mandatory methods. These mandatory methods, and some other ones that are optional (but interesting in terms of capabilities), are described in the following sections.
### Mandatory methods
@@ -124,7 +124,7 @@ Again, if the value can't be processed properly by the field class, it may be ne
#### `initialize`
-The default `#initialize` method that is provided by the [`Marten::Schema::Field::Base`](pathname:///api/0.1/Marten/Schema/Field/Base.html) is fairly simply and looks like this:
+The default `#initialize` method that is provided by the [`Marten::Schema::Field::Base`](pathname:///api/0.4/Marten/Schema/Field/Base.html) is fairly simply and looks like this:
```crystal
def initialize(
diff --git a/docs/versioned_docs/version-0.1/schemas/introduction.md b/docs/versioned_docs/version-0.4/schemas/introduction.md
similarity index 69%
rename from docs/versioned_docs/version-0.1/schemas/introduction.md
rename to docs/versioned_docs/version-0.4/schemas/introduction.md
index 822577d30..531ac5f5c 100644
--- a/docs/versioned_docs/version-0.1/schemas/introduction.md
+++ b/docs/versioned_docs/version-0.4/schemas/introduction.md
@@ -10,7 +10,7 @@ Schemas are classes that define how input data should be serialized/deserialized
### The schema class
-A schema class describes an _expected_ set of data. It describes the logical structure of this data, what are its expected characteristics, and what are the rules to use in order to identify whether it is valid or not. Schemas classes must inherit from the [`Marten::Schema`](pathname:///api/0.1/Marten/Schema.html) base class and they must define "fields" through the use of a `field` macro. These fields allow to define what data is expected by the schema, and how it is validated.
+A schema class describes an _expected_ set of data. It describes the logical structure of this data, what are its expected characteristics, and what are the rules to use in order to identify whether it is valid or not. Schemas classes must inherit from the [`Marten::Schema`](pathname:///api/0.4/Marten/Schema.html) base class and they must define "fields" through the use of a `field` macro. These fields allow to define what data is expected by the schema, and how it is validated.
For example, the following snippet defines a simple `ArticleSchema` schema:
@@ -64,7 +64,7 @@ end
Let's break it down a bit more:
* when the incoming request is a `GET`, the handler will simply render the `article_create.html` template, and initialize the schema (instance of `ArticleSchema`) with any data currently present in the request object (which is returned by the `#request` method). This schema object is made available to the template context
-* when the incoming request is a `POST`, it will initialize the schema and try to see if it is valid considering the incoming data (using the `#valid?` method). If it's valid, then a new `Article` record will be created using the schema's validated data (`#validated_data`), and the user will be redirect to a home page. Otherwise, the `article_create.html` template will be rendered again with the invalid schema in the associated context
+* when the incoming request is a `POST`, it will initialize the schema and try to see if it is valid considering the incoming data (using the [`#valid?`](pathname:///api/0.4/Marten/Core/Validation.html#valid%3F(context%3ANil|String|Symbol%3Dnil)-instance-method) method). If it's valid, then a new `Article` record will be created using the schema's validated data ([`#validated_data`](pathname:///api/0.4/Marten/Schema.html#validated_data%3AHash(String%2CBool|Float64|Int64|JSON%3A%3AAny|JSON%3A%3ASerializable|Marten%3A%3AHTTP%3A%3AUploadedFile|String|Time|Time%3A%3ASpan|UUID|Nil)-instance-method)), and the user will be redirect to a home page. Otherwise, the `article_create.html` template will be rendered again with the invalid schema in the associated context
It should be noted that templates can easily interact with schema objects in order to introspect them and render a corresponding HTML form. In the above example, the schema could be used as follows to render an equivalent form in the `article_create.html` template:
@@ -191,10 +191,47 @@ class SignUpSchema < Marten::Schema
end
```
-Schema validations are always triggered by the use of the `#valid?` or `#invalid?` methods: these methods return `true` or `false` depending on whether the data is valid or invalid.
+Schema validations are always triggered by the use of the [`#valid?`](pathname:///api/0.4/Marten/Core/Validation.html#valid%3F(context%3ANil|String|Symbol%3Dnil)-instance-method) or [`#invalid?`](pathname:///api/0.4/Marten/Core/Validation.html#invalid%3F(context%3ANil|String|Symbol%3Dnil)-instance-method) methods: these methods return `true` or `false` depending on whether the data is valid or invalid.
Please head over to the [Schema validations](./validations.md) guide in order to learn more about schema validations and how to customize it.
+## Accessing validated data
+
+After performing [schema validations](#validations) (ie. after calling [`#valid?`](pathname:///api/0.4/Marten/Core/Validation.html#valid%3F(context%3ANil|String|Symbol%3Dnil)-instance-method) or [`#invalid?`](pathname:///api/0.4/Marten/Core/Validation.html#invalid%3F(context%3ANil|String|Symbol%3Dnil)-instance-method) on a schema object), accessing the validated data is often necessary. For instance, you may need to persist the validated data as part of a model record. To achieve this, you can make use of the [`#validated_data`](pathname:///api/0.4/Marten/Schema.html#validated_data%3AHash(String%2CBool|Float64|Int64|JSON%3A%3AAny|JSON%3A%3ASerializable|Marten%3A%3AHTTP%3A%3AUploadedFile|String|Time|Time%3A%3ASpan|UUID|Nil)-instance-method) method, which is accessible in all schema instances.
+
+This method provides access to a hash that contains the deserialized and validated field values of the schema. For instance, let's consider the example of the `ArticleSchema` schema [mentioned earlier](#the-schema-class):
+
+```crystal
+schema = ArticleSchema.new(Marten::Schema::DataHash{"title" => "Test article", "content" => "Test content"})
+schema.valid? # => true
+
+schema.validated_data["title"] # => "Test article"
+schema.validated_data["content"] # => "Test content"
+```
+
+It is important to note that accessing values using [`#validated_data`](pathname:///api/0.4/Marten/Schema.html#validated_data%3AHash(String%2CBool|Float64|Int64|JSON%3A%3AAny|JSON%3A%3ASerializable|Marten%3A%3AHTTP%3A%3AUploadedFile|String|Time|Time%3A%3ASpan|UUID|Nil)-instance-method) as shown in the above example is not type-safe. The [`#validated_data`](pathname:///api/0.4/Marten/Schema.html#validated_data%3AHash(String%2CBool|Float64|Int64|JSON%3A%3AAny|JSON%3A%3ASerializable|Marten%3A%3AHTTP%3A%3AUploadedFile|String|Time|Time%3A%3ASpan|UUID|Nil)-instance-method) hash can return any supported schema field values, and as a result, you may need to utilize the [`#as`](https://crystal-lang.org/reference/syntax_and_semantics/as.html) pseudo-method to handle the fetched validated data appropriately, depending on how and where you intend to use it.
+
+To palliate this, Marten automatically defines type-safe methods that you can utilize to access your validated schema field values:
+
+* `#Welcome to the Marten documentation!
+{{ article.title }}
``` +This notation can be used to call object methods but also to perform key lookups for hashes or named tuples. It can also be used to perform index lookups for indexable objects (such as arrays or tuples): + +``` +{{ my_array.0 }} +``` + ### Filters Filters can be applied to [variables](#variables) or [tag](#tags) arguments in order to transform their values. They are applied to these variables or arguments through the use of a pipe (**`|`**) followed by the name of the filter. @@ -181,19 +187,19 @@ Templates can be loaded from specific locations within your codebase and from ap Application templates are always enabled by default (`templates.app_dirs = true`) for new Marten projects. -It is possible to programmatically load a template by name. To do so, you can use the [`#get_template`](pathname:///api/0.1/Marten/Template/Engine.html#get_template(template_name%3AString)%3ATemplate-instance-method) method that is provided by the Marten templates engine: +It is possible to programmatically load a template by name. To do so, you can use the [`#get_template`](pathname:///api/0.4/Marten/Template/Engine.html#get_template(template_name%3AString)%3ATemplate-instance-method) method that is provided by the Marten templates engine: ```crystal Marten.templates.get_template("foo/bar.html") ``` -This will return a compiled [`Template`](pathname:///api/0.1/Marten/Template/Template.html) object that you can then render by using a specific context. +This will return a compiled [`Template`](pathname:///api/0.4/Marten/Template/Template.html) object that you can then render by using a specific context. ## Rendering a template You won't usually need to interact with the "low-level" API of the Marten template engine in order to render templates: most of the time you will render templates as part of [handlers](../handlers-and-http.mdx), which means that you will likely end up using the [`#render`](../handlers-and-http/introduction.md#render) shortcut or [generic handlers](../handlers-and-http/generic-handlers.md) that automatically render templates for you. -That being said, it is also possible to render any [`Template`](pathname:///api/0.1/Marten/Template/Template.html) object that you loaded by leveraging the [`#render`](pathname:///api/0.1/Marten/Template/Template.html#render(context%3AHash|NamedTuple)%3AString-instance-method) method. This method can be used either with a Marten context object, a hash, or a named tuple: +That being said, it is also possible to render any [`Template`](pathname:///api/0.4/Marten/Template/Template.html) object that you loaded by leveraging the [`#render`](pathname:///api/0.4/Marten/Template/Template.html#render(context%3AHash|NamedTuple)%3AString-instance-method) method. This method can be used either with a Marten context object, a hash, or a named tuple: ```crystal template = Marten.templates.get_template("foo/bar.html") @@ -204,10 +210,10 @@ template.render({ foo: "bar" }) ## Using custom objects in contexts -Most objects that are provided by Marten (such as Model records, query sets, schemas, etc) can automatically be used as part of templates. If your project involves other custom classes, and if you would like to interact with such objects in your templates, then you will need to explicitly ensure that they include the [`Marten::Template::Object`](pathname:///api/0.1/Marten/Template/Object.html) module. +Most objects that are provided by Marten (such as Model records, query sets, schemas, etc) can automatically be used as part of templates. If your project involves other custom classes, and if you would like to interact with such objects in your templates, then you will need to explicitly ensure that they include the [`Marten::Template::Object`](pathname:///api/0.4/Marten/Template/Object.html) module. :::note Why? -Crystal being a statically typed language, the Marten engine needs to know which types of objects it is dealing with in advance in order to know (i) what can go into template contexts and (ii) how to "resolve" object attributes when templates are rendered. It is not possible to simply expect any `Object` object, hence why we need to make use of a shared [`Marten::Template::Object`](pathname:///api/0.1/Marten/Template/Object.html) module to account for all the classes whose objects should be usable as part of template contexts. +Crystal being a statically typed language, the Marten engine needs to know which types of objects it is dealing with in advance in order to know (i) what can go into template contexts and (ii) how to "resolve" object attributes when templates are rendered. It is not possible to simply expect any `Object` object, hence why we need to make use of a shared [`Marten::Template::Object`](pathname:///api/0.4/Marten/Template/Object.html) module to account for all the classes whose objects should be usable as part of template contexts. ::: Let's take the example of a `Point` class that provides access to an x-coordinate and a y-coordinate: @@ -234,7 +240,7 @@ If you try to render such a template while passing a `Point` object into the tem Unable to initialize template values from Point objects ``` -To remediate this, you will have to include the [`Marten::Template::Object`](pathname:///api/0.1/Marten/Template/Object.html) module in the `Point` class and define a `#resolve_template_attribute` method as follows: +To remediate this, you will have to include the [`Marten::Template::Object`](pathname:///api/0.4/Marten/Template/Object.html) module in the `Point` class and define a `#resolve_template_attribute` method as follows: ```crystal class Point @@ -257,9 +263,9 @@ class Point end ``` -Each class including the [`Marten::Template::Object`](pathname:///api/0.1/Marten/Template/Object.html) module must also implement a `#resolve_template_attribute` method in order to allow resolutions of object attributes when templates are rendered (for example `{{ point.x }}`). That being said, there are a few shortcuts that can be used in order to avoid writing such methods. +Each class including the [`Marten::Template::Object`](pathname:///api/0.4/Marten/Template/Object.html) module must also implement a `#resolve_template_attribute` method in order to allow resolutions of object attributes when templates are rendered (for example `{{ point.x }}`). That being said, there are a few shortcuts that can be used in order to avoid writing such methods. -The first one is to use the [`#template_attributes`](pathname:///api/0.1/Marten/Template/Object.html#template_attributes(*names)-macro) macro in order to easily define the names of the methods that should be made available to the template runtime. For example, such macro could be used like this with our `Point` class: +The first one is to use the [`#template_attributes`](pathname:///api/0.4/Marten/Template/Object.html#template_attributes(*names)-macro) macro in order to easily define the names of the methods that should be made available to the template runtime. For example, such macro could be used like this with our `Point` class: ```crystal class Point @@ -275,7 +281,7 @@ class Point end ``` -Another possibility is to include the [`Marten::Template::Object::Auto`](pathname:///api/0.1/Marten/Template/Object/Auto.html) module instead of the [`Marten::Template::Object`](pathname:///api/0.1/Marten/Template/Object.html) one in your class. This module will automatically ensure that every "attribute-like" public method that is defined in the including class can also be accessed in templates when performing variable lookups. +Another possibility is to include the [`Marten::Template::Object::Auto`](pathname:///api/0.4/Marten/Template/Object/Auto.html) module instead of the [`Marten::Template::Object`](pathname:///api/0.4/Marten/Template/Object.html) one in your class. This module will automatically ensure that every "attribute-like" public method that is defined in the including class can also be accessed in templates when performing variable lookups. ```crystal class Point @@ -289,13 +295,13 @@ class Point end ``` -Note that **all** "attribute-like" public methods will be made available to the template runtime when using the [`Marten::Template::Object::Auto`](pathname:///api/0.1/Marten/Template/Object/Auto.html) module. This may be a good enough behavior, but if you want to have more control over what can be accessed in templates or not, you will likely end up using [`Marten::Template::Object`](pathname:///api/0.1/Marten/Template/Object.html) and the [`#template_attributes`](pathname:///api/0.1/Marten/Template/Object.html#template_attributes(*names)-macro) macro instead. +Note that **all** "attribute-like" public methods will be made available to the template runtime when using the [`Marten::Template::Object::Auto`](pathname:///api/0.4/Marten/Template/Object/Auto.html) module. This may be a good enough behavior, but if you want to have more control over what can be accessed in templates or not, you will likely end up using [`Marten::Template::Object`](pathname:///api/0.4/Marten/Template/Object.html) and the [`#template_attributes`](pathname:///api/0.4/Marten/Template/Object.html#template_attributes(*names)-macro) macro instead. ## Using context producers Context producers are helpers that ensure that common variables are automatically inserted in the template context whenever a template is rendered. They are applied every time a new template context is generated. -For example, they can be used to insert the current HTTP request object in every template context being rendered in the context of a handler and HTTP request. This makes sense considering that the HTTP request object is a common object that is likely to be used by multiple templates in your project: that way there is no need to explicitly "insert" it in the context every time you render a template. This specific capability is provided by the [`Marten::Template::ContextProducer::Request`](pathname:///api/0.1/Marten/Template/ContextProducer/Request.html) context producer, which inserts a `request` object into every template context. +For example, they can be used to insert the current HTTP request object in every template context being rendered in the context of a handler and HTTP request. This makes sense considering that the HTTP request object is a common object that is likely to be used by multiple templates in your project: that way there is no need to explicitly "insert" it in the context every time you render a template. This specific capability is provided by the [`Marten::Template::ContextProducer::Request`](pathname:///api/0.4/Marten/Template/ContextProducer/Request.html) context producer, which inserts a `request` object into every template context. Template context producers can be configured through the use of the [`templates.context_producers`](../development/reference/settings.md#contextproducers) setting. When generating a new project by using the `marten new` command, the following context producers will be automatically configured: @@ -345,3 +351,9 @@ When rendered with `John` as the content of the `name` variable, the abov Hello, <b>John</b>! Hello, John! ``` + +## Strict variables + +By default, when a template variable is unknown or undefined, Marten treats it as a `nil` value. Consequently, nothing will be displayed for such variables, and they will be evaluated as falsey in if conditions. + +However, it is possible to modify this behavior by enabling the [`templates.strict_variables`](../development/reference/settings.md#strict_variables) setting. When this setting is set to `true`, unknown variables encountered in templates will raise [`Marten::Template::Errors::UnknownVariable`](pathname:///api/0.4/Marten/Template/Errors/UnknownVariable.html) exceptions. diff --git a/docs/versioned_docs/version-0.1/templates/reference/context-producers.md b/docs/versioned_docs/version-0.4/templates/reference/context-producers.md similarity index 87% rename from docs/versioned_docs/version-0.1/templates/reference/context-producers.md rename to docs/versioned_docs/version-0.4/templates/reference/context-producers.md index ef749944a..8e2ef8e09 100644 --- a/docs/versioned_docs/version-0.1/templates/reference/context-producers.md +++ b/docs/versioned_docs/version-0.4/templates/reference/context-producers.md @@ -7,19 +7,19 @@ This page provides a reference for all the available context producers that can ## Debug context producer -**Class:** [`Marten::Template::ContextProducer::Debug`](pathname:///api/0.1/Marten/Template/ContextProducer/Debug.html) +**Class:** [`Marten::Template::ContextProducer::Debug`](pathname:///api/0.4/Marten/Template/ContextProducer/Debug.html) The Debug context producer contributes a `debug` variable to the context: the associated value is `true` or `false` depending on whether [debug mode](../../development/reference/settings.md#debug) is enabled for the project or not. ## Flash context producer -**Class:** [`Marten::Template::ContextProducer::Flash`](pathname:///api/0.1/Marten/Template/ContextProducer/Flash.html) +**Class:** [`Marten::Template::ContextProducer::Flash`](pathname:///api/0.4/Marten/Template/ContextProducer/Flash.html) The Flash context producer contributes a `flash` variable to the context: this variable corresponds to the [flash store](../../handlers-and-http/introduction.md#using-the-flash-store) that is associated with the current HTTP request. If the template context is not initialized with an HTTP request object, then no variables are inserted. ## I18n context producer -**Class:** [`Marten::Template::ContextProducer::I18n`](pathname:///api/0.1/Marten/Template/ContextProducer/I18n.html) +**Class:** [`Marten::Template::ContextProducer::I18n`](pathname:///api/0.4/Marten/Template/ContextProducer/I18n.html) The I18n context producer contributes I18n-related variables to the context: @@ -28,7 +28,7 @@ The I18n context producer contributes I18n-related variables to the context: ## Request context producer -**Class:** [`Marten::Template::ContextProducer::Request`](pathname:///api/0.1/Marten/Template/ContextProducer/Request.html) +**Class:** [`Marten::Template::ContextProducer::Request`](pathname:///api/0.4/Marten/Template/ContextProducer/Request.html) The Request context producer contributes a `request` variable to the context: this variable corresponds to the current HTTP request object. If the template context is not initialized with an HTTP request object, then no variables are inserted. diff --git a/docs/versioned_docs/version-0.4/templates/reference/filters.md b/docs/versioned_docs/version-0.4/templates/reference/filters.md new file mode 100644 index 000000000..d95474751 --- /dev/null +++ b/docs/versioned_docs/version-0.4/templates/reference/filters.md @@ -0,0 +1,134 @@ +--- +title: Template filters +description: Template filters reference. +--- + +This page provides a reference for all the available filters that can be used when defining [templates](../introduction.md). + +## `capitalize` + +The `capitalize` filter allows to modify a string so that the first letter is converted to uppercase and all the subsequent letters are converted to lowercase. + +For example: + +```html +{{ value|capitalize }} +``` + +If `value` is "marten", the output will be "Marten". + +## `default` + +The `default` filter allows to fallback to a specific value if the left side of the filter expression is empty or not truthy. A filter argument is mandatory. It should be noted that empty strings are considered truthy and will be returned by this filter. + +For example: + +```html +{{ value|default:"foobar" }} +``` + +If `value` is `nil` (or `0` or `false`), the output will be "foobar". + +## `downcase` + +The `downcase` filter allows to convert a string so that each of its characters is lowercase. + +For example: + +```html +{{ value|downcase }} +``` + +If `value` is "Hello", then the output will be "hello". + +## `escape` + +The `escape` filter replaces special characters (namely `&`, `<`, `>`, `"` and `'`) in the template variable with their corresponding HTML entities. + +For example: + +```html +{{ value|escape }} +``` + +If `value` is `Let's do it`, then the output will be `<b>Let's do it</b>`. + +## `join` + +The `join` filter converts an array of elements into a string separated by `arg`. + +For example: + +```html +{{ value|join: arg }} +``` + +If `value` is `["Bananas","Apples","Oranges"]` and `arg` is `, `, then the output will be "Bananas, Apples, Oranges". + +## `linebreaks` + +The `linebreaks` filter allows to convert a string replacing all newlines with HTML line breaks (``). + +For example: + +```html +{{ value|linebreaks }} +``` + +If `value` is `Hello\nWorld`, then the output will be `Hello
World`. + +## `safe` + +The `safe` filter allows to mark that a string is safe and that it should not be escaped before being inserted in the final output of a rendered template. Indeed, string values are always automatically HTML-escaped by default in templates. + +For example: + +```html +{{ value|safe }} +``` + +If `value` is `
Hello
`, then the output will be `Hello
` as well. + +## `size` + +The `size` filter allows returning the size of a string or an enumerable object. + +For example: + +```html +{{ value|size }} +``` + +## `split` + +The `split` filter converts a string into an array of elements separated by `arg`. + +For example: + +```html +{{ value|split: arg }} +``` + +If `value` is `Bananas,Apples,Oranges` and `arg` is `,`, then the output will be ["Bananas","Apples","Oranges"]. + +## `time` + +The `time` filter allows outputting the string representation of a time variable. It requires the specification of a filter argument, which is the format string used to format the time (whose available directives are part of [`Time::Format`](https://crystal-lang.org/api/Time/Format.html)). + +```html +{{ value | time: "%Y-%m-%d" }} +``` + +In the above example, the output will be a date string such as `2023-09-25`. + +## `upcase` + +The `upcase` filter allows to convert a string so that each of its characters is uppercase. + +For example: + +```html +{{ value|upcase }} +``` + +If `value` is "Hello", then the output will be "HELLO". diff --git a/docs/versioned_docs/version-0.1/templates/reference/tags.md b/docs/versioned_docs/version-0.4/templates/reference/tags.md similarity index 86% rename from docs/versioned_docs/version-0.1/templates/reference/tags.md rename to docs/versioned_docs/version-0.4/templates/reference/tags.md index 83181cdd3..457be9357 100644 --- a/docs/versioned_docs/version-0.1/templates/reference/tags.md +++ b/docs/versioned_docs/version-0.4/templates/reference/tags.md @@ -5,7 +5,7 @@ description: Template tags reference. ## `asset` -The `asset` template tag allows to generate the URL of a given [asset](../../files/asset-handling). It must take at least one argument (the filepath of the asset). +The `asset` template tag allows to generate the URL of a given [asset](../../assets/introduction.md). It must take at least one argument (the filepath of the asset). For example, the following line is a valid usage of the `asset` tag and will output the path or URL of the `app/app.css` asset: @@ -33,6 +33,26 @@ For example: The `block` template tag allows to define that some specific portions of a template can be overridden by child templates. This tag is only useful when used in conjunction with the [`extend`](#extend) tag. See [Template inheritance](../introduction.md#template-inheritance) to learn more about this capability. +## `cache` + +The `cache` template tag allows to cache the content of a template fragment (enclosed within the `{% cache %}...{% endcache %}` tags) for a specific duration. This caching operation is done by leveraging the configured [cache store](../../caching/introduction.md#configuration-and-cache-stores). + +At least a cache key and and a cache expiry (expressed in seconds) must be specified when using this tag: + +```html +{% cache "mykey" 3600 %} + Cached content! +{% endcache %} +``` + +It should be noted that the `cache` template tag also supports specifying additional "vary on" arguments that allow to invalidate the cache based on the value of other template variables: + +```html +{% cache "mykey" 3600 current_locale user.id %} + Cached content! +{% endcache %} +``` + ## `csrf_token` The `csrf_token` template tag allows to compute and insert the value of the CSRF token into a template. This tag can only be used for templates that are rendered as part of a handler (for example by leveraging [`#render`](../../handlers-and-http/introduction.md#render) or one of the [generic handlers](../../handlers-and-http/generic-handlers.md) involving rendered templates). @@ -83,8 +103,8 @@ Finally, loops give access to a special `loop` variable _inside_ the loop in ord | `loop.index0` | The index of the current iteration (0-indexed) | | `loop.revindex` | The index of the current iteration counting from the end of the loop (1-indexed) | | `loop.revindex0` | The index of the current iteration counting from the end of the loop (0-indexed) | -| `loop.first` | A boolean indicating if this is the first iteration of the loop | -| `loop.last` | A boolean indicating if this is the last iteration of the loop | +| `loop.first?` | A boolean indicating if this is the first iteration of the loop | +| `loop.last?` | A boolean indicating if this is the last iteration of the loop | | `loop.parent` | The parent's `loop` variable (only for nested for loops) | ## `if` @@ -237,3 +257,17 @@ For example: ``` Would output `This should not be {{ processed }}.`. + +## `with` + +The `with` template tag assigns one or more variables inside a block. After the end of the block has been reached the block variables are no longer available. + +For example: + +``` +{% with x = 'Hello World', y = 1 %} + {{ x }} {{ y }}! +{% endwith %} +``` + +Would output `Hello World 1!`. diff --git a/docs/versioned_docs/version-0.1/the-marten-project.mdx b/docs/versioned_docs/version-0.4/the-marten-project.mdx similarity index 79% rename from docs/versioned_docs/version-0.1/the-marten-project.mdx rename to docs/versioned_docs/version-0.4/the-marten-project.mdx index 0b93daa5b..383cf00ee 100644 --- a/docs/versioned_docs/version-0.1/the-marten-project.mdx +++ b/docs/versioned_docs/version-0.4/the-marten-project.mdx @@ -12,6 +12,9 @@ This section provides general information about the Marten project itself and de`) in strings easily + +#### Schemas + +* Schemas can now be initialized from handler routing parameters (which means that they can be initialized from the hashes that are returned by the [`Marten::Handlers::Base#params`](pathname:///api/0.2/Marten/Handlers/Base.html#params%3AHash(String%2CInt16|Int32|Int64|Int8|String|UInt16|UInt32|UInt64|UInt8|UUID)-instance-method) method) + +#### Management commands + +* The [`serve`](../../development/reference/management-commands.md#serve) management command now supports the ability to override the host and port used by the development server + +#### Testing + +* A [testing client](../../development/testing.md#using-the-test-client) was introduced in order to allow developers to easily test handlers (and the various routes of a project) by issuing requests and by introspecting the returned responses. + +## Backward incompatible changes + +### Templates + +* The `loop.first` and `loop.last` for loop variables were respectively renamed `loop.first?` and `loop.last?`. See the [template tag reference](../../templates/reference/tags.md#for) to learn more about the `for` template tag + +### Management commands + +* The [`new`](../../development/reference/management-commands.md#new) management command's optional directory argument was replaced by a dedicated `-d DIR, --dir=DIR` option diff --git a/docs/versioned_docs/version-0.4/the-marten-project/release-notes/0.3.1.md b/docs/versioned_docs/version-0.4/the-marten-project/release-notes/0.3.1.md new file mode 100644 index 000000000..f53946252 --- /dev/null +++ b/docs/versioned_docs/version-0.4/the-marten-project/release-notes/0.3.1.md @@ -0,0 +1,13 @@ +--- +title: Marten 0.3.1 release notes +pagination_prev: null +pagination_next: null +--- + +_July 10, 2023._ + +## Bug fixes + +* Ensure that context objects provided by [generic handlers](../../handlers-and-http/generic-handlers.md) are initialized using [`Marten::Template::Context`](pathname:///api/dev/Marten/Template/Context.html). +* Fix a possible compilation error happening around template variables initialization. +* Ensure that `#