0.2.0

Marten 0.2.0 adds key features to the framework such as authentication, email sending, raw SQL query capabilities, ...

Requirements and compatibility

Crystal 1.6 and 1.7.

New features

Authentication

The framework now provides the ability to generate projects with a built-in authentication system that handles basic user management needs: signing in/out users, resetting passwords, etc. This can be achieved through the use of the --with-auth option of the new management command:

marten new project myblog --with-auth

The --with-auth option ensures that an auth application is created for the generated project under the src/auth folder. This application is part of the created project and provides the necessary models, handlers, schemas, emails, and templates allowing authenticating users with email addresses and passwords, while also supporting standard password reset flows. All these abstractions provide a "default" authentication implementation that can be then updated on a per-project basis to better accommodate authentication-related requirements.

Email sending

Marten now lets you define emails that you can fully customize (properties, header values, etc) and whose bodies (HTML and/or text) are rendered by leveraging templates. For example, here is how to define a simple email and how to deliver it:

class WelcomeEmail < Marten::Email
  to @user.email
  subject "Hello!"
  template_name "emails/welcome_email.html"

  def initialize(@user : User)
  end
end

email = WelcomeEmail.new(user)
email.deliver

Emails are delivered by leveraging an emailing backend mechanism. Emailing backends implement how emails are actually sent and delivered. Presently, Marten supports one built-in development emailing backend, and a set of other third-party backends that you can install depending on your email sending requirements.

Please refer to the Emailing section to learn more about this new feature.

Raw SQL capabilities

Query sets now provide the ability to perform raw queries that are mapped to actual model instances. This is interesting if the capabilities provided by query sets are not sufficient for the task at hand and you need to write custom SQL queries.

For example:

Article.raw("SELECT * FROM articles WHERE title = ?", "Hello World!").each do |article|
  # Do something with `article` record
end

Please refer to Raw SQL to learn more about this capability.

Email field for models and schemas

It is now possible to define email fields in models and schemas. These allow you to easily persist valid email addresses in your models but also to expect valid email addresses in data validated through the use of schemas.

For example:

class User < Marten::Model
  field :id, :big_int, primary_key: true, auto: true
  field :email, :email, unique: true
end

Transaction callbacks

Models now support the definition of transaction callbacks by using the #after_commit and #after_rollback macros.

For example:

class User < Marten::Model
  field :id, :big_int, primary_key: true, auto: true
  field :username, :string, max_size: 64, unique: true

  after_commit :do_something, on: :update

  private def do_something
    # Do something!
  end
end

Please refer to Callbacks to learn more about this capability.

Minor features

Models and databases

• Support for DB connection pool parameters was added. See the database settings reference for more details about the supported parameters
• Model fields now contribute #<fieldName>? methods to model classes in order to easily identify if a field has a value or not. Note that this capability is also enabled for the relationship methods provided by the many_to_one and one_to_one fields
• It is now possible to leverage a #with_timestamp_fields macro to automatically create created_at / updated_at timestamp fields in models. The created_at field is populated with the current time when new records are created while the updated_at field is refreshed with the current time whenever records are updated. See Timestamps to learn more about this capability
• It is now possible to easily retrieve specific column values without loading entire record objects by leveraging the #pluck and #pick query set methods

Handlers and HTTP

• string can now be used as an alias for str when defining routing parameters

Templates

• Support for index lookups was added. This means that it is now possible to retrieve specific index values from indexable objects in templates using the {{ var.<index> }} syntax (for example: {{ var.0 }})
• A linebreaks template filter was introduced to allow replacing all newlines with HTML line breaks (<br />) 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 method)

Management commands

• The serve management command now supports the ability to override the host and port used by the development server

Testing

• A testing 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 to learn more about the for template tag

Management commands

• The new management command's optional directory argument was replaced by a dedicated -d DIR, --dir=DIR option

0.1.5

Marten 0.1.5 fixes a couple of bugs.

Bug fixes

• Fix a bug where some types returned by built-in fields weren't allowed as template values
• Fix a bug where it was not possible to resolve UUID routing parameters from valid UUID strings
• Ensure abstract model classes can be created without primary key fields
• Ensure subclasses of Marten::Conf::Setting no longer have to define a mandatory #initialize method if they don't need to

0.1.4

Marten 0.1.4 fixes a couple of bugs.

Bug fixes

• Fix non-working #pk method generation for models with a one-to-one primary key field
• Fix a possible NilAssertionError when running a migration involving a column change
• Fix a possible layout issue in the server error debug page

0.1.3

Marten 0.1.3 fixes a couple of bugs.

Bug fixes

• Ensure that before/after deletion callbacks are executed in the same transaction as the deletion runner
• Add missing .gitignore file to projects generated through the use of the new management command
• Fix incorrect host used for development environments when generating new projects through the use of the new management command: now, projects automatically use the 127.0.0.1 local host in development
• Ensure that the flash context producer takes into account requests that don't have an associated flash store in order to avoid unexpected NilAssertionErrorexceptions

0.1.2

Read the release notes

0.1.1

Read the release notes

0.1.0

Read the release notes