compony 0.7.0 → 0.7.1

data/doc/guide/basic_component.md

@@ -0,0 +1,259 @@
+[Back to the guide](/README.md#guide)
+
+# What is a component?
+
+Compony components are nestable elements that are capable of replacing Rails' routes, views and controllers. They structure code for data manipulation, authentication and rendering into a single class that can easily be subclassed. This is achieved with Compony's DSL that provides a readable and overridable way to store your logic.
+
+Just like Rails, Compony is opinionated and you are advised to structure your code according to the examples and explanations. This makes it easier for others to dive into existing code.
+
+# A basic (bare) component
+
+## Naming
+
+Compony components must be named according to the pattern `Components::FamilyName::ComponentName`.
+
+- The family name should be pluralized and is analog to naming a Rails controller. For instance, when you would create a `UsersController` in plain Rails, the Compony family equivalent is `Users`.
+- The component name is the Compony analog to a Rails action.
+
+Example: If your plain Rails `UsersController` has an action `show`, the equivalent Compony component is `Components::Users::Show` and is located under `app/components/users/show.rb`.
+
+If you have abstract components (i.e. components that your app never uses directly, but which you inherit from), you may name and place them arbitrarily.
+
+## Initialization, manual instantiation and rendering
+
+You will rarely have to override `def initialize` of a component, as most of your code will go into the component's `setup` block as explained below. However, when you do, make sure to forward all default arguments to the parent class, as they are essential to the component's function:
+
+```ruby
+def initialize(some_positional_argument, another=nil, *args, some_keyword_argument:, yetanother: 42, **kwargs, &block)
+  super(*args, **kwargs, &block) # Typically you should call this first
+  @foo = some_positional_argument
+  @bar = another
+  @baz = some_keyword_argument
+  @stuff = yetanother
+end
+```
+
+Typically, your components will be instantiated and rendered by Compony through the ["standalone" feature](./standalone.md). Nonetheless, it is possible to do so manually as well, for instance if you'd like to render a component from within an existing view in your application:
+
+```erb
+<% index_users_comp = Components::Users::Index.new %>
+<%= index_users_comp.render(controller) %>
+```
+
+Note that rendering a component always requires the controller as an argument. It also possible to pass an argument `locals` that will be made available to `render` (see below):
+
+```erb
+<% index_users_comp = Components::Users::Index.new %>
+<%= index_users_comp.render(controller, locals: { weather: :sunny }) %>
+```
+
+## Setup
+
+Every component must call the static method `setup` which will contain most of the code of your components. This can be achieved either by a call directly from your class, or by inheriting from a component that calls `setup`. If both classes call the method, the inherited class' `setup` is run first and the inheriting's second, thus, the child class can override setup properties of the parent class.
+
+Call setup as follows:
+
+```ruby
+class Components::Users::Show < Compony::Component
+  setup do
+    # Your setup code goes here
+  end
+end
+```
+
+The code in setup is run at the end the component's initialization. In this block, you will call a number of methods that define the component's behavior and which we will explain now.
+
+### Labelling
+
+This defines a component's label, both as seen from within the component and from the outside. You can query the label in order to display it as a title in your component. Links and buttons to components will also display the same label, allowing you to easily rename a component, including any parts of your UI that point to it.
+
+Labels come in different formats, short and long, with long being the default. Define them as follows if your component is about a specific object, for instance a show component for a specific user:
+
+```ruby
+setup do
+  label(:short) { |user| user.label } # Assuming your User model has a method or attribute `label`.
+  label(:long) { |user| "Displaying user #{user.label}" } # In practice, you'd probably use I18n.t or FastGettext here to deal with translations.
+
+  # Or use this short hand to set both long and short label to the user's label:
+  label(:all) { |user| user.label }
+end
+```
+
+To read the label, from within the component or from outside, proceed as follows:
+
+```ruby
+label(User.first) # This returns the long version: "Displaying user John Doe".
+label(User.first, format: :short) # This returns the short version "John Doe".
+```
+
+It is important to note that since your label block takes an argument, you must provide the argument when reading the label (exception: if the component implements the method `data` returning an object, the argument can be omitted and the label block will be provided that object). Only up to one argument is supported.
+
+Here is an example on how labelling looks like for a component that is not about a specific object, such as an index component for users:
+
+```ruby
+setup do
+  label(:long) { 'List of users' }
+  label(:short) { 'List' }
+end
+```
+
+And to read those:
+
+```ruby
+label # "List of users"
+label(format: :short) # "List"
+```
+
+If you do not define any labels, Compony will fallback to the default which is using Rail's `humanize` method to build a name from the family and component name, e.g. "index users".
+
+Additionally, components can specify an icon and a color. These are not used by Compony directly and it is up to you to to define how and where to use them. Example:
+
+```ruby
+setup do
+  color { '#AA0000' }
+  icon { %i[fa-solid circle] }
+end
+```
+
+To retrieve them from outside the component, use:
+
+```ruby
+my_component.color # '#AA0000'
+my_component.icon # [:'fa-solid', :circle]
+```
+
+### Providing content
+
+Basic components do not come with default content. Instead, you must call the method `content` inside the setup block and provide a block containing your view. It will be evaluated inside a `RequestContext` (more on that later).
+
+In this block, provide the HTML to be generated using Dyny: [https://github.com/kalsan/dyny](https://github.com/kalsan/dyny)
+
+Here is an example of a component that renders a title along with a paragraph:
+
+```ruby
+setup do
+  label(:all) { 'Welcome' }
+  content do
+    h1 'Welcome to my basic component.'
+    para "It's not much, but it's honest work."
+  end
+end
+```
+
+#### Naming content blocks, ordering and overriding them in subclasses
+
+Content blocks are actually named. The `content` call adds or replaces a previously defined content block, e.g. in an earlier call to `setup` in a component's superclass. When calling `content` without a name, it defaults to `main` and will overwrite any previous `main` content. However, you can provide your own name and refer to other names by using the `before:` keyword.
+
+```ruby
+setup do
+  content do # will become :main
+    h1 'Welcome to my basic component.'
+  end
+  content :thanks do
+    para 'Thank you and see you tomorrow.'
+  end
+  content :middle, before: :thanks do
+    para 'This paragraph is inserted between the others.'
+  end
+  content :thanks do
+    para 'Thank you and see you tonight.' # this overwrites "Thank you and see you tomorrow."
+  end
+  content :first, before: :main do
+    para 'This appears first.'
+  end
+end
+```
+
+This results in:
+  - This appears first.
+  - Welcome to my basic component.
+  - This paragraph is inserted between the others.
+  - Thank you and see you tonight.
+
+As you see, overusing this feature can lead to messy code as it becomes unclear what happens in what order. For this reason, this feature should only be used to decouple the content of your abstract components for allowing surgical overrides in subclasses.
+
+It is a good convention to always have one content block named `:main`, as you might want to refer to it in subclasses.
+
+#### Nesting content blocks, calling a content block from another
+
+In some situations, such as in forms, it can be useful to nest content blocks. This will also allow subclasses to override a wrapper while keeping the content, and vice versa. To make this possible, you can also use the `content` keyword inside a content block. Note that unlike the call in `setup`, this call will render a content block instead of defining it. This happens inside the request context and the content block must be defined inside the current component.
+
+Note that you cannot call another component's content block this way.
+
+Here is an example on how to use this feature, e.g. to create a bootstrap card that can be overridden with precision:
+
+```ruby
+# Components::Bootstrap::Card
+setup do
+  content hidden: true do # hidden: true will cause `render` to skip this content block. You can still use it in the nested fashion.
+    div 'I am the default content for the card'
+  end
+
+  content :card do
+    div class: 'card card-body' do
+      content :main
+    end
+  end
+end
+```
+
+The output is:
+
+```html
+<div class="card card-body"><div>I am the default content for the card</div></div>
+```
+
+So when you subclass this component, you can forget about the card and just overwrite `:main` as follows:
+
+```ruby
+# Components::Hello::HelloCard < Components::Bootstrap::Card
+setup do
+  content do # hidden is still true because the old :main content block specified that already.
+    h1 'Hello'
+    para 'Welcome to my site.'
+  end
+end
+```
+
+The output is:
+
+```html
+<div class="card card-body"><h1>Hello</h1><p>Welcome to my site.</p></div>
+```
+
+#### Removing content blocks
+
+If a component's parent class defines a content block that is undesired in a subclass component, the content block can be removed as follows:
+
+```ruby
+setup do
+  remove_content :some_content_defined_in_parent # This component will now behave as if this content block was never declared in its parent.
+end
+```
+
+### Redirecting away / Intercepting rendering
+
+Immediately before the `content` block(s) are evaluated, another chain of blocks is evaluated if present: `before_render`. If on of these blocks creates a reponse body in the Rails controller, the subsequent `before_render` blocks and all `content` blocks are skipped.
+
+This is useful for redirecting. Here is an example of a component that provides a restaurant's lunch menu, but redirects to the menu overview page instead if it's not lunch time:
+
+```ruby
+setup do
+  label(:all){ 'Lunch menu' }
+
+  before_render do
+    current_time = Time.zone.now
+    if current_time.hour >= 11 && current_time.hour < 14
+      flash.notice = "Sorry, it's not lunch time."
+      redirect_to all_menus_path
+    end
+  end
+
+  content do # This is entirely skipped if it's not lunch time.
+    h1 label
+    para 'Today we have spaghetti.'
+  end
+end
+```
+
+Similarly to `content`, the `before_render` method also accepts a name, defaulting to `:main`, as well as a `before:` keyword. This allows you to selectively extend and/or override `before_render` blocks in subclasses.

data/doc/guide/example.md

@@ -0,0 +1,228 @@
+[Back to the guide](/README.md#guide)
+
+# Example
+
+To get you a rough idea what working with Compony feels like, let's look at a small dummy application using Compony from scratch, to make this example as explicit as possible. In practice, much of the logic shown here would be moved to abstract components that you can inherit from.
+
+The example is meant to be read top-down and information will mostly not be repeated. Comments will give you a rough idea of what's going on on each line. The features are more completely documented in subsequent chapters.
+
+Please note that from this example alone, you won't be able to comprehend the underlying concepts - refer to the rest of the [guide](/README.md#guide) for this.
+
+Let's implement a simple user management page with Compony. User's have a name, an integer age, a comment, as well as a role (which we will conveniently model using `AnchorModel`: https://github.com/kalsan/anchormodel). We want to be able to list, show, create, edit and destroy users. Users having the role Admin shall not be destroyed.
+
+## The User model
+
+We'll assume a model that has the standard Rails schema:
+
+```ruby
+create_table 'users', force: :cascade do |t|
+    t.string 'name'
+    t.string 'comment'
+    t.integer 'age'
+    t.datetime 'created_at', null: false
+    t.datetime 'updated_at', null: false
+    t.string 'role', default: 'guest', null: false
+  end
+```
+
+```ruby
+class User < ApplicationRecord
+  # Refer to https://github.com/kalsan/anchormodel
+  belongs_to_anchormodel :role
+
+  # Fields define which attributes are relevant in the GUI and how they should be presented.
+  field :name, :string
+  field :age, :integer
+  field :comment, :string
+  field :role, :anchormodel
+  field :created_at, :datetime
+  field :updated_at, :datetime
+
+  # The method `label` must be implemented on all Compony models. Instead of this method, we could also rename the column :name to :label.
+  def label
+    name
+  end
+
+  # This is how we tell Compony that admins are not to be destroyed.
+  prevent :destroy, 'Cannot destroy admins' do
+    role == Role.find(:admin)
+  end
+end
+```
+
+## The Show component
+
+This components loads a user by reading the param `id`. It then displays a simple table showing all the fields defined above.
+
+We will implement this component on our own, giving you an insight into many of Compony's mechanisms:
+
+```ruby
+# All components (except abstract ones) must be placed in the `Components` namespace living under `app/components`.
+# They must be nested in another namespace, called "family" (here, `Users`), followed by the component's name (here, `Show`).
+class Components::Users::Show < Compony::Component
+  # The Resourceful mixin causes a component to automatically load a model from the `id` parameter and store it under `@data`.
+  # The model's class is inferred from the component's name: `Users::Show` -> `User`
+  include Compony::ComponentMixins::Resourceful
+
+  # Components are configured in the `setup` method, which prevents loading order issues.
+  setup do
+    # The DSL call `label` defines what is the title of the component and which text is displayed on links as well as buttons pointing to it.
+    # It accepts different formats and takes a block. Given that this component always loads one model, the block must take an argument which is the model.
+    # The argument must be provided by links and buttons pointing to this component.
+    label(:short) { |_u| 'Show' } # The short format is suitable for e.g. a button in a list of users.
+    label(:long) { |u| "Show user #{u.label}" } # The long format is suitable e.g. in a link in a text about this user.
+
+    # Actions point to other components. They have a name that is used to identify them (e.g. in the `prevent` call above) and a block returning a button.
+    # Compony buttons take the name to an action and either a family name or instance, e.g. a Rails model instance.
+    # Whether or not an instance must be passed is defined by the component the button is pointing to (see the comment for `label` earlier in the example).
+    action(:index) { Compony.button(:index, :users) } # This points to `Components::Users::Index` without passing a model (because it's an index).
+    action(:edit) { Compony.button(:edit, @data) } # This points to `Components::Users::Edit` for the currently loaded model. This also checks feasibility.
+
+    # When a standalone config is present, Compony creates one or multiple Rails routes. Components without standalone config must be nested within others.
+    standalone path: 'users/show/:id' do # This specifies the path to this component.
+      verb :get do # This speficies that a GET route should be created for the path specified above.
+        authorize { true } # Immediately after loading the model, this is called to check for authorization. `true` means that anybody can get access.
+      end
+    end
+
+    # After loading the model and passing authorization, the `content` block is evaluated. This is Compony's equivalent to Rails' views.
+    # Inside the `content` block, the templating Gem Dyny (https://github.com/kalsan/dyny) is used, allowing you to write views in plain Ruby.
+    content do
+      h3 @data.label # Display a <h3> title
+      table do # Open a <table> tag
+        tr do # Open a <tr> tag
+          # Iterate over all the fields defined in the model above and display its translated label (this uses Rails' `human_attribute_name`), e.g. "Name".
+          @data.fields.each_value { |field| th field.label }
+        end # Closing </tr>
+        tr do
+          # Iterate over the fields again and call `value_for` which formats each field's value according to the field type.
+          @data.fields.each_value { |field| td field.value_for(@data) }
+        end
+      end
+    end
+  end
+end
+```
+
+Here is what our Show component looks like when we have a layout with the bare minimum and no styling at all:
+
+![Screenshot of our component with an absolutely minimal layout](/doc/imgs/intro-example-show.png)
+
+It is important to note that actions, buttons, navigation, notifications etc. are handled by the application layout. In this and the subsequent screenshots, we explicitely use minimalism, as it makes the generated HTML clearer.
+
+## The Destroy component
+
+Compony has a built-in abstract `Destroy` component which displays a confirmation message and destroys the record if the verb is `DELETE`. This is a good example for how DRY code can become for "boring" components. Since everything is provided with an overridable default, components without special logic can actually be left blank:
+
+```ruby
+class Components::Users::Destroy < Compony::Components::Destroy
+end
+```
+
+Note that this component is fully functional. All is handled by the class it inherits from:
+
+![Screenshot of the destroy component](/doc/imgs/intro-example-destroy.png)
+
+## The New component and the Form component
+
+Compony also has a pre-built abstract `New` component that handles routing and resource manipulation. It combines the controller actions `new` and `create`, depending on the HTTP verb of the request. Since it's pre-built, any "boring" code can be omitted and our `New` components looks like this:
+
+```ruby
+class Components::Users::New < Compony::Components::New
+end
+```
+
+By default, this component looks for another component called `Form` in the same directory, which can look like this:
+
+```ruby
+class Components::Users::Form < Compony::Components::Form
+  setup do
+    # This mandatory DSL call prepares and opens a form in which you can write your HTML in Dyny.
+    # The form is realized using the simple_form Gem (https://github.com/heartcombo/simple_form).
+    # Inside this block, more DSL calls are available, such as `field`, which automatically generates
+    #    a suitable simple_form input from the field specified in the model.
+    form_fields do
+      concat field(:name) # `field` checks the model to find out that a string input is needed here. `concat` is the Dyny equivalent to ERB's <%= %>.
+      concat field(:age)
+      concat field(:comment)
+      concat field(:role) # Compony has built-in support for Anchormodel and as the model declares `role` to be of type `anchormodel`, a select is rendered.
+    end
+
+    # This DSL call is mandatory as well and automatically generates strong param validation for this form.
+    # The generated underlying implementation is Schemacop V3 (https://github.com/sitrox/schemacop/blob/master/README_V3.md).
+    schema_fields :name, :age, :comment, :role
+  end
+end
+```
+
+This is enough to render a fully functional form that creates new users:
+
+![New form](/doc/imgs/intro-example-new.png)
+
+## The Edit component
+
+Just like `New`, `Edit` is a pre-built component that handles routing and resource manipulation for editing models, combinding the controller actions `edit` and `update` depending on the HTTP verb. It uses that same `Form` component we wrote above and thus the code is as simple as:
+
+```ruby
+class Components::Users::Edit < Compony::Components::Edit
+end
+```
+
+It then looks like this:
+
+![Edit form](/doc/imgs/intro-example-edit.png)
+
+## The Index component
+
+This component should list all users and provide buttons to manage them. We'll build it from scratch and make it resourceful, where `@data` holds the ActiveRecord relation.
+
+```ruby
+class Components::Users::Index < Compony::Component
+  # Making the component resourceful enables a few features for dealing with @data.
+  include Compony::ComponentMixins::Resourceful
+
+  setup do
+    label(:all) { 'Users' } # This sets all labels (long and short) to 'Users'. When pointing to this component using buttons, we will not provide a model.
+    standalone path: 'users' do # The path is simply /users, without a param. This conflicts with `Resourceful`, which we will fix in `load_data`.
+      verb :get do
+        authorize { true }
+      end
+    end
+
+    # This DSL call is specific to resourceful components and overrides how a model is loaded.
+    # The block is called before authorization and must assign a model or collection to `@data`.
+    load_data { @data = User.all }
+
+    content do
+      h4 'Users:' # Provide a title
+      # Provide a button that creates a new user. Note that we must write `:users` (plural) because the component's family is `Users`.
+      concat compony_button(:new, :users) # The `Users::New` component does not take a model, thus we just pass the symbol `:users`, not a model.
+
+      div class: 'users' do # Opening tag <div class="users">
+        @data.each do |user| # Iterate the collection
+          div class: 'user' do # For each element, open another div
+            User.fields.values.each do |field| # For each user, iterate all fields
+              span do # Open a <span> tag
+                concat "#{field.label}: #{field.value_for(user)} " # Display the field's label and apply it to value, as we did in the Show component.
+              end
+            end
+            # For each user, add three buttons show, edit, destroy. The method `with_button_defaults` applies its arguments to every `compony_button` call.
+            # The option `format: :short` causes the button to call the target component's `label(:short) {...}` label function.
+            Compony.with_button_defaults(label_opts: { format: :short }) do
+              concat compony_button(:show, user) # Now equivalent to: `compony_button(:show, user, label_opts: { format: :short })`
+              concat compony_button(:edit, user)
+              concat compony_button(:destroy, user)
+            end
+          end
+        end
+      end
+    end
+  end
+end
+```
+
+The result looks like this:
+
+![Index component](/doc/imgs/intro-example-index.png)
+
+Note how the admin's delete button is disabled due to the feasibility framework. Pointing the mouse at it causes a tooltip saying: "Cannot destroy admins.", as specified in the model's prevention.

data/doc/guide/feasibility.md

@@ -0,0 +1,38 @@
+[Back to the guide](/README.md#guide)
+
+# Feasibility
+
+When a user has the permission to perform an action in general, but it is currently not feasible (for instance if the concerned object is incomplete, or if right now is not the right time to do the action), buttons pointing to that action should be disabled and a HTML `title` attribute should cause a tooltip explaining why this action cannot be performed right now.
+
+This can be easily achieved with the feasibility framework, which allows you to prevent actions on conditions, along with an error message. Formulate the error message similar to Rails validation errors (first letter not capital, no period at the end), as the prevention framework is able to concatenate multiple error messages if multiple conditions prevent an action.
+
+The feasibility framework currently only makes sense for resourceful components.
+
+Example:
+
+```ruby
+# app/models/user.rb
+# Prevent sending an e-mail to a user that has no e-mail address present
+prevent :send_mail, 'the e-mail address is missing' do
+  email.blank?
+end
+
+# app/models/event.rb
+# Multiple actions can be prevented at once:
+# Prevent creating or removing a booking to an event that lies in the past or that is locked
+prevent [:create_booking, :destroy_booking], 'the event is already over' do
+  ends_at < Time.zone.now || locked?
+end
+```
+
+**Note that the feasibility framework currently only affects buttons/links pointing to actions, not the action itself.** If a user were to issue the HTTP call manually, the component happily responds and performs the action. This is why you should always back important preventions with an appropriate Rails model validation:
+
+- The Rails model validation prevents that invalid data can be saved to the database.
+- The feasibility framework disables buttons and links and explains to guide the user.
+- Links are disabled by changing the href to `'#'` and adding the `.disabled` class, which is useful when bootstrap is used.
+- Authorization is orthogonal to this, limiting the actions of a specific user.
+- If an action is both prevented and not authorized, the authorization "wins" and the action button is not shown at all.
+
+Compony has a feature that auto-detects feasibility of some actions. In particular, it checks for `dependent` relations in the `has_one`/`has_many` relations and disables delete buttons that point to objects that have dependent objects that cannot automatically be destroyed.
+
+To disable auto detection, call `skip_autodetect_feasibilities` in your model.

data/doc/guide/generators.md

@@ -0,0 +1,13 @@
+[Back to the guide](/README.md#guide)
+
+# Rails Generators provided by Compony
+
+To make your life easier and coding faster, Compony comes with two generators:
+
+- `rails g component Users::New` will create `app/components/users/new.rb` and, since the component's name coincides with a a pre-built component, automatically inherit from that. If the name is unknown, the generated component will inherit form `Compony::Component` instead. The generator also equips generated components with the boilerplate code that wil be required to make the component work.
+  - The generator can also be called via its alternative form `rails g component users/new`.
+- `rails g components Users` will generate a set of the most used components.
+
+### Support for custom base components
+
+Generators will automatically detect your `BaseComponents` (see [Inheritance: best practice](./doc/guide/inheritance.md#best-practice)).