Frontend Improvements

.gitignore

@@ -33,6 +33,7 @@ MANIFEST
 # Static files
 polaris/polaris/collectstatic/*
 !polaris/polaris/collectstatic/__init__.py
+polaris/polaris/static/base.css
 
 # PyInstaller
 #  Usually these files are written by a python script from a template

Pipfile

@@ -29,6 +29,9 @@ django-cors-headers = "*"
 toml = "*"
 pyjwt = "*"
 django-sslserver = "*"
+libsass = "*"
+django-compressor = "*"
+django-sass-processor = "*"
 
 [requires]
 python_version = "3.7"

README.rst

@@ -35,34 +35,41 @@ Installation and Configuration
 ==============================
 
 .. _CLI tool: https://github.com/msfeldstein/create-stellar-token
+.. _Static Files: https://docs.djangoproject.com/en/2.2/howto/static-files/
 
 First make sure you have ``cd``'ed into your django project's main directory
 and then run
 ::
 
     pip install django-polaris
 
-Add it to ``INSTALLED_APPS`` in settings.py
+Configuring settings.py
+^^^^^^^^^^^^^^^^^^^^^^^
+
+Add the following to ``INSTALLED_APPS`` in settings.py. Any app that overrides
+a static asset in Polaris should be listed `before` "polaris". This ensures that
+django will find your asset before the Polaris default.
 ::
 
     INSTALLED_APPS = [
         ...,
+        "django.contrib.staticfiles",
+        "corsheaders",
+        "rest_framework",
+        "sass_processor",
         "polaris",
     ]
 
-Add Polaris' ``PolarisSameSiteMiddleware`` to your
-``settings.MIDDLEWARE``. Make sure its listed `above` ``SessionMiddleware``.
+Add Polaris' ``PolarisSameSiteMiddleware`` and ``CorsMiddleware`` to your
+``settings.MIDDLEWARE``. The former must be listed `above` ``SessionMiddleware``.
 ::
 
     MIDDLEWARE = [
-        'django.middleware.security.SecurityMiddleware',
+        ...,
         'polaris.middleware.PolarisSameSiteMiddleware',
         'django.contrib.sessions.middleware.SessionMiddleware',
-        'django.middleware.common.CommonMiddleware',
-        'django.middleware.csrf.CsrfViewMiddleware',
-        'django.contrib.auth.middleware.AuthenticationMiddleware',
-        'django.contrib.messages.middleware.MessageMiddleware',
-        'django.middleware.clickjacking.XFrameOptionsMiddleware',
+        'corsheaders.middleware.CorsMiddleware',
+        ...
     ]
 
 
@@ -72,15 +79,38 @@ find your ``.env`` file.
 
     PROJECT_ROOT = os.path.dirname(os.path.dirname(os.path.abspath(__file__)))
 
-Paste the text below into ``PROJECT_ROOT/.env``.
+Add the following to your settings.py as well:
+::
+
+    FORM_RENDERER = "django.forms.renderers.TemplatesSetting"
+    STATIC_ROOT = os.path.join(BASE_DIR, "<your static root directory>")
+    STATIC_URL = "<your static url path>"
+    STATICFILES_STORAGE = "whitenoise.storage.CompressedManifestStaticFilesStorage"
+    STATICFILES_FINDERS = [
+        "django.contrib.staticfiles.finders.FileSystemFinder",
+        "django.contrib.staticfiles.finders.AppDirectoriesFinder",
+        "sass_processor.finders.CssFinder",
+    ]
+    SASS_PROCESSOR_ROOT = STATIC_ROOT
+    DEFAULT_PAGE_SIZE = <your default page size>
+
+This allows Polaris to override django's default HTML widgets to provide
+a great UI out of the box. See the `Static Files`_ django page for more
+information.
+
+Environment Variables
+^^^^^^^^^^^^^^^^^^^^^
+
+Polaris uses several environment variables that should be defined in the
+environment or included in ``PROJECT_ROOT/.env``.
 ::
 
     DJANGO_SECRET_KEY="yoursupersecretkey"
     DJANGO_DEBUG=True
 
     ASSETS="USD"
-    USD_STELLAR_DISTRIBUTION_ACCOUNT_SEED=""
-    USD_STELLAR_ISSUER_ACCOUNT_ADDRESS=""
+    USD_DISTRIBUTION_ACCOUNT_SEED=""
+    USD_ISSUER_ACCOUNT_ADDRESS=""
 
     STELLAR_NETWORK_PASSPHRASE="Test SDF Network ; September 2015"
     HORIZON_URI="https://horizon-testnet.stellar.org/"
@@ -94,6 +124,9 @@ account's private key and issuer account's public key. Note that each pair of va
 names should be prepended with the asset code. The SDF has built a small `CLI tool`_
 for creating these accounts on testnet.
 
+Python Code and Bash Commands
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
 Add the Polaris endpoints in ``urls.py``
 ::
 
@@ -105,9 +138,19 @@ Add the Polaris endpoints in ``urls.py``
         path("", include(polaris.urls)),
     ]
 
-Run migrations: ``python manage.py migrate``
+| Run migrations: ``python manage.py migrate``
+| Compile static assets: ``python manage.py compilescss``
+| Collect static assets: ``python manage.py collectstatic --no-input``
+
+The last step is to add an ``Asset`` database object for the token you
+intend to anchor. Get into the django python shell like so:
+``python manage.py shell``, then:
+::
+
+    from polaris.models import Asset
+    Asset.objects.create(code="USD", issuer="<the issuer address>")
 
-You now have Polaris completely integrated into your Django project!
+You are now ready to run the Polaris anchor server!
 
 Running the Server Locally
 ^^^^^^^^^^^^^^^^^^^^^^^^^^

docs/index.rst

@@ -32,52 +32,82 @@ Installation and Configuration
 ==============================
 
 .. _CLI tool: https://github.com/msfeldstein/create-stellar-token
+.. _Static Files: https://docs.djangoproject.com/en/2.2/howto/static-files/
 
 First make sure you have ``cd``'ed into your django project's main directory
 and then run
 ::
 
     pip install django-polaris
 
-Add it to ``INSTALLED_APPS`` in settings.py
+Configuring settings.py
+^^^^^^^^^^^^^^^^^^^^^^^
+
+Add the following to ``INSTALLED_APPS`` in settings.py. Any app that overrides
+a static asset in Polaris should be listed `before` "polaris". This ensures that
+django will find your asset before the Polaris default.
 ::
 
     INSTALLED_APPS = [
         ...,
+        "django.contrib.staticfiles",
+        "corsheaders",
+        "rest_framework",
+        "sass_processor",
         "polaris",
     ]
 
-Add Polaris' :doc:`PolarisSameSiteMiddleware </middleware/index>` to your
-``settings.MIDDLEWARE``. Make sure its listed `above` ``SessionMiddleware``.
+Add Polaris' :doc:`PolarisSameSiteMiddleware </middleware/index>` and
+``CorsMiddleware`` to your ``settings.MIDDLEWARE``.
+The form must be listed `above` ``SessionMiddleware``.
 ::
 
     MIDDLEWARE = [
-        'django.middleware.security.SecurityMiddleware',
+        ...,
         'polaris.middleware.PolarisSameSiteMiddleware',
         'django.contrib.sessions.middleware.SessionMiddleware',
-        'django.middleware.common.CommonMiddleware',
-        'django.middleware.csrf.CsrfViewMiddleware',
-        'django.contrib.auth.middleware.AuthenticationMiddleware',
-        'django.contrib.messages.middleware.MessageMiddleware',
-        'django.middleware.clickjacking.XFrameOptionsMiddleware',
+        'corsheaders.middleware.CorsMiddleware',
+        ...
     ]
 
-
 Define ``PROJECT_ROOT`` in your project's settings.py. Polaris uses this to
 find your ``.env`` file.
 ::
 
     PROJECT_ROOT = os.path.dirname(os.path.dirname(os.path.abspath(__file__)))
 
-Paste the text below into ``PROJECT_ROOT/.env``.
+Add the following to your settings.py as well:
+::
+
+    FORM_RENDERER = "django.forms.renderers.TemplatesSetting"
+    STATIC_ROOT = os.path.join(BASE_DIR, "<your static root directory>")
+    STATIC_URL = "<your static url path>"
+    STATICFILES_STORAGE = "whitenoise.storage.CompressedManifestStaticFilesStorage"
+    STATICFILES_FINDERS = [
+        "django.contrib.staticfiles.finders.FileSystemFinder",
+        "django.contrib.staticfiles.finders.AppDirectoriesFinder",
+        "sass_processor.finders.CssFinder",
+    ]
+    SASS_PROCESSOR_ROOT = STATIC_ROOT
+    DEFAULT_PAGE_SIZE = <your default page size>
+
+This allows Polaris to override django's default HTML widgets to provide
+a great UI out of the box. See the `Static Files`_ django page for more
+information.
+
+Environment Variables
+^^^^^^^^^^^^^^^^^^^^^
+
+Polaris uses several environment variables that should be defined in the
+environment or included in ``PROJECT_ROOT/.env``.
 ::
 
     DJANGO_SECRET_KEY="yoursupersecretkey"
     DJANGO_DEBUG=True
 
     ASSETS="USD"
-    USD_STELLAR_DISTRIBUTION_ACCOUNT_SEED=""
-    USD_STELLAR_ISSUER_ACCOUNT_ADDRESS=""
+    USD_DISTRIBUTION_ACCOUNT_SEED=""
+    USD_ISSUER_ACCOUNT_ADDRESS=""
 
     STELLAR_NETWORK_PASSPHRASE="Test SDF Network ; September 2015"
     HORIZON_URI="https://horizon-testnet.stellar.org/"
@@ -91,6 +121,9 @@ account's private key and issuer account's public key. Note that each pair of va
 names should be prepended with the asset code. The SDF has built a small `CLI tool`_
 for creating these accounts on testnet.
 
+Python Code and Bash Commands
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
 Add the Polaris endpoints in ``urls.py``
 ::
 
@@ -102,9 +135,19 @@ Add the Polaris endpoints in ``urls.py``
         path("", include(polaris.urls)),
     ]
 
-Run migrations: ``python manage.py migrate``
+| Run migrations: ``python manage.py migrate``
+| Compile static assets: ``python manage.py compilescss``
+| Collect static assets: ``python manage.py collectstatic --no-input``
+
+The last step is to add an ``Asset`` database object for the token you
+intend to anchor. Get into the django python shell like so:
+``python manage.py shell``, then:
+::
+
+    from polaris.models import Asset
+    Asset.objects.create(code="USD", issuer="<the issuer address>")
 
-You now have Polaris completely integrated into your Django project!
+You are now ready to run the Polaris anchor server!
 
 Running the Server Locally
 ^^^^^^^^^^^^^^^^^^^^^^^^^^

docs/integrations/index.rst

@@ -33,7 +33,6 @@ integration functions for anchors to override.
 Form Integrations
 -----------------
 
-.. _Bulma: https://bulma.io/documentation
 .. _Django Forms: https://docs.djangoproject.com/en/2.2/topics/forms/#forms-in-django
 
 Polaris uses `Django Forms`_ for collecting users' information, such as their
@@ -60,20 +59,6 @@ See the :doc:`../forms/index` documentation for the `TransactionForm` definition
 
 .. autofunction:: polaris.integrations.WithdrawalIntegration.after_form_validation
 
-Form CSS
-^^^^^^^^
-Polaris uses default CSS provided by Bulma_ for styling forms. To keep the
-UX consistent, make sure to pass in a modified `widget` parameter to all
-form fields displaying text like so:
-
-::
-
-    widget=forms.widgets.TextInput(attrs={"class": "input"})
-
-The `attrs` parameter adds a HTML attribute to the `<input>` tag that Bulma
-uses to add better styling. You may also add more Bulma-supported attributes
-to Polaris forms.
-
 Use an External Application for the Interactive Flow
 ----------------------------------------------------
 

docs/requirements.txt

@@ -10,12 +10,15 @@
 # `Pipfile.lock` and then regenerate `requirements*.txt`.
 ################################################################################
 
+django-compressor
 django-cors-headers
 django-environ
 django-model-utils
+django-sass-processor
 django-sslserver
 django==2.2.8
 djangorestframework
+libsass
 psycopg2-binary
 pyjwt
 stellar-sdk==2.0.0

example/server/integrations.py

@@ -7,7 +7,7 @@
 from django.db.models import QuerySet
 from django import forms
 
-from polaris.models import Transaction, Asset
+from polaris.models import Transaction
 from polaris.integrations import (
     DepositIntegration,
     WithdrawalIntegration,

polaris/polaris/deposit/views.py

@@ -98,7 +98,8 @@ def post_interactive_deposit(request: Request) -> Response:
     if error_resp:
         return error_resp
 
-    form = rdi.form_for_transaction(transaction)(request.POST)
+    form_class, _ = rdi.form_for_transaction(transaction)
+    form = form_class(request.POST)
     is_transaction_form = issubclass(form.__class__, TransactionForm)
     if is_transaction_form:
         form.asset = asset
@@ -115,9 +116,9 @@ def post_interactive_deposit(request: Request) -> Response:
         rdi.after_form_validation(form, transaction)
 
         # Check to see if there is another form to render
-        form_class = rdi.form_for_transaction(transaction)
+        form_data = rdi.form_for_transaction(transaction)
 
-        if form_class:
+        if form_data:
             args = {"transaction_id": transaction.id, "asset_code": asset.code}
             url = reverse("get_interactive_deposit")
             return redirect(f"{url}?{urlencode(args)}")
@@ -158,10 +159,19 @@ def get_interactive_deposit(request: Request) -> Response:
     if err_resp:
         return err_resp
 
-    form = rdi.form_for_transaction(transaction)()
+    try:
+        form_class, context = rdi.form_for_transaction(transaction)
+    except TypeError:
+        return render_error_response(
+            "The anchor did not provide a form, unable to serve page.",
+            status_code=500,
+            content_type="text/html",
+        )
+
     url_args = {"transaction_id": transaction.id, "asset_code": asset.code}
     post_url = f"{reverse('post_interactive_deposit')}?{urlencode(url_args)}"
-    resp_data = {"form": form, "post_url": post_url}
+    resp_data = {"form": form_class(), "post_url": post_url}
+    resp_data.update(context)
     return Response(resp_data, template_name="deposit/form.html")