Package: photon-platform-formulator
Formulator is a library for dynamically generating terminal-based forms using
Python and the Textual library. Forms are defined using a simple YAML blueprint
format that specifies the form fields, their types, and their validation rules.
The Formulator library interprets this blueprint and generates a form that can
be interacted with in the terminal. When the form is submitted, Formulator
validates the input values against the validation rules and displays any
errors. It’s a handy tool for collecting user input from the terminal in a
structured and validated manner.Warningthis is a very early concept and is likely to change frequentlyInstallationInstall Formulator with pip:pipinstallphoton-platform-formulatorUsageTo use Formulator, first define your form blueprint in a YAML file. For example:form:title:Retro Encabulator Configuratorid:retro-encabulatorfields:instrument-name:label:Instrumentplaceholder:Enter Nametype:Inputvalidate:required:truemax_length:8# ...Then, in your Python script, load the blueprint and pass it to the Formulator class:fromphoton_platform.formulatorimportFormulator,load_blueprintblueprint=load_blueprint("blueprint.yaml")form=Formulator(blueprint)reply=form.run()FeaturesFormulator comes packed with a range of features that make it easy and efficient to generate dynamic forms:Simple Blueprint Definition: Formulator uses a simple and intuitive YAML
blueprint to define form fields, types, options, and validation rules. This
makes it easy to create complex forms without writing any code.Dynamic Form Generation: Based on the provided YAML blueprint,
Formulator dynamically creates an interactive form in the terminal. This
includes a variety of field types such as input boxes, checkboxes, radio
buttons, and select dropdowns.Custom Validation: Formulator comes with a default set of validation
rules, including checks for required fields, minimum and maximum lengths,
numeric and alphabetic values, and email format. However, you can also
define your own validation rules by extending the Validator class.Flexible Layout: Formulator uses the Composer class to layout the form
widgets. You can override the default Composer class to customize the layout
according to your needs.Form Submission and Error Handling: When the form is submitted,
Formulator validates the input values against the validation rules and
displays any errors in a pop-up window. If the form is valid, Formulator
exits and returns a dictionary with the form values. This allows for
seamless integration with your application logic.Supported Textual WidgetsFormulator’s Composer class is designed to work with a variety of Textual
widgets. Below is a list of the currently supported widgets:Input: A basic text input field for user input.Checkbox: A field that can be checked or unchecked by the user.RadioSet: A set of radio buttons, where the user can select one option
from several.Select: A dropdown field where the user can select one option from a
list.Switch: A toggle switch that can be turned on or off.Button: A clickable button, used in Formulator for form submission and
quitting the application.Label: A text label used for displaying field names and other
information.Please note that the appearance and behavior of these widgets can be customized
by overriding the Composer class, giving you flexibility in creating the user
interface for your form.Command Line UsageYou can use Formulator from the command line using theformulatorcommand.Once you have your blueprint, you can run Formulator with the–blueprintoption:formulator--blueprintpath/to/your/blueprint.yamlThe–blueprintoption should be a path to a YAML file that contains your form blueprint. This will launch the Formulator app and display your form in the terminal. After you fill out and submit the form, the values you entered will be printed to the terminal as YAML.DemosIn thedemosdirectory, you will find ready-made examples showcasing the power and flexibility of Formulator. These examples serve as a reference guide for creating your own complex forms, as well as demonstrating Formulator’s functionality in configuring advanced machinery.Retro Encabulator Configurator (retro_encabulator.py / retro_encabulator.yaml)This is a brilliant example of Formulator’s capacity to streamline the configuration of advanced devices, such as the Retro Encabulator. With its modial interaction of magneto-reluctance and capacitive directance, the Retro Encabulator is a wonder of modern engineering. Configure everything from the cardinal grammeters synchronization to the number of hydrocoptic marzelvanes.Flux Capacitor Configurator (flux_capacitor.py / flux_capacitor.yaml)Dive into time travel technology with Formulator, as it allows you to customize the settings of your own Flux Capacitor. Ensure that your Flux Capacitor is always set to the appropriate jigowatt level, and that your time circuits are functioning optimally. Remember, your future is whatever you make it, so make it a good one with Formulator.Millenium Falcon Console (millenium_falcon.py / millenium_falcon.yaml)Step into the pilot’s seat of the fastest hunk of junk in the galaxy with Formulator’s Millenium Falcon console configurator. Tune the hyperdrive parameters, adjust the deflector shields, and calibrate the inertial dampeners to ensure your next Kessel Run is under twelve parsecs. Remember, she may not look like much, but she’s got it where it counts, kid.All demos include a Python script and a corresponding YAML blueprint. You can run the Python script directly to display the form in your terminal, or you can use theformulator –blueprintcommand with the YAML blueprint to achieve the same result.Writing BlueprintsCreating a form with Formulator begins with writing a blueprint in YAML format. This blueprint defines the form’s structure, the fields it contains, and the validation rules for each field.Formulator blueprints consist of a single ‘form’ object, which can have the following properties:title: The title of the form.id: A unique identifier for the form.fields: An object where each property represents a form field. The name of the property is used as the field’s ID.Each field in the ‘fields’ object can have the following properties:label: The label for the field, displayed to the user.type: The type of the field, which determines the kind of input the field accepts. It can be one of the following:Input: A text input field.Checkbox: A checkbox field.Select: A dropdown select field.RadioSet: A radio button set.Switch: A toggle switch.Button: A button.placeholder(optional): A placeholder text forInputfields, displayed when the field is empty.options(optional): A list of options forSelectandRadioSetfields.option(optional): The label for theCheckboxfield’s option.validate(optional): An object where each property represents a validation rule. The name of the property is used as the rule’s name, and its value as the rule’s argument. Available validation rules includerequired,min_length,max_length,numeric,alphabetic,min_value,max_value, andemail.Here’s an example of a simple blueprint:form:title:Example Formid:example-formfields:name:label:Nametype:Inputvalidate:required:truemin_length:2age:label:Agetype:Inputvalidate:required:truenumeric:truemin_value:0color:label:Favorite Colortype:Selectoptions:-Red-Green-Blue-Yellow-PurpleThis blueprint defines a form with the title “Example Form” and two fields, ‘Name’ and ‘Age’. The ‘Name’ field is a text input field that requires at least two characters, and the ‘Age’ field is also a text input field but requires a numeric value. The ‘Favorite Color’ field is a dropdown select field with five color options.For more complex examples, refer to the demos provided in the ‘demos’ directory of the Formulator repository.CustomizationFormulator’s behavior can be customized by providing your own Validator and
Composer classes. Validator is used to check the form input values against the
validation rules, and Composer is used to layout the form widgets.fromphoton_platform.formulatorimportFormulator,Validator,Composer,load_blueprintclassMyValidator(Validator):pass# define your validation methods hereclassMyComposer(Composer):pass# define your layout method hereblueprint=load_blueprint("blueprint.yaml")form=Formulator(blueprint,validator=MyValidator(),composer=MyComposer())form.run()More InformationFor more information and examples, see theFormulator GitHub page.