Form definitions powering Resistbot's electronic deliveries to elected officials in the United States.
Configuration files used by Resistbot to contact state and federal officials with their web forms.
The focus right now is on writing web form configs for 1) governors and 2) state legislative bodies which offer consistent contact forms for all
members. These forms are as interoperable as possible with the
unitedstates/contact-congress
schema (i.e. Phantom of DC).
The document Teach Resistbot to send a message to a US Governor
walks you through the steps to contribute a new governor.yaml to this repo.
Resistbot lets any American easily write a message to their governor. After you
teach Resistbot to use a governor’s official web contact form
by writing a new governor.yaml, Resistbot will be able to deliver
messages immediately to that governor. You’ll have made it faster and
easier for everybody to be heard in local politics.
- states- CA* upper.yaml # form config that applies for all members of California State Senate* lower.yaml # for all members of California State Assembly* governor.yaml # for CA governor* CAL000501.yaml # e.g. if we want to use different form config for Sen. de León than other CA senators- TX* upper.yaml # for all members of Texas State Senate* lower.yaml # for all members of Texas State House of Representatives... directories for other states ...- congress* P000603.yaml # for Rand Paul, Resistbot uses this intead of contact-congress/P000603.yaml... configs for other Members of Congress for whom Resistbot has its own setup ...- whitehouse* president.yml # for the White House... configs for other federal executives with web forms, as Resistbot adds support ...- us* scotus.yml # for SCOTUS... configs for other national levels with web forms, as Resistbot adds support ...- municipalities- NY- mayors# Mayor files are named for the city by convention, but the format is not strict.# bioguide in the config drives unique identification of the mayor.* new-york.yaml* albany.yaml- TX- mayors* dallas.yaml... directories for other states ...
Notes:
Bio IDs come from Biographical Directory of the United States Congress
and from Open States.
upper and lower correspond to values that chamber/post.label takes in Open States.
We will keep congress directory as sparse as possible, strongly
preferring to make changes upstream and defer to the config in contact-congress.
Schema is based on that of unitedstates/contact-congress with these changes:
New variables PHONE_AREA_CODE, PHONE_DIGITS_ONLY, PHONE3, PHONE4, PHONE7, NAME_FULL, NAME_PREFIX_NO_PERIOD, ADDRESS_STREET_CITY_STATE, ADDRESS_FULL.
bioguide, contact_form.method, and contact_form.action are optional, except for mayor, where bioguide is required.
In fill_in steps, captcha_selector can be an element enclosing text.
The processor should strip non-word characters from beginning and end of this element’s textContent,
append captcha_append_guidance if present, and then submit this for textual
captcha solving. See states/FL/upper.yaml for an example.
In fill_in steps with image captchas, captcha_image_extension can
optionally specify filename extension of the image, for example png. This
is necessary to use if the src of the img element does not have an image
format extension, which 2captcha requires. See states/SC/upper.yaml
for an example.
In a success section, instead of body, one can specify text that must match an alert, or one
can specify a CSS selector for an element that must be found. See states/WA/governor.yaml for
an example of the alert functionality, and states/CA/lower.yaml for an example of a CSS selector. You can also specify a custom timeout directive, in seconds, to wait for the success criteria to appear. See states/FL/governor.yaml for an example.
In recaptcha section, a callback and callback_selector can optionally be defined. If the
recaptcha callback is not defined in a data-callback attribute on the captcha element, its callback will
need to be found and explicitly passed as callback. If the callback requires the captcha
element be passed as a param, a selector for the element must be given as callback_selector. The recaptcha section also allows an optional version parameter. This is used when V3 is utilized by a form, and currently ‘V3’ is the only acceptable value. An optional response_selector can be used when the selector for the validated data is non-standard (some wpcf7 forms). At this time, the selector can be either the name attribute of a input tag, or an element ID.
Introduction of meta variables, described below.
Collectively, state legislatures are huge. Let’s look at the three most populous states plus Ohio. These are the largest states that offer web contact forms for their legislators.
If we use one form config per bioguide, that’s 593 form config files. Moreover, if perhaps 20% of officials churn in an election cycle, that’s about 100 form config files we need to delete and 100 form config files we need to add. Worse, because the contact forms for these states’ representatives are maintained by the state, if a contact form changes, we need to update tens or hundreds of config files at once.
So it would be expedient if we can, in states with consistent forms per chamber, set up state form config files that can be used for every member of the chamber. We wouldn’t need to do anything to handle churn, since we are not hard-coding bioguides anywhere. If a contact form changes, we need to update only one config file.
Let’s make it possible for form configs to reference dynamically an individual district or URL.
We introduce notion of “meta variable”, and make it possible to include $META_VARIABLES anywhere in the document. They will simply be replaced with the value of the variable, i.e. config.replace('$META_OFFICIAL_DISTRICT_ZFILL', '07'). The context must take care of quoting, if necessary.
For example, the CA senator config starts with:
- visit: "https://lcmspubcontact.lc.ca.gov/PublicLCMS/ContactPopup.php?district=SD$META_OFFICIAL_DISTRICT_ZFILL"
and the CA representative config with:
- visit: "https://lcmspubcontact.lc.ca.gov/PublicLCMS/ContactPopup.php?district=AD$META_OFFICIAL_DISTRICT_ZFILL"
The config for OH senate starts with:
- visit: "$META_OFFICIAL_URL"
Config files in contact-officials assume meta variables defined as
follows:
$META_OFFICIAL_DISTRICT: The district of the official, or empty
string if official holds statewide office. This corresponds todistrict in Open States and theunitedstates.io Congress data.
$META_OFFICIAL_DISTRICT_ZFILL: District normalized such that
single-digit district names get a leading zero, e.g. “07”.
$META_OFFICIAL_URL: The URL of the official homepage of the
official. This corresponds to url in Open States and url in
theunitedstates.io Congress data.
$META_OFFICIAL_LAST_SEGMENT_OF_URL: Everything after the last slash
in the official’s URL. One can’t directly visit a NJ state
legislator’s URL (e.g.
http://www.njleg.state.nj.us/members/bio.asp?Leg=47) directly without
being served a redirect! The only way to get to such a URL is by
clicking on a link from e.g. the roster, which sets some server-side
session state. This meta variable helps click on the legislator’s
link from the roster.
$META_OFFICIAL_STATE_LEGISLATOR_INDEX: The index (1-indexed) of the
official in list of the chamber legislators by alphabetical order by
last name of state lower chamber legislators in alphabetical name.
Even after visiting a NJ legislator’s personal webpage, and clicking
contact link, one is taken to a page that lists a district’s 1 senator
and 2 representatives, with checkboxes for each. For assemblymembers,
the only way we can select the right checkbox here is to introduce
this meta variable which identifies the legislator’s index in this list,
1-indexed.
$META_OFFICIAL_FIRST_NAME: First name of official.
$META_OFFICIAL_LAST_NAME: Last name of official.
$META_OFFICIAL_FULL_NAME: Full name of official (first and
last, separated by a space).