README.md in trailblazer-loader-0.0.3 vs README.md in trailblazer-loader-0.0.4
- old
+ new
@@ -1,89 +1,239 @@
# Trailblazer::Loader
-## Experimental!
+_Generic loader for Trailblazer projects._
-Note that this is not the finalized version of `trailblazer-loader`. We still need more input from you.
+ Reportedly works with Rails, Grape, Lotus, and Roda, and many more, for sure.
-Expect many minor version bumps.
+**Rails users**: This gem is bundled with [trailblazer-rails](https://github.com/trailblazer/trailblazer-rails).
-## Loading order
+## Overview
-Per concept. Lexically sorted. Then, sorted by depths, as follows.
+While Trailblazer enforces a new file structure where you organize by concept, and not by technology, the naming and the structuring within each concept allows different styles.
+Trailblazer-loader supports the following directory layouts concurrently.
+
+## Compound-Singular
+
+Per concept, you have one file per abstraction layer (called a _compound_ file). All is singular and reflects the namespace (except for operations which sit in the concept's namespace).
+
```
-app/concepts/blog/operation.rb
-app/concepts/comment/operation.rb
-app/concepts/post/operation.rb
-app/concepts/api/v1/comment/operation.rb
-app/concepts/api/v1/post/operation.rb
+app
+├── concepts
+│ ├── comment
+│ │ ├── callback.rb
+│ │ ├── cell.rb
+│ │ ├── contract.rb
+│ │ ├── operation.rb
+│ │ ├── policy.rb
+│ │ └── views
+│ │ ├── grid.haml
+│ │ └── show.haml
```
-1. Model. The model does not have dependencies to other layers. If it does, you're doing it wrong.
-2. Policy
-3. Representer
-4. Form
-5. Callbacks, etc.
-6. Operation. As an orchestrating object, this needs to be loaded last. It is very common for operations to reference form classes, etc. on the class level.
- first create.rb
- then operations.rb {configurable, could also be crud.rb}
+You may nest concepts in concepts.
+```
+app
+├── concepts
+│ ├── comment
+│ │ ├── contract.rb
+│ │ ├── operation.rb
+│ │ ├── admin
+│ │ ├── contract.rb
+│ │ └── operation.rb
+```
+
+Note: This is the structuring used in the [Trailblazer book](http://trailblazer.to/books/trailblazer.html).
+
+
+## Explicit-Singular
+
+Per concept, you have one directory per abstraction layer and one file per class. All is singular and reflects the namespace (except for operations which sit in the concept's namespace).
+
+```
+app
+├── concepts
+│ ├── comment
+│ │ ├── contract
+│ │ │ ├── create.rb
+│ │ │ └── update.rb
+│ │ ├── cell
+│ │ │ └── form.rb
+│ │ ├── operation
+│ │ │ ├── create.rb
+│ │ │ └── update.rb
+│ │ └── views
+│ │ ├── grid.haml
+│ │ └── show.haml
+```
+
+You may nest concepts in concepts.
+
+```
+app
+├── concepts
+│ ├── comment
+│ │ ├── contract
+│ │ │ ├── create.rb
+│ │ │ └── update.rb
+│ │ ├── operation
+│ │ │ ├── create.rb
+│ │ │ └── update.rb
+│ │ ├── admin
+│ │ │ └── contract
+│ │ │ ├── create.rb
+│ │ │ └── update.rb
+```
+
+## Explicit-Plural
+
+Per concept, you have one pluralized directory per abstraction layer and one file per class.
+
+```
+app
+├── concepts
+│ ├── comment
+│ │ ├── contracts
+│ │ │ ├── create.rb
+│ │ │ └── update.rb
+│ │ ├── cells
+│ │ │ └── form.rb
+│ │ ├── operations
+│ │ │ ├── create.rb
+│ │ │ └── update.rb
+│ │ └── views
+│ │ ├── grid.haml
+│ │ └── show.haml
+```
+
+And, yes, you may nest concepts in concepts.
+
+```
+app
+├── concepts
+│ ├── comment
+│ │ ├── contracts
+│ │ │ ├── create.rb
+│ │ │ └── update.rb
+│ │ ├── operation
+│ │ │ ├── create.rb
+│ │ │ └── update.rb
+│ │ ├── admin
+│ │ │ └── contracts
+│ │ │ ├── create.rb
+│ │ │ └── update.rb
+```
+
+
+## Loading order
+
+The loading order is identical for all styles.
+
+1. The loader finds all concept directories.
+2. Concept directories are sorted by nesting level, deeper nestings are loaded later as they might reference concepts they're nested in. For example, `concepts/comment/admin` might reuse existing code from `concepts/comment`.
+3. Per concept, files are lexically sorted, e.g. `create.rb` will be loaded *before* `update.rb` as we mostly do `Update < Create`.
+4. Per concept, operation files will be loaded after all other layer files have been required. This is because abstraction files like representers or contracts should not reference their operation. The operation, howver, as an orchestrating asset needs to refer to various abstraction objects.
+
+Here's a sample of a explicit-singular session.
+
+```ruby
+[
+ "app/concepts/navigation/cell.rb",
+ "app/concepts/session/impersonate.rb",
+ "app/concepts/session/operation.rb",
+ "app/concepts/user/operation.rb",
+ "app/concepts/comment/cell/cell.rb",
+ "app/concepts/comment/cell/grid.rb",
+ "app/concepts/comment/operation/create.rb",
+ "app/concepts/api/v1.rb",
+ "app/concepts/thing/callback/default.rb",
+ "app/concepts/thing/callback/upload.rb",
+ "app/concepts/thing/cell.rb",
+ "app/concepts/thing/cell/decorator.rb",
+ "app/concepts/thing/cell/form.rb",
+ "app/concepts/thing/cell/grid.rb",
+ "app/concepts/thing/contract/create.rb",
+ "app/concepts/thing/contract/update.rb",
+ "app/concepts/thing/policy.rb",
+ "app/concepts/thing/signed_in.rb",
+ "app/concepts/thing/operation/create.rb",
+ "app/concepts/thing/operation/delete.rb",
+ "app/concepts/thing/operation/show.rb",
+ "app/concepts/thing/operation/update.rb",
+ "app/concepts/api/v1/comment/representer/show.rb",
+ "app/concepts/api/v1/comment/operation/create.rb",
+ "app/concepts/api/v1/comment/operation/show.rb",
+ "app/concepts/api/v1/thing/representer/create.rb",
+ "app/concepts/api/v1/thing/representer/index.rb",
+ "app/concepts/api/v1/thing/representer/show.rb",
+ "app/concepts/api/v1/thing/operation/create.rb",
+ "app/concepts/api/v1/thing/operation/index.rb",
+ "app/concepts/api/v1/thing/operation/update.rb"
+]
+```
+
## Installation
Add this line to your application's Gemfile:
```ruby
gem 'trailblazer-loader'
```
+You do not need this step should you use one of the following binding gems.
+
+* [trailblazer-rails](https://github.com/trailblazer/trailblazer-rails)
+* [trailblazer-grape](https://github.com/trailblazer/trailblazer-grape)
+* [trailblazer-roda](https://github.com/trailblazer/trailblazer-roda)
+* [trailblazer-lotus](https://github.com/trailblazer/trailblazer-lotus)
+
## API
```ruby
-Trailblazer::Loader.new.(Rails.app.root) { |file| require_dependency(file) }
+Trailblazer::Loader.new.() { |file| require_dependency(File.join(Rails.app.root, file)) }
```
+`:concepts_root`
-## File Layout
+## Mixing
+Note that you're free to mix these styles the way it feels right for your project.
+
+For example, you can have compound files and explicit layout in one concept.
+
```
app
├── concepts
-│ ├── comment
-│ │ ├── cell.rb [optional]
-│ │ ├── contract.rb [optional]
-│ │ ├── operation.rb
-│ │ ├── policy.rb [optional]
-│ │ ├── representer.rb [optional]
-│ │ ├── views
-│ │ │ ├── show.haml
-│ │ │ ├── list.haml
-│ │ │ ├── comment.css.sass
+│ ├── comment
+│ │ ├── contract.rb - compound vs.
+│ │ ├── operation - explicit directory
+│ │ │ ├── create.rb
+│ │ │ └── update.rb
```
-### Alternative "explicit" layout
+## Namespacing Operations
-This works for cell, contract, operation, policy, representer and twin.
+Normally, operations in Trailblazer use the concept's namespace, e.g. `Comment::Create`, even though they can sit in an explicit file.
```
app
├── concepts
-│ ├── comment
-│ │ ├── operation
-│ │ │ ├── create.rb
-│ │ │ ├── update.rb
+│ ├── comment
+│ │ ├── operation - explicit directory
+│ │ │ ├── create.rb - contains Comment::Create
+│ │ │ └── update.rb
```
-### Nested
+You are free to namespace your operations, if you like that better.
+```ruby
+module Comment::Operation
+ class Create < Trailblazer::Operation
```
-app
-├── concepts
-│ ├── comment
-│ │ ├── cell
-│ │ │ ├── single
-│ │ │ │ ├── homepage.rb
-│ │ │ │ ├── search.rb
-│ │ │ │ ├── views
-│ │ │ │ │ ├── homepage.haml
-│ │ │ │ │ ├── search.haml
-│ │ │ ├── collection
-```
\ No newline at end of file
+
+## Debugging
+
+## Customizing
+
+Trailblazer-loader allows you to inject your own sorting and filtering logic, should you refuse to go mainstream.
+