add documentation and changelog

Author: Nils Henning

CHANGELOG.md

@@ -398,14 +398,7 @@ And use it in your view as follows:
 ### Rails Views in Matestack Pages/Components
 
 To render existing rails views inside your components or pages use the new `rails_view` component. It replaces the old `html` component.
-You can render existing partials and views with this helper anywhere in your app. 
-Views/Partials that are rendered with a `rails_view` component can access instance variables of the corresponding controller 
-or you can pass data directly as a hash to it and access it in your view. See below for further details and examples.
-
-Rails View in a component:
-```
-```
-
+You can render existing partials and views with this helper anywhere in your app. For further information read the `rails_view` documentation.
 
 ### Removed Components
 

docs/components/rails_view.md

@@ -0,0 +1,61 @@
+# matestack core component: rails_view
+
+Show [specs](../../spec/usage/components/rails_view_spec.rb)
+
+Use your rails views or partials with this component in your views, matestack pages, components or apps. 
+
+## Parameters
+
+This component expects that either `view` or `partial` is given as parameter.
+
+#### # view - optional
+Expects a string, specifying the path of the view that should be rendered by the component. 
+The path resolution works like rails `render 'your_path'` path resolution.
+
+#### # partial - optional
+Expects a string, specifying the partial that should be rendered by the component.
+The path resolution works like rails `render partial: 'your_path'` path resolution.
+
+## Example 1 - Using Rails View and Partial on a page, component or app
+
+```ruby
+class WelcomePage < Matestack::Ui::Page
+  def response
+    rails_view view: 'welcome/header'
+    rails_view partial: 'welcome/hero'
+    heading text: 'Welcome', size: 1
+  end
+end
+```
+
+The above page will first render your 'welcome/header' view. 
+If for example you use erb templates, it will render your `app/views/welcome/header.html.erb` view.
+And secondly it will render your 'welcome/hero' partial. 
+Again, if you use erb templates, it will render your `app/views/welcome/_hero.html.erb` partial.
+The usage of `rails_view` is the same on a page, component or app.
+
+
+## Example 2 - Using Rails View in a view
+
+You can also use `rails_view` in another view
+
+```html
+<%= matestack_component(:rails_view, view: 'welcome/header') %>
+<%= matestack_component(:rails_view, partial: 'welcome/hero') %>
+```
+
+## Example 3 - Passing and accessing data
+
+You can access all your instance variables from your controller action within a view or partial rendered by `rails_view`.
+You can also pass data explicitly. Just add them to the hash you pass to the `rails_view` call. 
+You can access those like you would do if you pass `locals` to a rails view or partial.
+
+Your `rails_view` call:
+```ruby
+rails_view view: 'welcome/header', headline: 'Great to see you!'
+```
+
+and in your rails view you can access your data as follows:
+```
+<h1><%= headline %></h1>
+```