Getting started for ASP.NET Core + React project

Here we describe how to add EasyQuery widgets to your ASP.NET Core + React.js project.

Prerequisites

  1. You have an ASP.NET Core (version 2.1+) project with React.js on the client-side. We suppose the project was created using a standard ASP.NET Core template (dotnet new react or ... reactredux) but it's not the requirement.
  2. Your application uses Entity Framework Core to work with the database. (NB: it's possible to use EasyQuery without EF Core as well but for the sake of simplicity we will not consider other cases here).

Server-side changes

First, we are going to add EasyQuery to your ASP.NET Core backend project.

1: Add EasyQuery packages to your project

Since we have a standard ASP.NET Core project with EntityFramework Core for working with the database - then we will need the following 2 EasyQuery packages be added to your .csproj file:

    <PackageReference Include="Korzh.EasyQuery.AspNetCore" Version="5.1.1" />
    <PackageReference Include="Korzh.EasyQuery.EntityFrameworkCore.Relational" Version="5.1.1" />

2: Add EasyQuery services and middleware

On this step we will setup EasyQuery services and middleware.

First of all you need to register EasyQuery services in DI container. Here is the code you will need to add to your Startup class:

public void ConfigureServices(IServiceCollection services)
{
    .    .    .    .   .   .
    services.AddEasyQuery()
        .UseSqlManager();
}

The lines above performs two tasks:

  • The first line registers EasyQuery services in dependency injection container
  • The seconde one specify the default EasyQuery manager which is the main "engine" that covers the most of EasyQuery functions: saving and loading of the models and queries, SQL generation, data retriving and exporting, etc. Currently there are two possible options: EasyQueryManagerSql and EasyQueryManagerLinq.

Finally, we need to setup the middleware which will handle HTTP requests from the client-side, pass them to the manager, takes the result and prepares it for sending back to the client. To avoid any conflicts with MVC or SPA handlers we put EasyQuery middleware before them:

public void Configure(IApplicationBuilder app, IHostingEnvironment env)
{
    .   .   .   .   .   .

    app.UseEasyQuery(options => {
        options.Endpoint = "/api/easyquery";
        options.UseDbContext<AppDbContext>();
        options.UsePaging(25);
    });

    app.UseMvc(routes => {
	     .    .    .    .
    });

    app.UseSpa(spa => {
        .   .   .   .
    });
}

The code above defines the following main settings:

  1. The endpoint is set to /api/easyquery. This means that all requests from EasyQuery widgets will be started with this path (like /api/easyquery/models/{modelId} to load the model). Please note that this is the default value so you can omit this setting in your app.
  2. We will use the DbContext class specified in UseDbContext call to get the model or to execute the generated queries. It's the fasteset way to specify the model load and the connection to your DB. Otherwise you will need to set them separately via UseModelLoader or UseDbConnection extension functions.
  3. The last UsePaging call turns on the paging and set the page size.

So, server-side setup is finished. Now we need to setup the client-side part.

Add EasyQuery view to your React app

Now it's time to configure the client-side scripts and styles. Here we suppose that your React application is placed in ClientApp subfolder of your main project's folder.

1. Adding JQuery and EasyQuery styles

Currently, EasyQuery still uses JQuery and JQuery UI for rendering some widgets (we will remove this dependence in future updates). So, we need to add those libraries to our project and the simplest way to do it - is to include necessary scripts right to the index HTML file of your client-side app: ClientApp/public/index.html.

Additionally, it's necessary to include EasyQuery CSS files which defines the basic styles for our widgets and views. They also should be placed into index.html:

<head>
    .    .    .    .    .    .
	
	<!-- EasyQuery CSS -->
    <link rel="stylesheet" href="https://cdn.korzh.com/eq/5.1.1/eq.core.min.css">
    <link rel="stylesheet" href="https://cdn.korzh.com/eq/5.1.1/eq.view.min.css">

    <!-- JQuery scripts -->
    <script src="https://ajax.aspnetcdn.com/ajax/jQuery/jquery-3.4.1.min.js"></script>
    <script src="https://ajax.aspnetcdn.com/ajax/jquery.ui/1.10.4/jquery-ui.min.js"></script>
</head>

Additionally you can add Chat.js script file as well if you plan to show the charts for query results:

    .    .    .    .    .    .


    <!-- ChartJS scripts -->
    <script src="https://cdn.jsdelivr.net/npm/chart.js@2.8.0"></script>
</head>

2. Adding EasyQuery NPM packages

To install EasyQuery packages just open the console in your ClientApp folder and run the following command :

npm install "@easyquery/core" "@easyquery/broker-eqs" "@easyquery/ui" "@easyquery/ui-jquery"

3. Adding EasyQuery component

Here we are goint to add a new view (page) that will contain the EasyQuery "advanced search" functionality.

It terms of React.js it will be a new component which in our case will includes 2 files: EasyQuery.js (the component's code) and EasyQueryHtml.js (the JSX template).

The template part for this new view should contain several "slots" for EasyQuery widgets - some div elements with special IDs. Here are some of those IDs:

  • QueryPanel - for conditions widget
  • ColumnsPanel - for columns widget
  • ResultPanel - for result panel widget which will combine a grid to show the result set and the chart (if showChart option is turned on).

To simplify the task you can use the files from our sample project

Just copy EasyQuery.js and EasyQueryHtml.js files from there to the ClientApp/src/components folder of your project.

4. Explaining the component's code

EasyQuery introduces the concept of a "view". "View" - is a set of different EasyQuery widgets assembled to work together on some web page. There are several views available out-of-the-box. Here we are going to use the AdvancedSearch view.

So, basically, all you need to do, is to create an instance of some EasyQuery view class during the initialization of your React component and then call its init method. The best place to do it - is in componentDidMount method.

So, in general, the content of your component will look like the following:

import React, { Component } from 'react';

//including easyquery view classes
import { AdvancedSearchViewJQuery } from '@easyquery/ui-jquery';

//including the JSX template 
import AdvancedSearchHtml  from './EasyQueryHtml';

export class EasyQuery extends Component {
    static displayName = EasyQuery.name;

    //creating an instance of EasyQuery view
    view = new AdvancedSearchViewJQuery();

    componentDidMount() {
	    //setting differnt EasyQuery options
        const options = {
		  .    .    .    . 
        }
        
		//initilizing the view
        this.view.init(options);
    }

    render() {
	    //rendering the template
        return (
            <AdvancedSearchHtml />
        );
    }

    shouldComponentUpdate() {
	    //EasyQuery view will render everything by itself - so we need to inform React that this component is not affected by the changes in state or props.
        return false;
    }
}

5. Wrap it up

To make new component accessible you will also need to add a new item to the main App component (in /ClientApp/src/App.js module):

import React, { Component } from 'react';
.   .   .   .   .   .   .
import { EasyQuery } from './components/EasyQuery';

export default class App extends Component {
  static displayName = App.name;

  render () {
    return (
      <Layout>
        <Route exact path='/' component={Home} />
		.   .   .   .   .   .   .
        <Route path='/easy-query' component={EasyQuery} />
      </Layout>
    );
  }
}

That's all. If everything was done right you will get something like the following in result:

eq-aspcore-react