Eventyay Exhibition
===================

Eventyay Exhibition is a plugin for `eventyay`_ that adds exhibitor,
sponsor, exhibition booth, proposal, and lead-scanning features to events.

The plugin allows organizers to manage exhibitors and sponsors, publish
public exhibitor pages, collect exhibitor and sponsor applications, configure
custom application questions, and provide exhibitors with access to lead
scanning functionality.

Features
--------

- Manage event exhibitors, sponsors, partners, booths, and sponsor groups.
- Add exhibitor profiles with descriptions, website links, contact links,
  videos, logos, header images, and promotional PDF slides.
- Mark organizations as exhibitors, sponsors, both, or partners that are not
  exhibitors.
- Configure sponsor groups and show selected sponsor groups on the event front
  page.
- Publish public exhibitor lists and exhibitor detail pages for an event.
- Enable a public call for exhibitor and sponsor applications.
- Configure proposal fields and custom application questions.
- Review exhibitor and sponsor proposals with states such as submitted,
  accepted, rejected, withdrawn, and draft.
- Generate exhibitor access keys.
- Enable exhibitor lead scanning and retrieve scanned lead data.
- Support notes and tags for scanned leads.
- Provide REST API endpoints for exhibitor data and lead scanning workflows.

Image dimensions
----------------

The public detail page shows an exhibitor's header image (banner) complete,
never cropped. Its hero reserves this box:

============  ==================
Property      Value
============  ==================
Aspect ratio  3:1 (wide)
Recommended   1500 x 500 pixels
============  ==================

An image that does not match 3:1 is neither rejected nor cropped on the detail
page. It is scaled to fit inside the box and centred, with the surrounding area
filled by a plain background, so the layout stays intact whatever is uploaded.

List cards are a thumbnail of the banner rather than a second copy of it, so
they keep filling their box and crop to do so. Upload at 3:1 and both surfaces
show the same picture.

The ratio is defined once, as the ``--exhibition-banner-ratio`` CSS custom
property in
``exhibition/static/exhibition/css/exhibitors-public-detail.css``.

Repository branches
-------------------

The repository uses two main branches:

- ``dev``: active development branch and default branch.
- ``main``: stable branch for reviewed changes.

Contributors should normally create pull requests against ``dev`` unless a
maintainer requests a different target branch.

Development setup
-----------------

1. Make sure that you have a working `eventyay development setup`_.

2. Clone this repository, e.g., to ``local/eventyay-exhibition``::

       git clone https://github.com/fossasia/eventyay-exhibition.git local/eventyay-exhibition
       cd local/eventyay-exhibition

3. Check out the development branch::

       git checkout dev

4. Activate the `virtual environment <https://github.com/fossasia/eventyay?tab=readme-ov-file#getting-started>`_ you use for eventyay development.

5. Execute ``uv pip install -e .`` within this directory to register this application with the eventyay plugin registry::

       uv pip install -e .

6. Execute ``make`` within this directory to compile translations::

       make

7. Restart your local eventyay server. You can now use the plugin from this repository for your events by enabling it in
   the ``plugins`` tab in the settings.

Python version
--------------

The plugin currently targets Python 3.12.

Useful commands
---------------

Install the plugin locally::

    uv pip install -e .

Install test dependencies::

    uv pip install -e ".[test]"

Compile translations::

    make

Generate translation files::

    make localegen

Run tests::

    pytest

Run formatting and lint checks::

    ruff format --check .
    ruff check .

Auto-fix formatting and lint issues where possible::

    ruff format .
    ruff check --fix .

Code style
----------

The repository uses Ruff for formatting, import sorting, and linting. Run Ruff
and the test suite before opening a pull request.

To install the local commit hooks, install `pre-commit`_ and run::

    pre-commit install

Project structure
-----------------

Important files and directories:

- ``exhibition/models.py``: exhibitor, sponsor, proposal, question, lead, and
  tag models.
- ``exhibition/forms.py``: organizer-facing and public application forms.
- ``exhibition/views.py``: organizer and public web views.
- ``exhibition/api.py``: REST API serializers and lead scanning endpoints.
- ``exhibition/urls.py``: public, organizer, and API routes.
- ``exhibition/templates/``: HTML templates for exhibitor pages, settings,
  proposals, and public call pages.
- ``exhibition/static/``: JavaScript and static assets.
- ``tests/``: test suite.

Public routes
-------------

The plugin provides public event routes for:

- exhibitor list pages
- exhibitor detail pages
- public exhibition calls
- proposal submission and proposal editing by applicants

Organizer routes
----------------

Organizers can manage:

- exhibitor and sponsor entries
- sponsor groups
- exhibition settings
- public call settings
- proposal review
- custom application questions

API endpoints
-------------

The plugin exposes API endpoints for:

- exhibitor authentication by access key
- exhibitor data
- lead creation
- lead retrieval
- lead updates
- exhibitor lead tags

These endpoints are intended for integration with exhibitor-facing tools such
as lead scanning applications.

Contributing
------------

- Use ``dev`` as the base branch for regular development pull requests.
- Keep pull requests focused and small enough to review.
- Include screenshots or screencasts for user interface changes.
- Add or update tests for behavior changes.
- Run Ruff checks and tests before opening a pull request.
- Avoid unrelated cleanups in feature or bug-fix pull requests.

License
-------

Copyright 2024 FOSSASIA

Released under the terms of the Apache License 2.0.

.. _eventyay: https://github.com/fossasia/eventyay
.. _eventyay development setup: https://github.com/fossasia/eventyay?tab=readme-ov-file#getting-started
.. _pre-commit: https://pre-commit.com/