search

lostcarpark / conclar

ConClár Programme Guide in ReactJS
MIT License
11 stars 12 forks source link

readme

ConClár

ConClár is an online Program Guide tool for conventions.

It has been developed in ReactJS and is intended to work in all modern browsers (sorry, it probably won't work in Internet Explorer). It is designed to work equally well on mobile and desktop devices.

ConClár is inspired by Eemeli Aro's KonOpas. As this uses a number of unsupported libraries, it was developed as a completely new application, rather than trying to patch up the old code.

ConClár can be hosted on most webservers, and has been tested on Apache and Nginx. Some changes are required if your guide is not in the root directory of the website (see below). The programme data is read from JSON files, and is compatible with KonOpas files. There are several programme planning tools that should be compatible, though so far it has only been tested with Zambia.

Getting Started

ConClár requires npm to install its dependencies. This is part of Node.js, so start by going to the Node.js download page. Grab the latest installer for your operating system, and install it. You should do this on your local computer, not your webserver.

Next create a local directory for your ConClár project. You can put this anywhere in your filesystem.

Next you need to get the code from GitHub. You can either use the download link to get a Zip file, or clone the project with the git command. If you are customising for your convention, you should consider creating a fork so that you can merge in future changes.

ConClár requires a configuration file called in the /src/ directory called config.json. To avoid local customizations getting pushed to the main repository, this not included. Instead, there is a sample config file that is a good starting point. You should copy this to the correct name. If you have a fork of the project, you may want to remove /src/config.json from .gitignore, to track your convention's customizations. You can copy the example with the following command:

cp src/config_example.json src/config.json

Once you've done that, run the following from a command prompt in the directory you created above:

npm install

This will install everything needed to run the project.

Available Scripts

In the project directory, you can run:

npm start

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

The page will reload when you make changes.\ You may also see any lint errors in the console.

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 React app deployment for more information.

Customisation

The main place customisations go is the src/config.json file. Settings currently available include:

More settings will be added to this file in future versions.

To customise the site heading, edit the src/components/Header.js file.

The convention information page is composed in Markdown using the provided file, public/info.md. Markdown is a common standard for formatting text that is easy to follow and safer than HTML. There is a handy cheat sheet.

To change the styling, edit src/App.css. Note that the current styling is temporary, and a better default theme with easier customisation is planned.

To change the home screen app name, edit public/manifest.json.

Hosting

ConClár is fairly simple to host on most webservers. However it does require that all requests get directed to index.html. Instruction for this on Apache and Nginx are included below.

After running npm run build just copy the build directory to the public directory of your webserver.

Hosting in a subdirectory

If you need to put ConClár in a subdirectory on your webserver, you'll need to carry out the following additional steps:

  1. Edit the BASE_PATH setting in your config.json file. To put in a directory called "guide", set BASE_PATH to "/guide/".
  2. Edit the package.json file and add a homepage setting as shown below.
  3. Set appropriate settings for the webserver to find the index.html in the subdirectory.
  4. Use npm run build to prepare the application to upload.

The package.json file should start as follows:

  {
    "name": "conclar",
    "version": "0.1.0",
    "private": true,
    "homepage": "/guide",
  ...

Hosting on Apache

On Apache, the easiest way to direct traffic to index.html is by way of a .htaccess file. A default .htaccess is included in the public directory. This will get copied to the build directory, but may get hidden when you copy to your webserver. The contents are as follows:

<IfModule mod_rewrite.c>
    RewriteEngine On
    RewriteBase /
    RewriteCond %{REQUEST_FILENAME} !-f
    RewriteCond %{REQUEST_FILENAME} !-d
    RewriteCond %{REQUEST_FILENAME} !-l
    RewriteRule . /index.html [L]
</IfModule>

If you are hosting in a subdirectory, modify .htaccess as follows (replace "guide" with the folder you are hosting in):

<IfModule mod_rewrite.c>
    RewriteEngine On
    RewriteBase /guide/
    RewriteCond %{REQUEST_FILENAME} !-f
    RewriteCond %{REQUEST_FILENAME} !-d
    RewriteCond %{REQUEST_FILENAME} !-l
    RewriteRule . /guide/index.html [L]
</IfModule>

Hosting on Nginx

On Nginx, the following needs to go in your .conf file:

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

For hosting in a subdirectory, this should be altered as follows:

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

File Format

The ConClár file format is designed to be compatible with KonOpas, and in most cases data files for KonOpas can be used without modification.

Full details of the file format are in a separate Data Structure document.

Credits

ConClár is Copyright James Shields, 2022, and made available as an open source project under the MIT licence.

Thanks to:

The included "rainbow head" thumbnail image is a public domain image available on Open Clipart.