Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Update docs (fixes #212) #213

Merged
merged 5 commits into from Dec 24, 2019
Merged

Update docs (fixes #212) #213

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
a17f5b9
Improve documentation
lucascaton Dec 21, 2019
68305d0
Add instructions on updating 'app/views/index.erb' to the docs
lucascaton Dec 21, 2019
bd5b350
Add missing instruction to the docs
lucascaton Dec 21, 2019
75c8995
Add missing code to docs
lucascaton Dec 21, 2019
5bf07c8
Remove unnecessary 'id/' from author page path
lucascaton Dec 21, 2019
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Jump to
Jump to file
Failed to load files.
Diff view
Diff view
57 changes: 39 additions & 18 deletions docs/docs/building-a-web-application.md
View file
Open in desktop
Expand Up @@ -30,6 +30,7 @@ require 'sinatra/reloader' # for hot reloading changes we make
require_relative '../blog'

class Web < Sinatra::Base
enable :sessions
Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This is necessary to get Sinatra::Flash working.

register Sinatra::Flash

configure :development do
Expand All @@ -48,10 +49,11 @@ In `./config.ru`

```ruby
require './app/web'

run Web
```

For now this is enough. On the command line execute `rackup -p 4567` and open [localhost:4567](http://localhost:4567). If you see `"Welcome to Sequent!"` then we are good to go!
For now this is enough. On the command line execute `bundle exec rackup -p 4567` and open [localhost:4567](http://localhost:4567). If you see `"Welcome to Sequent!"` then we are good to go!

For this guide we want to be able to signup as Author. In a later guide we will go full CRUD on the application
and actually create Posts with Authors.
Expand All @@ -67,7 +69,7 @@ First we change the `get '/'` to serve us an `erb` with a html form that allows

The erb `in app/views/index.erb`:

```ruby
```erb
<html>
<body>
<pre><%= flash.inspect %></pre>
Expand Down Expand Up @@ -134,6 +136,7 @@ In `app/database.rb`:
require 'yaml'
require 'erb'
require 'active_record'
require 'sequent'

class Database
class << self
Expand Down Expand Up @@ -216,7 +219,7 @@ readability.

Next step is to display the existing authors. In Sequent this is done in 4 steps:

**1. Create the `AuthorRecord`.**
**1. Create the `AuthorRecord`**

Since we are using `ActiveRecord` we need to create the `AuthorRecord`

Expand All @@ -226,7 +229,7 @@ class AuthorRecord < Sequent::ApplicationRecord
end
```

**2. Create the corresponding sql file**
**2. Create the corresponding SQL file**

`db/tables/author_records.sql`
```sql
Expand Down Expand Up @@ -286,6 +289,7 @@ require_relative 'app/projectors/author_projector'
```

**4. Update Sequent configuration**

Then we can add this projector to our Sequent config `config/initializers/sequent.rb`

```ruby
Expand All @@ -306,14 +310,17 @@ Sequent.configure do |config|
end
```

**5. Create and run the migration**
**5. Update and run the migration**

In `db/migrations.rb`:

In `db/migrations.rb`
```ruby
VIEW_SCHEMA_VERSION = 2 # <= update this to version 2

class Migrations < Sequent::Migrations::Projectors
...
def self.version
VIEW_SCHEMA_VERSION
end

def self.versions
{
Expand All @@ -328,10 +335,13 @@ class Migrations < Sequent::Migrations::Projectors
end
```

Make sure you have updated your `VIEW_SCHEMA_VERSION` constant.
{: .notice}

Stop your app and now run this migration and see what happens:

```bash
(master)$ bundle exec rake sequent:migrate:online && bundle exec rake sequent:migrate:offline
$ bundle exec rake sequent:migrate:online && bundle exec rake sequent:migrate:offline
INFO -- : group_exponent: 3
INFO -- : Start replaying events
INFO -- : Number of groups 4096
Expand All @@ -344,7 +354,7 @@ INFO -- : Migrated to version 2
Let's inspect the database again:

```bash
(master)$ psql blog_development
$ psql blog_development
blog_development=# select * from view_schema.author_records;
id | aggregate_id | name | email
----+--------------------------------------+------+----------------
Expand All @@ -353,18 +363,18 @@ blog_development=# select * from view_schema.author_records;

We have authors in the database! This means we can also display them in our app:

Change the `app/web.rb`
Change the `app/web.rb`:

```ruby
get '/authors/id/:aggregate_id' do
get '/authors/:aggregate_id' do
Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I removed this from the author path to keep it consistent with Rails routes pattern.

Although this isn't Rails, I think it's nice to use something most of Ruby developers are used to it.

Hope it makes sense :)

@author = AuthorRecord.find_by(aggregate_id: params[:aggregate_id])
erb :'authors/show'
end
```

Add the `app/views/authors/show.erb`
Add the `app/views/authors/show.erb`:

```ruby
```erb
<html>
<body>
<h1>Author <%= h @author.name %> </h1>
Expand All @@ -378,7 +388,7 @@ Add the `app/views/authors/show.erb`

To create a navigatable web app we also add the following code:

In `app/web.rb`
In `app/web.rb`:

```ruby
class Web < Sinatra::Base
Expand All @@ -393,9 +403,20 @@ class Web < Sinatra::Base
end
```

In `app/views/authors/index.erb`
In `app/views/index.erb`:

```ruby
```html
<body>
<nav style="border-bottom: 1px solid #333; padding-bottom: 1rem;">
<a href="/authors">All authors</a>
</nav>

...
```

In `app/views/authors/index.erb`:

```erb
<html>
<body>
<p>
Expand All @@ -413,7 +434,7 @@ In `app/views/authors/index.erb`
<% @authors.each do |author| %>
<tr>
<td>
<a href="/authors/id/<%= author.aggregate_id %>"><%= h author.aggregate_id %></a>
<a href="/authors/<%= author.aggregate_id %>"><%= h author.aggregate_id %></a>
</td>
<td><%= h author.name %></td>
<td><%= h author.email %></td>
Expand All @@ -431,6 +452,6 @@ So that's it for this guide. In this guide we learned:
2. Add a Projector and Migration
3. Use the Projector to display data in the web application

The full sourcecode of this guide is available here: [sequent-examples](https://github.com/zilverline/sequent-examples/tree/master/building-a-web-application)
The full sourcecode of this guide is available here: [sequent-examples](https://github.com/zilverline/sequent-examples/tree/master/building-a-web-application).

We will continue with this app in the [Finishing the web application](/docs/finishing-the-web-application.html) guide.
6 changes: 4 additions & 2 deletions docs/docs/getting-started.md
View file
Open in desktop
Expand Up @@ -53,7 +53,7 @@ $ pg_config --version
PostgreSQL 11.2
```

Sequent works with PostgreSQL version 9.4 or later, but we recommend you install the lastest version. For installation instructions refer to your OS or see [postgresql.org](https://www.postgresql.org)
Sequent works with PostgreSQL version 9.4 or later, but we recommend you install the lastest version. For installation instructions refer to your OS or see [postgresql.org](https://www.postgresql.org).

#### Sequent

Expand Down Expand Up @@ -114,7 +114,9 @@ bundle exec rake sequent:migrate:online
bundle exec rake sequent:migrate:offline
```

If your database already exists and you just need to create the event_store schema and the view_schema then do:
If your database already exists and you just need to create the `event_store` schema
and the `view_schema` then do:

```bash
bundle exec rake sequent:db:create_event_store
bundle exec rake sequent:db:create_view_schema
Expand Down
6 changes: 4 additions & 2 deletions docs/docs/modelling-the-domain.md
View file
Open in desktop
Expand Up @@ -34,7 +34,7 @@ post.rb # Requires the entire aggregate root

### Adding a command

Changes to state start by executing a command. Commands are quite simple classes containing some attributes and attribute validations. Looking at `lib/post/commands.rb` we have one command:
Changes to state start by executing a command. Commands are quite simple classes containing some attributes and attribute validations. Looking at `lib/post/commands.rb`, we have one command:

```ruby
class AddPost < Sequent::Command
Expand Down Expand Up @@ -233,7 +233,7 @@ require_relative 'lib/author'
require_relative 'lib/usernames'
```

The `author/author_command_handler.rb`
The `author/author_command_handler.rb`:

```ruby
class AuthorCommandHandler < Sequent::CommandHandler
Expand All @@ -250,6 +250,8 @@ class AddAuthor < Sequent::Command
end
```

And the `AuthorCommandHandler` to `config/initializers/sequent.rb`.
Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This is a mandatory step and was missing, as reported via #212.


Now when we run the tests all are marked as `Pending: Not yet implemented`. Before we can go any further we need to think about what kind of Events we are interested in. What do we want to know in this case? When registering our very first `Author` it will not only create the Author, but also create our `Usernames` Aggregate to ensure uniqueness of the usernames. So the test is something like:

```
Expand Down
4 changes: 3 additions & 1 deletion docs/index.md
View file
Open in desktop
Expand Up @@ -32,11 +32,13 @@ application created in the modelling the domain guide and add a web interface fo
web framework.

### 4. Finishing the webapplication

In the [finishing the web-application guide](/docs/finishing-the-web-application.html) we continue with
the blog application and add form validation and let the Author's add Posts.

### 5. Rails & Sequent
The [Rails & Sequent](/docs/rails-sequent.html) guide shows how to use Sequent in a [Rails application](https://rubyonrails.org/)

The [Rails & Sequent](/docs/rails-sequent.html) guide shows how to use Sequent in a [Rails application](https://rubyonrails.org/).

## Reference Guide

Expand Down