projectestac/mapa-innovacio repository overview

⁠Map of pedagogical innovation in Catalonia

https://innovacio.xtec.gencat.cat⁠

⁠Description

This application deals with five types of data:

• The innovation programs promoted or certified by the Departament of Education of the Government of Catalonia.
• A list of schools participating in these programs since the school year 2015/16.
• The relationships between schools and innovation programs (year of participation, project title, etc.).
• The current school zones of Catalonia, organized on two levels: 10 "local services" (Serveis Territorials) and 73 school districts (Serveis Educatius de Zona).
• Information about educational levels, school types and other metadata.

All these data are used to build an interactive map and pages with specific information about schools, programs and projects.

⁠Main features

The main features of this application are:

• Show on the map all the schools participating on the selected programs, year by year.
• Allow to select/unselect which programs should be shown on the map, based on their characteristics (educational level, innovation type, subject, etc.)
• Show information about a specific innovation program: objectives, rules, agenda, schools involved, etc.
• Show information about a specific school: address, location, educational levels, website, participation in innovation programs, etc.
• Show information about school districts and the local impact of each innovation program.
• Full-text search engine, allowing to search by keywords, program descriptions, school names, districts, etc.
• Representation of the "presence density" of each innovation program on school districts. This index is calculated by dividing the number of schools participating in each program by the total number of schools having at least one of the educational levels included in it.

⁠Components

This is a Progressive Web Application⁠ built with the following open source components:

• React⁠ as a main framework and create-react-app⁠ as a scaffolding, compilation and delivery system.
• Leaflet⁠ and react-Leaflet⁠, used to build the maps with cartography provided by Wikimedia Commons⁠.
• React Router⁠ to allow online and offline navigation between the different sections, always providing a permalink to current content.
• Material-UI⁠ has been used to build the user interface, inspired by Google's Material Design⁠. Some icons have been obtained from Material Design Icons⁠, packaged for Material-UI by mdi-material.ui⁠.
• Fuse.js⁠ as a full-text search engine.
• react-markdown⁠ is used to render the program descriptions in rich-text.
• sw-precache⁠ builds a costumized Service Worker⁠, allowing also the use of the application when the device is off-line. This component will be replaced soon by Workbox⁠.
• Font Face Observer⁠ is used to dynamically load the Open Sans⁠ font.
• json2csv⁠ exports spreadsheets of data in CSV format.
• react-ga⁠ React module for Google Analytics.

Keep in mind that these components use hundreds of other open source projects to make the final application possible.

⁠Building the app

⁠Prerequisites

• NodeJS⁠ is needed to build the main application. Linux users are advised to use the official LTS repositories⁠.

⁠Setting up

First of all, the NPM⁠ components must be loaded:

# Go to the main project directory:
$ cd path/to/mapa-innovacio-edu

# Install the required npm components:
$ npm ci

⁠Basic configuration

The application has different settings that can be adjusted. Many of these adjustements should be set on a file named .env, not included on the repository files. In order to generate your own .env file, just duplicate .env.example:

# Make a copy of .env.example
cp .env.example .env

⁠Choosing the type of router

You can choose between two different types of React Router⁠:

⁠HashRouter

HashRouter⁠ uses the "hash⁠" part of URLs to identify the specific contents to be displayed on each page. In order to use this type of router set REACT_APP_HASH_TYPE to one of this values: "slash" (#/), "noslash" (#) or "hashbang" (#!/) in .env:

# File .env (or .env.production)
# hashType param passed to HashRouter
REACT_APP_HASH_TYPE="hashbang"

⁠BrowserRouter

BrowserRouter⁠ can also use the "pathname⁠" part of URLs. In order to use this type of router, set REACT_APP_HASH_TYPE to no-hash in .env:

# File .env (or .env.production)
# hashType param passed to HashRouter
REACT_APP_HASH_TYPE="no-hash"

• Configure your web server to redirect all paths to index.html, except those that point to real files or directories.

  • With Apache HTTP server⁠ you must enable mod_rewrite⁠ and configure your virtual host. If you have AllowOverride All set, the .htaccess file provided in /public will be used:

Options -MultiViews
RewriteEngine On
RewriteCond %{REQUEST_FILENAME} !-f
RewriteCond %{REQUEST_FILENAME} !-l
RewriteCond %{REQUEST_FILENAME} !-d
RewriteRule ^ index.html [QSA,L]

• With NGINX⁠, you must configure your virtual host with a directive like this one:

location / {  
  try_files $uri $uri/ /index.html;
}

Note: If you are using Devilbox⁠ for development, take a look at the file /.devilbox/nginx.yml.

⁠Setting up the root directory

By default, the application is configured to be served at the root (/) of your HTTP server. Before deploying it on a different directory, the homepage value of package.json should be modified. This value should be "" for the root, or any absolute path starting (and not ending) with "/" for other locations. For example, this setting will make the final application run on https://myhost.mydomain.com/mymap/:

   "homepage": "/mymap"

⁠Common operations

From here, the most usual operations are:

⁠Launch the development server:

$ cd path/to/mapa-innovacio-edu
$ npm start

Runs the app in the development mode.
Open http://localhost:3000⁠ to view it in the browser.

The page will reload if you make edits.
You will also see any lint errors in the console.

⁠Build the main application:

$ cd path/to/mapa-innovacio-edu
$ npm run build

Builds the app for production to the build folder.
It correctly bundles React in production mode and optimizes the build for the best performance.

The build is minified and the filenames include the hashes.
Your app is ready to be deployed!

See the section about deployment⁠ for more information.

For more information about this and other available scripts check the Create React App⁠ site.

⁠Deploying with Docker

You can choose to build your own image from source code, or download a pre-built image from DockerHub⁠.

To build and launch your own docker image on port 8000:

$ cd /path/to/mapa/innovacio
$ docker build . -t mapa-innovacio
$ docker run -d -p 8000:80 --name mapa-innovacio mapa-innovacio

To use the pre-built docker image just launch:

$ docker run -d -p 8000:80 --name mapa-innovacio projectestac/mapa-innovacio

In both cases the app will be available at: http://localhost:8000/⁠ (of course, you can choose any other port!)

⁠License

"Map of pedagogical innovation in Catalonia" is an open source development made by the Department of Education of the Government of Catalonia, released under the terms of the European Union Public Licence v. 1.2⁠.