This project provides a base Flask application and base Docker image for arXiv-NG services.

Each component of this project must meet all of the following criteria:

1. It is likely that the component will be utilized in many or all arXiv services.
2. Once stable, it is unlikely to change often.
3. It is unlikely that implementing new features in specific services would require changes to the component.
4. When a component does change, it must change in the same way for all of the services that use it.

Templates are written in Jinja2 syntax. CSS framework is Bulma with arXiv-specific overrides for color and typography. While the .sass format has been used for override files, .scss files may also be imported and included.

These files set the default display styles and layout for all pages on arxiv-NG, and can be overridden as needed by submodules.

TODO: Add autoprefixer in postcss and autocompile sass/scss

A template is included for rapid evaluation of display layer CSS within this repo, prepopulated with sample content. The styleguide.html template (route: /styleguide) shows error message samples, informational message boxes, and sample content from search.

This project includes a minimal Flask application for development verification/testing purposes. To run the dev server (assuming that you are working in the root of this repository):

$ FLASK_APP=app.py FLASK_DEBUG=1 pipenv run flask run

You should be able to view the rendered styleguide.html at http://127.0.0.1:5000/styleguide.

To use the base UI package in a Flask application add it to your Pipfile. To use a specific version, for example, you would write:

arxiv-base = "==0.11.1rc5"

Or if you want to install a specific working branch (dev only) the Pipfile line might read:

arxiv-base = {git = "https://github.com/arXiv/arxiv-base.git@task/ARXIVNG-1215"}

See the pip documentation for details.

You can use pipenv from the command line to install a selected unpublished branch. First uninstall existing, then reinstall using pip syntax above. Example:

pipenv uninstall arxiv-base
pipenv install git+https://github.com/arXiv/arxiv-base.git@task/ARXIVNG-1010#egg=arxiv-base

In your application factory, instantiate the Base component. This makes templates and static files available to you. For example, in your factory.py module:

from flask import Flask
from arxiv.base import Base
from someapp import routes


def create_web_app() -> Flask:
   app = Flask('someapp')
   app.config.from_pyfile('config.py')

   Base(app)   # Registers the base/UI blueprint.
   app.register_blueprint(routes.blueprint)    # Your blueprint.
return app

You can now extend base templates, e.g.:

{%- extends "base/base.html" %}

{% block content %}
Hello world!
{% endblock %}

And use static files in your templates, e.g.:

{{ url_for('base.static', filename='images/CUL-reduced-white-SMALL.svg') }}

In order to serve static assets for multiple versions of the an app at the same time, arxiv-base prefixes the app name and app version to asset urls. This is to allow gracefully upgrades with no broken links to css, js or images.

The Base component will automatically set your app's static_url_path using the name of the app and the value of APP VERSION in your config to /static/[app name]/[ app version ]. It will also rewrite blueprint static_url_path to /static/[app name]/[ app version ]/[ blueprint name].

TODO Add actual step by step instructions on how to deploy static assets to S3

We use Flask-S3 to serve static files via S3. Given the URL strategy above, following the instructions for Flask-S3 should just work.

Be sure to initialize the integration after instantiating Base and registering your blueprints. For example:

def create_web_app() -> Flask:
    """Initialize and configure the application."""

    app = Flask('coolapp')
    app.config.from_object(config)
    Base(app)    # Gives us access to the base UI templates and resources.
    app.register_blueprint(routes.blueprint)
    s3.init_app(app)    # <- Down here!
    return app

Some tests to check app configuration and pattern compliance are provided in arxiv.base.app_tests. See that module for usage.

TODO: compile sass at app start up, stop checking compiled artifacts into to git.

The file arxivstyle.css should never be edited directly. It is compiled from arxivstyle.sass with this command from project directory root: sass arxiv/base/static/sass/arxivstyle.sass:arxiv/base/static/css/arxivstyle.css

or you can use the --watch option to autocompile on any changed file:

sass --watch arxiv/base/static/sass/arxivstyle.sass:arxiv/base/static/css/arxivstyle.css

Bulma source files are included in the static/sass directory so that variables can be overridden directly during compile. The arxivstyle.sass file has been written to do this; do not edit it.

Documentation for sass

Adding class="beta" to the main content div will create a beta watermark at the top left of pages having this class.