@bigbinary/neeto-form-frontend

neeto-form-nano

The neeto-form-nano allows us to build forms within neeto applications. This nano exports @bigbinary/neeto-form-frontend NPM package and neeto-form-engine Rails engine.

See this page to find host applications using this nano. Changes made in the nano should be rolled out to all of them, especially migrations.

Contents

• Development with Host Application
  • Engine
  • Frontend package
    • Installation
    • Instructions for development
    • Usage
• Instructions for Publishing

Development with Host Application

Engine

The engine adds setup for form on backend and allows us to attach forms to any model. It also stores submissions.

Installation

• Add this line to your application's Gemfile:

  source "NEETO_GEM_SERVER_URL" do
    # ...existing gems
  
    gem 'neeto-form-engine'
  end
  

• And then execute:

  bundle install
  

• Install the migrations

  bundle exec rails neeto_form_engine:install:migrations
  

• Run the migrations

  bundle exec rails db:migrate
  

• Add this line to your application's config/routes.rb file.

  mount NeetoFormEngine::Engine, at: "/neeto_form"
  

  NOTE: The mount point must be /neeto_form and cannot be changed to any other path.

• Create file neeto_form_engine.rb under config/initializers to provide the owner_class information

  NeetoFormEngine.owner_class = "Organization"
  

• Configure models to add below association to the provided owner class

  has_many :forms, class_name: "::NeetoFormEngine::Form", as: :owner
  

• Configure models to add below association to scope submission records (optional)

  has_one :submission, class_name: "::NeetoFormEngine::Submission", as: :record
  

• Configure model to add below association to attach form (optional)

  has_one :form, class_name: "::NeetoFormEngine::Form", as: :attachable
  

Customizability

NeetoFormEngine::Customizable::Forms::Createable

The engine supports customizing the default behavior of Forms::CreateService by overriding the supported methods in this concern.

Available methods:

• create_default_questions!: If you want to use custom logic to create default questions, you can specify them using this method. owner, form and params will be available globally.
• additional_form_params: If you want to include additional attributes while creating forms, you can specify them using this method. It takes one argument params which will be the form parameters passed from the front-end.

NeetoFormEngine::Customizable::Questions::Createable

The engine supports customizing the default behavior of Questions::CreateService by overriding the supported methods in this concern.

Available methods:

• create_question!: This method receives one argument params that contains the question parameters passed from the front-end.
• additional_question_params: If you want to include additional attributes while creating questions, you can specify them using this method. It takes one argument params which will be the question parameters passed from the front-end.

NeetoFormEngine::Customizable::Questions::Updateable

The engine supports customizing the default behavior of Questions::UpdateService by overriding the supported constants in this concern.

Available constants:

• EXCLUDED_UPDATE_PARAMS: If you have included extra parameters other than kind for additional use cases that are not valid entity attributes, they need to be specified as EXCLUDED_UPDATE_PARAMS.

NeetoFormEngine::Customizable::QuestionResponses::Createable

The engine supports customizing the default behavior of QuestionResponses::CreateService by overriding the supported methods in this concern.

Available methods:

• additional_initialization_logic: If you want to initialize additional variables, you can specify them using this method.
• additional_process_actions: If you want to perform any additional actions outside the transaction block, you can override this method.
• additional_create_submission_actions: You can use this method to specify any additional logic that needs to be executed after creating submissions.
• additional_create_response_actions: If you want to perform some additional actions on each of the responses, you can specify them using this method. This method receives question and response_param passed from the front-end as arguments.

Set up Google reCAPTCHA

• Sign up for an API key pair from the official website.

• Configure the following environment variables and secrets with suitable values

  • Under .env file:

    FORM_NANO_RECAPTCHA_V2_SITE_KEY=# Value from Google cloud console
    FORM_NANO_RECAPTCHA_V2_SECRET_KEY=# Value from Google cloud console
    

  • Under secrets.yml file:

    form_nano:
      recaptcha_v2:
        site_key: <%= ENV["FORM_NANO_RECAPTCHA_V2_SITE_KEY"] %>
        secret_key: <%= ENV["FORM_NANO_RECAPTCHA_V2_SECRET_KEY"] %>
    

• Include the site key in global_props

  module ApplicationHelper
    def get_client_props
      # other variables
      custom_props = {
        # other props
        form_nano_recaptcha_v2_site_key: Rails.application.secrets.form_nano.dig(:recaptcha_v2, :site_key)
      }
    end
  end
  

Frontend package

The frontend package allows us to create forms across neeto products.

Installation

• Install the NPM package

  yarn add @bigbinary/neeto-form-frontend
  

• The frontend package has a few peer dependencies that are required for the proper functioning of the package. Install all the peer dependencies using the below command:

  yarn add @bigbinary/neetoui @bigbinary/neeto-icons ramda@^0.28.0 classnames@^2.3.1 formik@2.2.9 @bigbinary/neeto-commons-frontend react-google-recaptcha
  

• Import stylesheet from the following location:

  @import "@bigbinary/neeto-form-frontend/dist/main.css";
  

Instructions for development

Check the Frontend package development guide for step-by-step instructions to develop the frontend package.

Usage

You can learn more about the usage here:

• Components
• Hooks
• Email Verification

Instructions for Publishing

Consult the building and releasing packages guide for details on how to publish.