search

rom-rb / rom-rb.org

The official rom-rb website
https://rom-rb.org/
45 stars 108 forks source link

Feedback on ROM - Relations & Structs #314

Closed wmakley closed 4 years ago

wmakley commented 4 years ago

Example defines a Users relation class, but then immediately references the local variable "users" without indicating how to get there:

class Users < ROM::Relation[:sql]
  # ...
end

user = users.by_pk(1).one

I am just trying to require ROM from scratch to learn it.

solnic commented 4 years ago

Thanks for feedback. This is a problem with most of the code examples, showing entire setup in every single example would produce too much noise, that's why it's best to start with intro docs that explain that at run-time you work with relation objects.

Soon we'll have more advanced code examples with tabs, where you'll be able to click on "Full example" (or something like this) where a complete, executable example will be shown.

I'm going to close this issue because this is a known problem and I'll be addressing it for sure.

wmakley commented 4 years ago

Thanks for listening. I've been interested in trying ROM for a while, but I'm having a lot of trouble because it feels like I have to piece it together. The full picture isn't on any page of the guide. I've read the conceptual overview, but it's very high level and it left me with lots of dots I couldn't connect on my own. (It seems something I might find more meaningful after I've used ROM for a while.)

  1. What is the difference between config.relation and class MyRelation <ROM::Relation[:sql] ?
  2. The first pages say to define everything inside the ROM.container block which returns a "container" object, but subsequent examples show defining global classes outside of this block, such as repositories. What is the difference? How does the repository know about my rom container if I don't pass it in?
  3. Now that I have a "rom" container, what can I do with it? None of the example code uses it.
solnic commented 4 years ago
  1. What is the difference between config.relation and class MyRelation <ROM::Relation[:sql] ?

The former uses configuration DSL, which is suitable for scripts but not for applications. The latter, so defining classes explicitly, is a typical way of using ROM with applications.

  1. The first pages say to define everything inside the ROM.container block which returns a "container" object, but subsequent examples show defining global classes outside of this block, such as repositories.

Yeah this is super confusing. We should explain configuration with explicit classes as THE way of using ROM. Using configuration DSL isn't really common anymore (it used to be in the early days).

What is the difference?

The container block is a shortcut if you want to bootstrap rom runtime quickly in a script. Again, in applications you want to create rom configuration object, set up db connections and register components (or more commony use auto-registration with a directory that contains component files).

How does the repository know about my rom container if I don't pass it in?

Repositories receive rom containers in their constructors. It's up to you to handle that. ROM is often used in application based on dry-system, which supports constructor injection OOTB so things Just Work™.

Now that I have a "rom" container, what can I do with it? None of the example code uses it.

It gives you access to all initialized components. In an application you use it to access relations or to initialize repositories with it, most commonly. In some special cases you may access mappers and/or commands directly too.

I recommend joining our forum and/or chat and ask questions there.