Package: django-apollo-forms
What Apollo IsAtMorgan & Morgan, the development team builds lots of forms. A lot. While most of the
heavy lifting for form management was done for us by the marketing platform, Hubspot, there were some major gaps that forced us to consider
a switch:Cost. Our Hubspot license was > $50,000 yearly where the only utility came from the form management tooling.Lack of flexibility. While defining basic validation rules and field layouts was OK, doing anything more complex
(e.g. email blacklists, geo-based submission filtering, etc.) was impossible. In fact, since their switch to React rendered
forms,custom validation in a Hubspot form doesn't work at all.Lack of control. The Hubspot JS library is 300kb+ in size before gzip and sets short-term cache expiration headers. Why? It's hard to say without access to the unminified source.Lack of transparency. Hubspot provides Salesforce syncing out of the box. However, having a highly customized Salesforce Org,
our Hubspot sync process was anything but straightforward.With these problems in mind, we builtApolloas a solution.Apollo is a Django application which - in conjunction with theIcarus Javascript Library-
aims to act as a plug-and-play solution for the busy engineer. In addition to providing a management interface for building
form fields, designing forms, and viewing form submissions, Apollo makes the assumption that it should make no assumptions about
domain specific requirements of the host application. Thus, it decouples form management from submission processing,
leaving the job of reacting to events within the host. To facilitate this architecture, Apollo opts for a Pub/Sub design, notifying listeners
on key events:form submittedform submission validatedform submission errorSee more details on signals in thesignals referenceWhy ApolloIt is - and always will be - free and open sourcePlug-and-play architectureUtility in a wide variety of use caseIntegration with native Django permissions, allowing for role assignment when delegating API / form builder access.Installationpipinstalldjango-apollo-forms# add the App to the list of INSTALLED_APPSINSTALLED_APPS={...'django_filters','rest_framework','rest_framework_swagger',# optional, creates browsable API docs'apollo',...}# run the migrations to generate DB tablespythonmanage.pymakemigrationsapollo
pythonmanage.pymigrateapollo# collectstatic to generate the static files for the form builder interfacepythonmanage.pycollectstaticCustomizationYou can customize the behavior of Apollo by overriding the defaults of theAPOLLOvariable in your settings.py. Below
are the parameters which may be controlled in this setting.ParameterDefaultDescriptionBUILDER_ROOT_PREFIX""The path at which the Apollo form builder is mounted in the host applicationBUILDER_REQUIRES_IS_STAFFTrueIf True, then only users withis_staffpermissions can access the form builderDOWNLOAD_REQUIRES_IS_STAFFTrueIf True, then only users withis_staffpermissions can download form submissionsAPI_ROOT/apiThe path to the API root on the serverAPI_VERSIONv1The Apollo API versionICARUS_THEMES_URL//static.forthepeople.com/engineering/icarus/v1.0-latest/themesLocation where icarus themes are locatedSUBMISSION_EMAIL_FROMNoneEmail address to send submission notifications fromEXTERNAL_HOOKS_SIGNAL_ONLYTrueIf True, then we we do not send webhooks notifications, only trigger a signalDEFAULT_FORM_SUBMISSION_SERIALIZERapollo.api.v1.serializers.FormSubmissionSerializerDotted path to a serializer class to use for FormSubmission objectsExampleAPOLLO={"BUILDER_ROOT_PREFIX":"/apollo"}FeaturesSetup field templates for your forms. These define the default configurations for fields and can be overridden on a per-form basis.Step-by-step form builder interface.Powerful layout creator with the ability to apply different layouts for desktop and mobile screens.Form UsageWhen it comes to actually using the forms built by Apollo, you have two options:Use theIcarus Javascript Library(Recommended)DIY.If you decide to pursue (2), you'll want to consult the Browsable API, mounted at/<API_ROOT>/<API_VERSION>/docsfor details on authentication, request format,
and available resources.DevelopmentGetting StartedBringing up a new dev environment should be fairly straightforward. Rundocker-compose up -dto bring up a complete development
environment.Building ReleasesCreate a virtualenv then runpip install -r requirements.txtin order to install versioning utilities. Runbumpversion <SEMVER>to create a buildable version then push upstream to trigger CI.