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.
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.
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.
The main place customisations go is the src/config.json
file. Settings currently available include:
BASE_PATH
: The path to ConClár within your webserver. Set to '/' to run in the root directory. See below for running in a subdirectory.APP_ID
: A unique id to distinguish between instances of multi-year conventions.APP_TITLE
: The title to appear at the top of the webpage, and in the browser window title.PROGRAM_DATA_URL
: The address of the file containing programme data.PEOPLE_DATA_URL
: The address of the file listing people. If these are the same, both will be read from one file, but programme data must come before people data.FETCH_OPTIONS
: A JSON object containing options to pass when fetching data. See JavaScript fetch() documentation for available valies. Typical examples:
"cache": "reload"
- Should always be used so beck end program updates will be read."credentials": "omit"
- Use if source is not using a certificate from a recognised authority, e.g. a self signed cert."headers": { "Origin": "http://example.com" }
- Headers sent in the fetch. Origin may be required for Cross Origin Resource Sharing (CORS).TIMEZONE
: The name of the timezone where your convention takes place. Viewers outside convention timezone will see times in convention time, and their local time below it.TIMEZONE_CODE
: The short code for the convention timezone. Set to blank to get browser code for timezone (not recommended, as it may not select the most elegant short code).INTERACTIVE
: Set to false
to get a non-interactive, expanded view of the schedule. The info page is also included, but not the participant list, individual participant pages, or individual item pages (regardless of the PERMALINK.SHOW_PERMALINK
setting).HEADER
: Add an optional image to the header of the pages.HEADER.IMG_SRC
: Set to the image filename to display. May be a file in the public directory. Leave blank for no image.HEADER.IMG_ALT_TEXT
: Set to the alt text that should display for the image.HEADER.LINEFEED_AFTER_URL
: If true, place a line feed after the image.NAVIGATION
: Each value in this section sets the label that will appear on main navigation of the site. Useful for switching between different international spellings of "programme".NAVIGATION.PROGRAM
: Label for program/programme menu.NAVIGATION.PEOPLE
: Label for people menu.NAVIGATION.MYSCHEDULE
: Label for user's personal schedule.NAVIGATION.INFO
: Label for the Information menu link._NAVIGATION.EXTRA
: An array of extra menu links. Each entry should take the form: { "LABEL": "Octocon Home", "URL": "https://octocon.com" }
. To have no extra links, set to "EXTRA": []
or delete EXTRA
entry altogether.HELP_TEXT.WELCOME
: Text to display to new visitors who haven't selected any programme items.HELP_TEXT.SHARING
: Text to display when user has selected items, informing them of sharing options.HELP_TEXT.CLOSE_LABEL
: Label for button to dismiss help text.HELP_TEXT.CLOSE_ARIA_LABEL
: Label to describe dismiss button.LOCATIONS.SEARCHABLE
: Whether the location list can be searched by typing. (Searching can be inconvenient on touch screens.)APPLICATION.LOADING.MESSAGE
: Message to display while loading.PROGRAM.LIMIT.SHOW
: If true, "limit number of items" drop-down will be displayed.PROGRAM.LIMIT.LABEL
: Label for limit drop-down.PROGRAM.LIMIT.OPTIONS
: Options for limit drop-down - should be an array of integers.PROGRAM.LIMIT.ALL_LABEL
: Label to show for "All" entry.PROGRAM.LIMIT.DEFAULT
: Default for limit drop-down.PROGRAM.LIMIT.SHOW_MORE.LABEL
: Label for the "Show more" button.PROGRAM.LIMIT.SHOW_MORE.NO_MORE
: Message to display when no more items available.PROGRAM.LIMIT.SHOW_MORE.NUM_EXTRA
: Number of items to add when "Show more" pressed.PROGRAM.MY_SCHEDULE.TITLE
: Title of My Schedule page.PROGRAM.MY_SCHEDULE.EMPTY.TEXT
: Text to display on My Schedule when no programme items selected.PROGRAM.MY_SCHEDULE.INTRO
: Introduction text for My Schedule page.PROGRAM.MY_SCHEDULE.SEARCH.SEARCH_LABEL
: Label for search box.PROGRAM.MY_SCHEDULE.SHARE.LABEL
: Heading for shared link section on MySchedule.PROGRAM.MY_SCHEDULE.SHARE.DESCRIPTION
: Descriptive message for link sharing section.PROGRAM.MY_SCHEDULE.SHARE.LINK_LABEL
: Label for link when single sharing link on page.PROGRAM.MY_SCHEDULE.SHARE.MAX_LENGTH
: Maximum number of characters in each link.PROGRAM.MY_SCHEDULE.SHARE.MULTIPLE_DESCRIPTION
: Description to display when multiple links displayed.PROGRAM.MY_SCHEDULE.SHARE.MULTIPLE_LINK_LABEL
: Label for link when multiple links shown. @number replaced by number of link.PROGRAM.SHARED.TITLE
: Title of Shared Programme Items page.PROGRAM.SHARED.DESCRIPTION
: Descriptive text for page showing shared links.PROGRAM.SHARED.BUTTON_LABEL
: Text for label of "Add all to My Schedule" button.TAGS.PLACEHOLDER
: The placeholder when selecting tags (unless separated).TAGS.SEARCHABLE
: Whether the tag list can be searched by typing (unless separated).TAGS.HIDE
: If true, hide the tags drop-down. Tags still displayed on items.TAGS.SEPARATE
: An array of tag prefixes to separate into individual drop-downs, and if drop-down is searchable or hidden. Tags should be specified as follows: { "PREFIX": "type", "PLACEHOLDER": "Select type", "SEARCHABLE": true|false, "HIDE": true|false }
.TAGS.FORMAT_AS_TAG
: If set to true, turns Grenadine item format into a KonOpas-style "type" tag.TAGS.DAY_TAG.GENERATE
: If set to true, will generate tags for each day of the convention.TAGS.DAY_TAG.DAYS
: Object with key values pairs for day names. Keys are day numbers from 1 (Monday) to 7 (Sunday).TAGS.DAY_TAG.PLACEHOLDER
: The placeholder for the "day" tags drop down.TAGS.DAY_TAG.SEARCHABLE
: Whether day tag list can be searched by typing.TAGS.DAY_TAG.HIDE
: If true, hide day tags drop-down. Day tags still shown on items if GENERATE true.TAGS.DONTLIST
: An array of tags not to list in the drop-downs and programme item tag lists.HIDE_BEFORE.HIDE
: If true hide "hide before" dropdown. If false, show dropdown containing times to hide items before.HIDE_BEFORE.PLACEHOLDER
: Placeholder text for hide before drop-down.HIDE_BEFORE.TIMES
: Array of times to list in hide before drop-down. Each entry should be specified as follows: { "TIME": "time in hh:mm:ss format", "LABEL_24H": "24 hour label", "LABEL_12H": "12 hour label" }. Time should be in convention timezone.FILTER.RESET.LABEL
: The label for the "Reset filters" button.PERMALINK.SHOW_PERMALINK
: If true, display a "permalink" icon when each program item is expanded.PERMALINK.PERMALINK_TITLE
: "Title" text displayed when mouse is hovered over permalink icon.EXPAND.EXPAND_ALL_LABEL
: Label text for Expand All button.EXPAND.COLLAPSE_ALL_LABEL
: Label for Collapse All button.EXPAND.SPRING_CONFIG
: Config to apply to the configuration of the 'spring' when expanding items. This may be a simply duration, such as { "duration": 100 }
to expand in 100ms, or can configure more dynamic spring effects, such as { mass: 1, tension: 1000, friction: 30 }
. Full list of options in react-spring documentation.ITEM_DESCRIPTION.PURIFY_OPTIONS
: Pass additional options to DOMPurify when processing item descriptions. For the available options, see the DOMPurify documentation. Format options as JSON, e.g., {"FORBID_ATTR": ["style"]}
.LINKS
: An array of link types expected in the program data. Individual entries should take the form {"NAME": "signup", "TEXT": "Click to sign up", "TAG": ""}
. NAME
should be the name of the link as it appears in the links object in the program data. TEXT
is the text that should appear on this link in ConClár. TAG
is an optional tag to add to every program item which includes a matching link. If using prefixed tags, include the prefix, e.g., "type:Workshop"
.LOCAL_TIME.CHECKBOX_LABEL
: Label for the "Show Local Time" checkbox.LOCAL_TIME.NOTICE
: Label for notie telling users how local time displayed.LOCAL_TIME.PREV_DAY
: Label appended to local time if local time is before start of advertised day.LOCAL_TIME.NEXT_DAY
: Label appended to local time if local time is after end of advertised day.LOCAL_TIME.FAILURE
: Local time depends on string conversions, and could fail in some circumstances. Display this message if unable to convert.TIME_FORMAT.DEFAULT_12HR
: Set to true if you want time displayed in 12 hour format by default.TIME_FORMAT.SHOW_CHECKBOX
: If set to false, users will not be given option to change between 12 and 24 hour time.TIME_FORMAT.CHECKBOX_LABEL
: Label for the 12 hour time checkbox label.TIME_FORMAT.AM
: Label for AM times.TIME_FORMAT.PM
: Label for PM times.DURATION.SHOW_DURATION
: If true, mins
from program data will be displayed.DURATION.DURATION_LABEL
: Format for duration. @mins
will be replaced by number of minutes. Note: do not translate @mins
.SHOW_PAST_ITEMS.SHOW_CHECKBOX
: Set to true to show the option during the convention; otherwise past programme items are shown by default.SHOW_PAST_ITEMS.CHECKBOX_LABEL
: Label for the show past items checkbox.SHOW_PAST_ITEMS.ADJUST_MINUTES
: Some wiggle room (in minutes) in order not to hide past items immediately as they start.PEOPLE.THUMBNAILS.SHOW_THUMBNAILS
: Set to false to not show member thumbnails (useful to remove spurious controls if pictures not in file).PEOPLE.THUMBNAILS.SHOW_CHECKBOX
: Set to false to hide "Show thumbnails" checkbox.PEOPLE.THUMBNAILS.CHECKBOX_LABEL
: Label for "Show thumbnails" checkbox.PEOPLE.THUMBNAILS.DEFAULT_IMAGE
: Set to default thumbnail for participants with no photo. Can be filename of image in public directory, or external URL. Leave blank for no default thumbnail.PEOPLE.SORT.SHOW_CHECKBOX
: Set to false to hide "Sort by full name" checkbox. Useful if your data only contains "name for publications".PEOPLE.SORT.CHECKBOX_LABEL
: Label for "Sort by full name" checkbox.PEOPLE.TAGS.PLACEHOLDER
: The placeholder when selecting person tags (unless separated).PEOPLE.TAGS.SEARCHABLE
: Whether the tag list can be searched by typing (unless separated).PEOPLE.TAGS.HIDE
: If true, hide the tags drop-down. Tags still displayed on items.PEOPLE.TAGS.SEPARATE
: An array of tag prefixes to separate into individual drop-downs, and if drop-down is searchable or hidden. Tags should be specified as follows: { "PREFIX": "type", "PLACEHOLDER": "Select type", "SEARCHABLE": true|false, "HIDE": true|false }
.PEOPLE.SEARCH.SHOW_SEARCH
: Set to false to hide "people" search box.PEOPLE.SEARCH.SEARCH_LABEL
: Label for "people2 search box.PEOPLE.BIO.PURIFY_OPTIONS
: Pass additional options to DOMPurify when processing participant bios. For more details, see ITEM_DESCRIPTION.PURIFY_OPTIONS
above.USELESS_CHECKBOX.CHECKBOX_LABEL
: Label for any useless checkboxes.SETTINGS.TITLE.LABEL
: Label for settings page.SETTINGS.TIME_FORMAT.LABEL
: Label for time format group.SETTINGS.TIME_FORMAT.T12_HOUR_LABEL
: Label for 12 hour option.SETTINGS.TIME_FORMAT.T24_HOUR_LABEL
: Label for 24 hour option.SETTINGS.SHOW_LOCAL_TIME.LABEL
: Label for Show Local Time option group.SETTINGS.SHOW_LOCAL_TIME.NEVER_LABEL
: Label for "Never show" option.SETTINGS.SHOW_LOCAL_TIME.DIFFERS_LABEL
: Label for "Display if different from Convention timezone".SETTINGS.SHOW_LOCAL_TIME.ALWAYS_LABEL
: Label for "Always display" option.SETTINGS.SHOW_TIMEZONE.LABEL
: Label for Show timezone after times option group.SETTINGS.SHOW_TIMEZONE.NEVER_LABEL
: Label for "Never show" option.SETTINGS.SHOW_TIMEZONE.IF_LOCAL_LABEL
: Label for "Show timezone if local time shown".SETTINGS.SHOW_TIMEZONE.ALWAYS_LABEL
: Label for "Always show" option.SETTINGS.SELECT_TIMEZONE.LABEL
: Label for select timezone group,SETTINGS.SELECT_TIMEZONE.BROWSER_DEFAULT_LABEL
: Label to use browser default timezone (will have name of timezone appended).SETTINGS.SELECT_TIMEZONE.SELECT_LABEL
: Label to select explicit timezone.SETTINGS.DARK_MODE.LABEL
: Label for dark mode settings group.SETTINGS.DARK_MODE.BROWSER_DEFAULT_LABEL
: Label for default browser dark mode preference.SETTINGS.DARK_MODE.BROWSER_LIGHT_LABEL
: Label to indicate browser is currently in light mode.SETTINGS.DARK_MODE.BROWSER_DARK_LABEL
: Label to indicate browser is currently in dark mode.SETTINGS.DARK_MODE.LIGHT_MODE_LABEL
: Label for forcing light mode.SETTINGS.DARK_MODE.DARK_MODE_LABEL
: Label for forcing dark mode.INFORMATION.MARKDOWN_URL
: The address of the markdown file containing additional information about the convention.INFORMATION.LOADING_MESSAGE
: Text to show while Markdown file is loading (usually never seen).FOOTER.SITE_NOTE_MARKDOWN
: General note displayed in the footer of the page. May use Markdown for encoding of links, emphesis, etc.FOOTER.CONCLAR_NOTE_MARKDOWN
: Note crediting ConClár. You are free to remove or modify this, but we politely request retaining to help promote this free tool.TIMER.FETCH_INTERVAL_MINS
: Number of minutes between refreshes of program data.TIMER.TIMER_TICK_SECS
: Number of seconds between checks of timer.DEBUG_MODE.ENABLE
: If true, display banner showing online status, and allowing manual data fetch.DEBUG_MODE.ONLINE_LABEL
: Label to display in debug mode when online.DEBUG_MODE.OFFLINE_LABEL
: Label to display in debug mode when offline.DEBUG_MODE.FETCH_BUTTON_LABEL
: Label to display in debug mode on Fetch button.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
.
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.
If you need to put ConClár in a subdirectory on your webserver, you'll need to carry out the following additional steps:
BASE_PATH
setting in your config.json
file. To put in a directory called "guide", set BASE_PATH
to "/guide/".package.json
file and add a homepage
setting as shown below.index.html
in the subdirectory.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",
...
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>
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;
}
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.
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.