Customization ============= When the different configuration options are insufficient for your needs, you can customize the sharpie code. We advise to first create a fork of the latest stable release of SHARPIE, see SHARPIE tags on GitHub. Next, follow the regular installation steps and make sure to install in editable mode using ``pip install -e .`` in the SHARPIE directory. You can run the sharpie webserver and runner as usual, any changes you make to the SHARPIE source files you installed will be reflected when using the standard SHARPIE commands. UI elements and Templates ------------------------- Most of the UI elements and templates are located in one of the apps (directories) in the ``sharpie/webserver`` directory: | UI elements and templates are located in ``sharpie/webserver/server`` and ``sharpie/webserver/experiment``, with the exception of the home page which is in ``home/``. | To add custom interaction elements such as buttons, inputs, images, etc., change the files in the ``templates/`` and ``static/`` directories for these apps. +++++++++ Templates +++++++++ We here give an overview of the role of different templates that you may want to choose for customization, all located in ``sharpie/webserver/``: * ``server/templates/base.html`` the root template, containing the root ```` tags and the menu of all pages. * ``home/templates/home/index.html`` the landing page that by default gives an overview of all installed experiments. * ``experiment/templates/experiment/config.html`` participant-facing experiment configuration page, with room name and agent role selection * ``experiment/templates/experiment/run.html`` template for experiment, including interaction instructions, history etc. Here you can add custom input elements, additional interaction information, custom history etc. +++++++ Styling +++++++ | SHARPIE uses the well-established `Bootstrap CSS `_ framework. | Some custom styling is additionally defined in ``sharpie/webserver/server/templates/base.html``, and in ``sharpie/webserver/experiment/static/experiment/css/control.css``. Interaction ----------- In case you want to change the interaction, you will need to add the required UI elements to the template first and ensure the styling is as you want it. Additionally, you will want to implement some logic for capturing and processing the inputs for proper interactions. The javascript files for this are located in * ``sharpie/webserver/server/experiment/static/experiment/js/mobileControls.js`` * ``sharpie/webserver/server/experiment/static/experiment/js/inputListener.js`` If you want to send different kind of information between the front end, i.e. participant-facing web UI, and the back-end, i.e. the webserver and the runner, read on. Communication ------------- To change which/how information is sent between the web UI, the webserver and the runner, have a look at the following files in ``sharpie/webserver/server/experiment``: * ``static/experiment/js/websocket.js`` implements the front-end experiment websocket logic. In particular have a look at ``websocket.onmessage`` which handles how messages from the web server are processed in the front-end. * ``websocket.py`` implements back-end experiment websocket logic. In particular, have a look at ``_handle_action`` for the processing of participant input and ``_handle_broadcast`` for handling of a a new ``step()`` from the runner. Finally, have a look at ``sharpie/runner/manage.py`` for logic on the runner-side.