next_on_rails 0.1.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 20645c6f6a59e3294c584a02c801b53efd4711b66b5b28e431bde613e6209e24
+  data.tar.gz: f42e5e7d240bbf70d949b7e99b4ee3e761f7ff16a17ad4fc76bb10c3928a7bf3
+SHA512:
+  metadata.gz: 91001cd6fa66e07fb965caaf96e232ff678d20df93b2d19ab418ba000d7d36c5f91bea06d1a7745e69d347df31722d3ec059a9406c883f6cbe5475e404c5890b
+  data.tar.gz: 671d41b98f9ed825ed29b81e639b4c6909ff87af9fdd4c241e06afdf95c20914f990f4e1fb22b760ec39b0efa48afb40a659a0ad42ae74a92dbd5d52e94f3370

data/MIT-LICENSE

@@ -0,0 +1,20 @@
+Copyright 2019 Enrico
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -0,0 +1,591 @@
+# Next On Rails
+
+Next On Rails (aka NOR) is a Ruby gem and a NPM package that help developers
+connecting [Rails](https://rubyonrails.org/) --api backend app to
+[Next.js](https://nextjs.org/) frontend app.
+
+The Ruby gem setup Rails api app to serve json in the [jsonapi
+format](https://jsonapi.org/) using the awesome Netflix [fast
+jsonapi](https://github.com/Netflix/fast_jsonapi) gem and configure
+[Devise](https://github.com/plataformatec/devise) for you with [Devise Token
+Auth](https://github.com/lynndylanhurley/devise_token_auth/tree/master/lib/generators/devise_token_auth)
+for authentication.
+
+The NPM package provides a set of [React
+hooks](https://reactjs.org/docs/hooks-intro.html) and utility to interact with
+backend. Basically it allows developers to:
+
+- fetch data with [Next.js
+  `getInitialProps`](https://github.com/zeit/next.js/#fetching-data-and-component-lifecycle)
+  async function in an easy way
+- handle Rails resources as React states easily with hooks
+  ([CRUD](https://en.wikipedia.org/wiki/Create,_read,_update_and_delete))
+
+The NPM package also provides a `requester` object that performs HTTP requests
+to Rails backend taking care of Devise Token Auth authentication token
+management.
+
+## Installation
+
+Create a fresh Rails --api app:
+
+    rails new YOUR-APP --api
+
+Add in the Gemfile Next On Rails
+
+    gem 'next_on_rails'
+    bundle
+
+Install
+
+    rails g nor:install
+
+This generator setup your backend and generate a new frontend app in Next.js
+inside the `./frontend` directory.
+
+**What's appened?**
+
+1. Generation of the `User` model for authentication with Devise
+2. Add `UserSerializer` in `app/serializers/user_serializer.rb` and `CurrentUserSerializer` in `app/serializers/current_user_serializer.rb`
+3. Add Devise config file in `config/initializers/devise.rb`
+4. Add Devise Token Auth config file in `config/initializers/devise_token_auth.rb`
+5. Add CORS configuration in `config/initializers/cors.rb`
+6. Add Devise routes in `config/routes.rb`
+7. Install a new `ApplicationController` that extends from `NextOnRails::ApplicationController`
+8. Add [Foreman gem](https://github.com/ddollar/foreman) gem and `Procfile`
+9. Setup [`letter_opener` gem](https://github.com/ryanb/letter_opener) for development environment
+10. Generate a Next.js frontend app in `./frontend` directory
+
+Now you are ready to use Next On Rails! Let's generate something:
+
+    rails g nor:scaffold post title body:text public:boolean
+    rails db:migrate
+
+And run your backend and fronend with `foreman start`. Rails backend runs on
+port 3000, while Next.js frontend runs on port 3001 (with
+[express.js](https://github.com/expressjs/express))
+
+Now visit [http://localhost:3001](http://localhost:3001). You should see the
+homepage with login and registration form. You can also visit the post CRUD
+pages just generated at
+[http://localhost:3001/posts](http://localhost:3001/posts).
+
+## The Frontend App
+
+The frontend app is a normal Next.js app with some enhancements:
+
+- Configured to use [SASS](https://sass-lang.com/) (see `./frontend/next.config.js`)
+- [Bootstrap](https://getbootstrap.com/) ready
+- The `App` React component is not the default `import App from 'next/app'` but `import App from 'next-on-rails/app'` (some High Order Components have been applied)
+- In the `./frontend/components` there are some usefull React components:
+  - `<Flash/>` (for display flash messages)
+  - `<LoginForm/>`
+  - `<RegistrationForm/>`
+  - `<Input/>`, `<CheckBox/>`, `<Select/>`, `<TextArea/>` forms
+
+# next-on-rails NPM package
+
+Let's say that we have the resources _posts_, in our backend we have the model
+`./app/models/post.rb` and the controller
+`./app/controllers/posts_controller.rb` with the usual crud actions _index_,
+_show_, _create_, _update_ and _destroy_. Now lets see how we can handle this
+resources from the Next.js frontend app using the next-on-rails NPM package.
+
+First of all we need to create a `/posts` page with the list of the posts. So
+we add the file `./frontend/pages/posts/index.js`:
+
+    const PostsIndex = props => {
+      return (
+        <div>
+          <h1>Posts</h1>
+          <!-- content here -->
+        </div>
+      )
+    }
+
+    export default PostsIndex
+
+We have just created a simple React functional component. This component will
+render the entire `/posts` HTML page. Now it would be nice if the component
+was initialized with a property `posts`, an array with the posts to display in
+this page. We need to request the posts to the Rails backend at
+`http://localhost:3000/posts.json` (standard
+[restful](https://en.wikipedia.org/wiki/Representational_state_transfer)
+route).
+
+### getInitialResources
+
+Next On Rails can help us with the function `getInitialResources` that returns
+an async function that returns the object
+`{ <resourcesName>: arrayOfResources }`
+that is the `getInitialProps` function that we need!! So we can change our
+component:
+
+    import { getInitialResources } from 'next-on-rails/resources'
+
+    const PostsIndex = props => {
+      return (
+        <div>
+          <h1>Posts</h1>
+          <ul>
+            {props.posts.map(post => <li key={post.id}>{post.title}</li>)}
+          </ul>
+        </div>
+      )
+    }
+
+    PostsIndex.getInitialProps = getInitialResources('posts')
+
+    export default PostsIndex
+
+Now the React component will be initialized with the property `posts` that is
+the array with all posts returned by the Rails backend `posts#index` endpoint.
+
+So `getInitialResources` call the index action of the controller associated at
+the resources passed as first parameter (`'posts'` in this example). It has
+also an optional second parameter: the request parameters used to make the
+request to the backend.
+
+### getInitialResource
+
+We can do the same for the single post page. We need to create a `/posts/:id`
+page. So we add the file `./frontend/pages/posts/show.js`. In this case we
+have to add the route to _express_ (in `./frontend/server.js` file) cause the
+route `/posts/:id` is [dynamic](https://github.com/zeit/next.js#with-link):
+
+    server.get('/posts/:id(\\d+)', (req, res) => {
+      app.render(req, res, '/posts/show', { id: req.params.id })
+    })
+
+The React component for this page will be:
+
+    import { getInitialResource } from 'next-on-rails/resources'
+
+    const PostsShow = props => {
+      return (
+        <div>
+          <h1>Post #{props.post.id}</h1>
+          <h2>{props.post.title}</h2>
+          <p>
+            {props.post.body}
+          </p>
+        </div>
+      )
+    }
+
+    PostsShow.getInitialProps = getInitialResource('post')
+
+    export default PostsShow
+
+In this case we used the function `getInitialResource` that is similar to
+`getInitialResources` but it calls the endpoint `posts#show` passing the
+parameter `id` retrieved from the current url. The property returned is no
+more an array, but a js object with the post (
+`{post: {id: 1, title: ..., body: ..., ...}}`).
+
+**NB:** first, we have said that the Rails backend responds in jsonapi format,
+but the post object is not in jsonapi format. Next On Rails normalize the
+jsonapi format internally for us. So in our frontend, we have the data ready
+to use!
+
+### composeGetInitialResources
+
+This function is like `getInitialResources` or `getInitialResource` but take a
+list of resource names and combine the property to pass to the React
+component. For example if we want to prefetch a post and a list of authors (in
+an edit page we can edit the post author for example) we can use this function:
+
+    PostsEdit.getInitialProps = composeGetInitialResources('post', 'authors')
+
+For this function the plurality of names are very important: singular names
+will be request the `show` action, plural names the `index` action. With this
+function is not possible to pass HTTP extra params. If you need to pass extra
+HTTP params you should call `getInitialResources` or `getInitialResource` and
+compose yourself the results.
+
+`composeGetInitialResources` __performs a single HTTP request__.
+
+### useResources
+
+Now let's say we want update a post. We need to create a `/posts/:id/edit`
+page. So we add the file `./frontend/pages/posts/edit.js` and add the route to _express_.
+
+The React component for this page will be:
+
+    import { getInitialResource, useResources, useResourceForm } from 'next-on-rails/resources'
+    import { Input, TextArea, CheckBox, HiddenIdField } from '../inputs'
+
+    const PostsEdit = props => {
+      const [, post, { update }] = useResources('posts', [], props.post)
+      const [submit, getError] = useResourceForm(update)
+
+      return (
+        <div>
+          <h1>Edit Post #{post.id}</h1>
+          <form onSubmit={submit}>
+            <HiddenIdField id={post.id} />
+            <Input name="title" value={post.title} error={getError('title')} />
+            <TextArea name="body" value={post.body} error={getError('body')} />
+            <CheckBox name="public" value={post.public} error={getError('public')} />
+            <button type="submit" className="btn btn-primary">
+              Save
+            </button>
+          </form>
+        </div>
+      )
+    }
+
+    PostsEdit.getInitialProps = getInitialResource('post')
+
+    export default PostsEdit
+
+Ok, we have a lot to say about this component. Don't worry!
+Let's start from the React hook `useResources`.
+
+The idea is that we have a state consisting of 2 elements. An array with a
+collection of resources and an object with a single resource. For example the
+array with all posts and an object with the current post. This 2 elements
+should be bound together so if I change the resource also the element with
+the same id in the resources array should change accordingly, and vice versa.
+
+This hook returns an array with four elements:
+`[arrayOfResources, currentResourceObject, { actions }, dispatch]`.
+The first two elements are the state, the array of resources (first one) and a
+single resource (second one). The third is an object with the five functions
+to perform the CRUD operations: `index`, `show`, `create`, `update` and
+`destroy`. The fourth is the dispatch function returned by the
+[`useReducer`](https://reactjs.org/docs/hooks-reference.html#usereducer) React
+hook that is used internally by the `useResources` hook.
+
+The third element is an object with five function, let's see one by one:
+
+- `function index(params)` has as its argument HTTP params and performs a
+  request to the `resources_controller#index` action of Rails backend. For
+  example you can call  `index({ page: 2 })` to get array of posts.
+  Returns a promise that will be resolved with the array of resources or
+  rejected with the errors.
+
+- `function show(id, params)` has as its first argument the ID of a resource
+  and as its second argument HTTP params. Performs a request to the
+  `resources_controller#show` action of Rails backend. Returns a promise that
+  will be resolved with the object of the resource with the corresponding ID
+  or rejected with the errors.
+
+- `function create(params)` has as its argument the params to create a new
+  resource. For example to create a new post you can call
+  `create({ title: 'Spiderman is dead', body: '...', public: true })`.
+  Performs a request to the `resources_controller#create` action of Rails
+  backend. Returns a promise that will be resolved with the object just
+  created or rejected with the errors.
+
+- `function update(id, params)` has as its first argument the ID of the
+  resource to update and as its second argument params to update. For example
+  to update a post you can call
+  `update(1, { title: 'Spiderman is alive', body: '...', public: true })`.
+  Performs a request to the `resources_controller#update` action of Rails
+  backend. Returns a promise that will be resolved with the object just
+  updated or rejected with the errors.
+
+- `function destroy(id)` has as its argument the ID of the resource to delete.
+  Performs a request to the `resources_controller#destroy` action of Rails
+  backend. Returns a promise that will be resolved with no arguments or
+  rejected with the errors.
+
+So now in our previous example we can understand the line
+
+    const [, post, { update }] = useResources('posts', [], props.post)
+
+We want a state with a post (initialized with the property `post`) and a
+function to update it! For this component we don't need posts array and any
+other CRUD functions.
+
+### useResourceForm
+
+Now let's talk about the other very useful hook that NOR makes us available:
+`useResourceForm`. This hook take a CRUD function which we talked about
+earlier as first argument, a success callback as second argument and an error
+callback as third argument.
+
+It returns an array with two functions: `[submit, getError]`. The first one is
+a function that is ready to pass as value of `onSubmit` form tag attribute. It
+collects all form data with
+[`FormData`](https://developer.mozilla.org/en-US/docs/Web/API/FormData) web
+API object and then call the CRUD function (passed as first parameter) with
+this form data. The resource ID can be passed as hidden field tag.
+
+The second function `getError` takes a resource field as string, like the post
+attribute `'title'`, and returns a validation error message for this attribute
+if there is one. The errors are modelled as a React state. So at the beginnig
+there are no errors and the function will return always `null`. After a failed
+submit the function can return the validation error message. So if we call
+`getError('title')` we get `null` if there is no validation errors or for
+example _"Title can't be blank"_ if there is.
+
+So we can now understand the line in the previous example
+
+    const [submit, getError] = useResourceForm(update)
+
+We get the `submit` function to update a post and the `getError` function to
+display the validation error messages.
+
+### useCurrentUser
+
+Always in our React components we can use this hook:
+
+
+    import { useCurrentUser } from 'next-on-rails/current-user'
+
+    const HelloUser = () => {
+      const { currentUser } = useCurrentUser()
+
+      return (
+        <p>{ currentUser ? `Hello ${currentUser.username}` : 'You are not logged' }</p>
+      )
+    }
+
+    export default HelloUser
+
+This hook return an object with two key. `currentUser` is the object with the
+current user logged or `null`. `setCurrentUser` is a function to update the
+current user.
+
+    const { currentUser, setCurrentUser } = useCurrentUser()
+
+### useFlash
+
+We can use flash messages also in our Next.js frontend app. Here the previous example with flash messages:
+
+    import { getInitialResource, useResources, useResourceForm } from 'next-on-rails/resources'
+    import { useFlash } from 'next-on-rails/utils'
+    import { Input, TextArea, CheckBox, HiddenIdField } from '../inputs'
+    import Flash from '../flash'
+
+    const PostsEdit = props => {
+      const { setFlash } = useFlash()
+      const [, post, { update }] = useResources('posts', [], props.post)
+      const [submit, getError] = useResourceForm(update, () => {
+        setFlash('notice', 'Post updated successfully')
+      })
+
+      return (
+        <div>
+          <Flash />
+          <h1>Edit Post #{post.id}</h1>
+          <form onSubmit={submit}>
+            <HiddenIdField id={post.id} />
+            <Input name="title" value={post.title} error={getError('title')} />
+            <TextArea name="body" value={post.body} error={getError('body')} />
+            <CheckBox name="public" value={post.public} error={getError('public')} />
+            <button type="submit" className="btn btn-primary">
+              Save
+            </button>
+          </form>
+        </div>
+      )
+    }
+
+    PostsEdit.getInitialProps = getInitialResource('post')
+
+    export default PostsEdit
+
+
+We can use the hook `useFlash` from which we can get a function to set a flash
+message and then we can display the component `Flash` that will show the
+message. You can find the `Flash` component in the file
+`./frontend/components/flash.js` where you can customize it as you want.
+
+### useLoading
+
+`useLoading` is another utility hook to know when the frontend is loading data from backend. Is quite simple:
+
+    import { useLoading } from 'next-on-rails/utils'
+
+    const Loader = props => {
+      const loading = useLoading()
+
+      if (loading) {
+        return <img src='loader.gif' alt="loading" />
+      } else {
+        return null
+      }
+    }
+
+### Requester
+
+To perform HTTP request to backend you should use the `requester`.
+
+    import requester from 'next-on-rails/requester'
+
+    requester.get('/posts')
+      .then(function (response) {
+        // handle success
+        console.log(response)
+      })
+      .catch(function (error) {
+        // handle error
+        console.log(error);
+      })
+
+It is a wrapper over [Axios](https://github.com/axios/axios) and it works in
+the same way. You can also access to axios object with `requester.axios`.
+
+So why the `requester`? Because is handle for you the [Devise Token Auth
+authentication
+token](https://devise-token-auth.gitbook.io/devise-token-auth/conceptual),
+adding the token in the request header and change it at every request based on
+the previous response. The requester save the token on cookies.
+
+It also normalize the jsonapi response. For example if reponse json is
+
+    {
+      "data": [
+        {
+          "id": "1",
+          "type": "post",
+          "attributes": {
+            "id": 1,
+            "title": "My first blog post",
+            "body": "Amazing",
+            "public": true
+          }
+        },
+        {
+          "id": "2",
+          "type": "post",
+          "attributes": {
+            "id": 2,
+            "title": "My second blog post",
+            "body": "Wow",
+            "public": false
+          }
+        }
+      ]
+    }
+
+it will be normalized in:
+
+    [
+      {
+        "id": 1,
+        "title": "My first blog post",
+        "body": "Amazing",
+        "public": true
+      },
+      {
+        "id": 2,
+        "title": "My second blog post",
+        "body": "Wow",
+        "public": false
+      }
+    ]
+
+### Config
+
+NOR try to follow the Rails conventions, but you can customize something
+editing the configuration file `./frontend/next-on-rails.config.js`. The default config is this:
+
+    {
+      baseURL: 'http://localhost:3000',
+      flashTimeout: 5000,
+      devisePaths: {
+        validateToken: '/auth/validate_token',
+        signIn: '/auth/sign_in',
+        signOut: '/auth/sign_out',
+        signUp: '/auth',
+        passwordReset: '/auth/password',
+        passwordChange: '/auth/password',
+        unlock: '/auth/unlock'
+      },
+      deviseFormInputNames: {
+        email: 'email',
+        password: 'password',
+        passwordConfirmation: 'password_confirmation'
+      }
+    }
+
+You can customize the resource names and actions:
+
+    resources: {
+      posts: {
+        routes: {
+          index: { method: 'get', url: '/all_posts.json' }
+        },
+        name: {
+          singular: 'post',
+          plural: 'posts'
+        }
+      }
+    }
+
+## Add custom action
+
+Until now we have always talk about the standard CRUD action. But how to do if
+we need manage a custom controller action?
+
+We can add in our post controller a new action:
+
+    def like
+      @post = Post.find(params[:id])
+      @post.increment!(:like_counter)
+      render json: PostSerializer.new(@post)
+    end
+
+And in `routes.rb`
+
+    resources :posts do
+      member do
+        patch :like
+      end
+    end
+
+Our frontend page component should be:
+
+    import { getInitialResource, useResources } from 'next-on-rails/resources'
+    import requester from 'next-on-rails/requester'
+
+    const PostsShow = props => {
+      const [, post, , dispatch] = useResources('posts', [], props.post)
+
+      const like = (event) => {
+        requester.patch(`/posts/${post.id}/like`)
+          .then(response => {
+            dispatch({ type: 'set', resource: response.data })
+          })
+          .catch(console.log)
+      }
+
+      return (
+          <div className="container pt-4">
+            <h1 className="mb-5">Post #{post.id}</h1>
+
+            <p>{post.body}</p>
+
+            <div>
+              <button onClick={like}>Like</button>
+              {post.like_counter} people like it
+            </div>
+        </div>
+      )
+    }
+
+    PostsShow.getInitialProps = getInitialResource('post')
+
+    export default PostsShow
+
+We have create a custom function `like` that performs the `posts#like` action
+and on success we replace the current post state object with the new post
+object returned from the HTTP request. In this way the `like_counter` will be
+updated and React re-render the incremented counter.
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
+
+## About Uqido
+
+[![uqido](https://i.imgur.com/FAo2W7w.png)](http://uqido.com)
+
+Next On Rails is maintained and funded by [Uqido](https://uqido.com).
+The names and logos for Uqido are trademarks of Uqido s.r.l.
+
+The [Uqido team](https://www.uqido.com/en/about-us/).