Generic handlers

This page provides a reference for all the available generic handlers.

Creating a record

Class: Marten::Handlers::RecordCreate

Handler allowing to create a new model record by processing a schema.

This handler can be used to process a form, validate its data through the use of a schema, and create a record by using the validated data. It is expected that the handler will be accessed through a GET request first: when this happens the configured template is rendered and displayed, and the configured schema which is initialized can be accessed from the template context in order to render a form for example. When the form is submitted via a POST request, the configured schema is validated using the form data. If the data is valid, the corresponding model record is created and the handler returns an HTTP redirect to a configured success URL.

class MyFormHandler < Marten::Handlers::RecordCreate
  model MyModel
  schema MyFormSchema
  template_name "my_form.html"
  success_route_name "my_form_success"
end

It should be noted that the redirect response issued will be a 302 (found).

The model class used to create the new record can be configured through the use of the #model macro. The schema used to perform the validation can be defined through the use of the #schema macro. Alternatively, the #schema_class method can also be overridden to dynamically define the schema class as part of the request handler handling.

The #template_name class method allows defining the name of the template to use to render the schema while the #success_route_name method can be used to specify the name of a route to redirect to once the schema has been validated. Alternatively, the #sucess_url class method can be used to provide a raw URL to redirect to. The same method can also be overridden at the instance level to rely on a custom logic to generate the success URL to redirect to.

tip

Handlers making use of the Marten::Handlers::RecordCreate generic handler can leverage additional types of callbacks. Please head over to Schema handler callbacks to learn more about those.

Deleting a record

Class: Marten::Handlers::RecordDelete

Handler allowing to delete a specific model record.

This handler can be used to delete an existing model record by issuing a POST request. Optionally the handler can be accessed with a GET request and a template can be displayed in this case; this allows to display a confirmation page to users before deleting the record:

class ArticleDeleteHandler < Marten::Handlers::RecordDelete
  model MyModel
  template_name "article_delete.html"
  success_route_name "article_delete_success"
end

It should be noted that the redirect response issued will be a 302 (found).

The #template_name class method allows defining the name of the template to use to render a deletion confirmation page while the #success_route_name method can be used to specify the name of a route to redirect to once the deletion is complete. Alternatively, the #sucess_url class method can be used to provide a raw URL to redirect to. The same method can also be overridden at the instance level to rely on a custom logic to generate the success URL to redirect to.

Displaying a record

Class: Marten::Handlers::RecordDetail

Handler allowing to display a specific model record.

This handler can be used to retrieve a model record, and to display it as part of a rendered template.

class ArticleDetailHandler < Marten::Handlers::RecordDetail
  model Article
  template_name "articles/detail.html"
end

The model class used to retrieve the record can be configured through the use of the #model macro. By default, a Marten::Handlers::RecordDetail subclass will always retrieve model records by looking for a pk route parameter: this parameter is assumed to contain the value of the primary key field associated with the record that should be rendered. If you need to use a different route parameter name, you can also specify a different one through the use of the #lookup_param class method. Finally, the model field that is used to get the model record (defaulting to pk) can also be configured by leveraging the #lookup_param class method.

The #template_name class method allows defining the name of the template to use to render the considered model record. By default, the model record is associated with a record key in the template context, but this can also be configured by using the record_context_name class method.

Listing records

Class: Marten::Handlers::RecordList

Handler allowing to list model records.

This base handler can be used to easily expose a list of model records:

class MyHandler < Marten::Handlers::RecordList
  template_name "my_template"
  model Post
end

The model class used to retrieve the records can be configured through the use of the #model macro. The order of these model records can also be specified by leveraging the #ordering class method.

The #template_name class method allows defining the name of the template to use to render the list of model records. By default, the list of model records is associated with a records key in the template context, but this can also be configured by using the list_context_name class method.

Optionally, it is possible to configure that records should be paginated by specifying a page size through the use of the page_size class method:

class MyHandler < Marten::Handlers::RecordList
  template_name "my_template"
  model Post
  page_size 12
end

When records are paginated, a Marten::DB::Query::Page object will be exposed in the template context (instead of the raw query set). It should be noted that the page number that should be displayed is determined by looking for a page GET parameter by default; this parameter name can be configured as well by calling the page_number_param class method.

How to customize the query set?

By default, handlers that inherit from Marten::Handlers::RecordList will use a query set targetting all the records of the specified model. It should be noted that you can customize this behavior easily by leveraging the #queryset macro instead of the #model macro. For example:

class MyHandler < Marten::Handlers::RecordList
  template_name "my_template"
  queryset Article.filter(user: request.user)
end

Alternatively, it is also possible to override the #queryset method and apply additional filters to the default query set:

class MyHandler < Marten::Handlers::RecordList
  template_name "my_template"
  model Article

  def queryset
    super.filter(user: request.user)
  end
end

Updating a record

Class: Marten::Handlers::RecordUpdate

Handler allowing to update a model record by processing a schema.

This handler can be used to process a form, validate its data through the use of a schema, and update an existing record by using the validated data. It is expected that the handler will be accessed through a GET request first: when this happens the configured template is rendered and displayed, and the configured schema which is initialized can be accessed from the template context to render a form for example. When the form is submitted via a POST request, the configured schema is validated using the form data. If the data is valid, the model record that was retrieved is updated and the handler returns an HTTP redirect to a configured success URL.

class MyFormHandler < Marten::Handlers::RecordUpdate
  model MyModel
  schema MyFormSchema
  template_name "my_form.html"
  success_route_name "my_form_success"
end

It should be noted that the redirect response issued will be a 302 (found).

The model class used to update the new record can be configured through the use of the #model macro. By default, the record to update is retrieved by expecting a pk route parameter: this parameter is assumed to contain the value of the primary key field associated with the record that should be updated. If you need to use a different route parameter name, you can also specify a different one through the use of the #lookup_param class method. Finally, the model field that is used to get the model record (defaulting to pk) can also be configured by leveraging the #lookup_param class method.

The schema used to perform the validation can be defined through the use of the #schema macro. Alternatively, the #schema_class method can also be overridden to dynamically define the schema class as part of the request handler handling.

The #template_name class method allows defining the name of the template to use to render the schema while the #success_route_name method can be used to specify the name of a route to redirect to once the schema has been validated. Alternatively, the #sucess_url class method can be used to provide a raw URL to redirect to. The same method can also be overridden at the instance level to rely on a custom logic to generate the success URL to redirect to.

tip

Handlers making use of the Marten::Handlers::RecordUpdate generic handler can leverage additional types of callbacks. Please head over to Schema handler callbacks to learn more about those.

Performing a redirect

Class: Marten::Handlers::Redirect

Handler allowing to conveniently return redirect responses.

This handler can be used to generate a redirect response (temporary or permanent) to another location. To configure such a location, you can either leverage the #route_name class method (which expects a valid route name) or the #url class method. If you need to implement a custom redirection URL logic, you can also override the #redirect_url method.

class TestRedirectHandler < Marten::Handlers::Redirect
  route_name "articles:list"
end

By default, the redirect returned by this handler is a temporary one. In order to generate a permanent redirect response instead, it is possible to leverage the #permanent class method.

It should also be noted that by default, incoming query string parameters are not forwarded to the redirection URL. If you wish to ensure that these parameters are forwarded, you can make use of the forward_query_string class method.

Processing a schema

Class: Marten::Handlers::Schema

Handler allowing to process a form through the use of a schema.

This handler can be used to process a form and validate its data through the use of a schema. It is expected that the handler will be accessed through a GET request first: when this happens the configured template is rendered and displayed, and the configured schema which is initialized can be accessed from the template context to render a form for example. When the form is submitted via a POST request, the configured schema is validated using the form data. If the data is valid, the handler returns an HTTP redirect to a configured success URL.

class MyFormHandler < Marten::Handlers::Schema
  schema MyFormSchema
  template_name "my_form.html"
  success_route_name "my_form_success"
end

It should be noted that the redirect response issued will be a 302 (found).

The schema used to perform the validation can be defined through the use of the #schema macro. Alternatively, the #schema_class method can also be overridden to dynamically define the schema class as part of the request handler handling.

The #template_name class method allows defining the name of the template to use to render the schema while the #success_route_name method can be used to specify the name of a route to redirect to once the schema has been validated. Alternatively, the #sucess_url class method can be used to provide a raw URL to redirect to. The same method can also be overridden at the instance level to rely on a custom logic to generate the success URL to redirect to.

tip

Handlers making use of the Marten::Handlers::Schema generic handler can leverage additional types of callbacks. Please head over to Schema handler callbacks to learn more about those.

Rendering a template

Class: Marten::Handlers::Template

Handler allowing to respond to GET request with the content of a rendered HTML template.

This handler can be used to render a specific template and returns the resulting content in the response. The template being rendered can be specified by leveraging the #template_name class method.

class HomeHandler < Marten::Handlers::Template
  template_name "app/home.html"
end

If you need to, it is possible to customize the context that is used to render the configured template. To do so, you can define a before_render callback and add new variables to the global template context (which functions similarly to a hash object):

class HomeHandler < Marten::Handlers::Template
  template_name "app/home.html"

  before_render add_recent_articles_to_context

  private def add_recent_articles_to_context : Nil
    context[:recent_articles] = Article.all.order("-published_at")[:5]
  end
end

Variables that are added to the global template context will automatically be available to the configured template's runtime.