ez-on-rails-react

This package provides a react library to interact with ez-on-rails backends.

EzOnRails provides a rails backend that is ez to use with all your needs to build fast applications having a frontend and a backend. It provides many features like a built in permission system, an easy to configure administration view, built in controllers with CRUD functionality, builtin features like searching, generators for your models etc. Have a look at the ez-on-rails repository to see the available features.

This package enables you to build frontend applications that interact with EzOnRails backends.

Installation

Install the package using npm

npm install https://github.com/D4uS1/ez-on-rails-react#v0.9.0

or yarn.

yarn add https://github.com/D4uS1/ez-on-rails-react#v0.9.0

There is a branch for each released version. See the [Versions](## Versions) section to find the newest compatible version for the backend.

Usage

1. Insert Context provider

You must add the EzOnRails context provider around your application that manages access tokens, api Versions, backend url etc.

You can also pass an onUnauthorizedCallback that is called if any hook doing http requests fail with a http 401 status code. This makes it possible to have a session management and logout the user if some token is invalid. Note that you can also set the callback by using the setOnUnauthorizedCallback methode from the useEzOnRails hook. Also note that if you use the callback, a 401 error will not be thrown. It will be catched and handled by the callback.

Example App.ts:

import React from 'react';
import { EzOnRails } from '@d4us1/ez-on-rails-react';

function App() {
  const onUnauthorizedCallback = () => {
      ...
  };

  return (
      <EzOnRails backendUrl='http://localhost:3000' apiVersion='1.0' onUnauthorizedCallback={onUnauthorizedCallback}>
        ...
      </EzOnRails>
  );
};

export default App;

Note that the apiVersion must match the defined apiVersion in the backend.

2. Use the login form component

Many of the actions to the EzOnRails backend must be authorized. The easiest way to accomplish this is to use the builtin components for user management. Dont be shocked by the design of this components. The components are simple html views without many css applied, but enable you to redesign everything by just passing the css classes of your needs. See the [Components](## Components) section for details.

import React from 'react'
import { LoginForm, EzOnRailsAuthInfo, useEzOnRails } from "@d4us1/ez-on-rails-react";

export const LoginPage = () => {
    const { authInfo } = useEzOnRails();

    useEffect(() => {
      if (authInfo) {
        // User signed in, do some initialization here
      }
    }, [authInfo]);

    const onLoginError = (e: unknown) => {
        alert("Login failed");
    }

    const onLoginSuccess = async (email: string, authInfo: EzOnRailsAuthInfo, stayLoggedIn: boolean) => {
        alert("Login success.");
    }

    return (
        <LoginForm  onLoginSuccess={onLoginSuccess}
                    onLoginError={onLoginError} />
    )
}

For now, if a user signs into your application, the access tokens are managed by EzOnRails itself. Hence you can make use of the hooks and other components that need those tokens.

Of course there are also components for a default registration workflow, like registration, password reset, confirmations etc. Every of this component can be fully redesigned by your needs. Have a look at the [Components](## Components) section for details.

Note that the success callback takes the email, authInfo and a value indicating whether the user has checked the checkbox to stay logged in after app restart. Since this method is called immediatly after the sign in, the contexts auth info may not be available. Hence if you do some further http requests here, the requests may fail. If you want to do some initialization after sign in, it is recommended to do this by a useEffect hook monitoring the authInfo, like in the example above.

You can also save the authentication information somewhere and pass it to the context provider after app restart again. If you dont want to show the stay logged in checkbox, pass hideStayLoggedIn to the component.

3. Model Type definitions

If you created a scaffold for a model in EzOnRails with the ezscaff generator, i recommend to define the model types as follows:

import { EzOnRailsRecord } from '@d4us1/ez-on-rails-react'

interface Article extends EzOnRailsRecord {
    author: string;
    title: string;
    ...
}

The inheritance of EzOnRailsRecord adds necessary attributes like the id and timestamp fields to the record. You dont need to take care about the management of what fields to pass or not if you use the hooks of this package in combination with models defined that way.

4. Model REST requests

Now you can use the useEzScaff hook to access the default actions that are available for the scaffold. This includes the index, show, create, update, delete and search action.

Example usage:

import React, { useEffect } from 'react';
import { useEzScaff } from '@d4us1/ez-on-rails-react';
import { Article } from 'models/Article';

export const ArticlesPage = () => {
    const {
        records,
        inProgress,
        error,
        getAll
    } = useEzScaff<Article>('Articles')

    useEffect(() => {
        getAll();
    }, [])

    return (
        <div>
        { inProgress && <div>...</div> }
        { error && <span>{error}</span> }
        { records && (
            <div>
                { records.map((record) => <div>{ record.title }</div>) }
            </div>
        )}
    )
}

This example fetches all articles from the backend if the page renders. Note that you can also show, create, update or delete one Article or search for articles the same way. Have a look at the [useEzScaff](### useEzScaff) explanation to see whats possible.

Note that you must pass the pluralized model name to the hook. This is necessary because per convention the base route for the scaffold is the pluralized path. The hook automaticly converts the model name to snake case, but its needed because javascript does not have a good working builtin pluralize function.

5. Simple api requests

You can make api requests to your backend using the useEzApi hook.

import React from 'react';
import { useEzApi } from '@d4us1/ez-on-rails-react';

export const SomePage = () => {
    const {
        inProgress,
        error,
        data
    } = useEzApi<{ someParam: string }, { someResponse: string }>('some/path', 'POST', { someParam: 'TEST' })

    return (
        <div>
            { inProgress && <div>In Progress</div> }
            { data && <div>{JSON.stringify(data)}</div> }
            { error && <div>{ error.toString() }</div> }
        </div>
    )
}

This example calls the path api/some/path using a http POST passing the data { someParam: 'TEST' }. The response is saved in the data result of the hook.

Note that this usage triggers the request by calling the hook. It is also possible to trigger the api manually, for instance after a button click. See the [Custom API requests](### 6. Custom API requests) section for details.

6. Custom API requests

If you want to to make a custom request that is not triggered on hook call you have three possibilities.

1. Use callApi that is returned by useApi (recommended)

The useEzApi hook also returns the function that calls the request itself. Hence it can be called manually.

Example:

import React from 'react';
import { useEzApi } from '@d4us1/ez-on-rails-react';

export const SomePage = () => {
    const {
        inProgress,
        error,
        data,
        callApi
    } = useEzApi<{ someParam: string }, { someResponse: string }>('some/path', 'POST', undefined, { skipInitialCall: true })

    return (
        <div>
            <button onClick={ () => callApi({ someParam: string }) }>Start request</button>
            { inProgress && <div>In Progress</div> }
            { data && <div>{JSON.stringify(data)}</div> }
            { error && <div>{ error.toString() }</div> }
        </div>
    )
}

As you can see here, you can pass the option skipInitialCall to the hook, hence the hook skips the initial request when its called. Instead you can use the callApi method that is used by the hook itself, to trigger the request. The result of the request will be returnd by the data result of the hook, as soon its available.

You can pass parameters to this function, those will be passed as parameters to the request. If you do not pass parameters, but defined some in the hook itself, they will be send instead.

The callApi method returns a Promise with the result. Hence, if you dont want to use the returned data attribute from the hook, you can also wait for the result.

const result = await callApi({ someParam: string });

2. Use the useEzApiHttpClient hook

This hook can be useful if you have many different http requests in one component and dont want to define an useEzApi hook for each of them. The hook returns only a method to call a request to the backend. The method accepts a path, the http method and the parameters and returns a promise of the response. Hence you can decide if you want to wait for the response of call it asynchronous.

The hook accepts a base path. This must not ne given, but can be useful if you want to access actions behind some scaffold that are no CRUD actions.

Example:

import React from 'react';
import { useEzApiHttpClient } from '@d4us1/ez-on-rails-react';

export const SomePage = () => {
    const { call } = useEzApiHttpClient()
    const response = useState<{ someResponse: string } | null>(null)

    const onClickRequest = async () => {
      const result = await call('some/path', 'POST', { someParam: string })
      setResponse(result)
    }

    return (
        <div>
            <button onClick={ () => call('some/path', 'POST', { someParam: string }) }>Start request</button>
            { response && <div>{JSON.stringify(response)}</div> }
        </div>
    )
}

3. Use the http client

You can call the http methods that are delivered by the package directly, but it is not recommended.

import React, { useState } from 'react';
import { EzOnRailsHttp, useEzOnRails } from '@d4us1/ez-on-rails-react';

export const SomePage = () => {
    const { backendUrl, apiVersion, authInfo } = useEzOnRails();
    const [response, setResponse] = useState<{ someResponse: string } | null>(null);
    
    const onClickRequest = async () => {
        const result = await EzOnRailsHttp.client.post(backendUrl, 'some/path', { someParam: 'Test' }, authInfo, apiVersion);
        setResponse(result);
    }
    
    return (
        <div>
            <button onClick={ () => callApi({ someParam: string }) }>Start request</button>
            { response && <div>{JSON.stringify(response)}</div> }
        </div>
    )
}

The http client also converts the parameters from camelCase to snake_case and the response from snake_case to camelCase and does the other necessary operations for you.

Have a look at the source of the http client to see the possible callable methods here. It also contains some non standard methods related to the registration process, but as mentioned before, it is recommended to use just the components and hooks.

Versions

Release versions are located in the branches prefixed with v followed by the verison number. You must have a look at the following compatibility list, because you must take a version that is compatible with your ez-on-rails backend.

Version	Compatible Backend Versions
0.8.0	0.8.0
0.8.1	0.8.0, 0.8.1
0.8.2	0.8.1
0.9.0	0.9.0

Components

There are several components you can use, especially for the user registration workflow. Every component is customizable in its style, by passing several properties ending with className. The components holding forms are customizable by passing the props described in the [DefaultFormProps](### DefaultFormProps) section.

LoginForm

Shows a login form that automatically saves the authInfo for following api requests to the backend in the context. The form is fully customizable in its style, labels and texts.