# Table of Contents - [Overview of docassemble](#overview-of-docassemble) - [Hello world example](#hello-world-example) - [Question blocks](#question-blocks) - [How to write an interview](#how-to-write-an-interview) - [Code questions](#code-questions) - [Question modifiers](#question-modifiers) - [Marking up text](#marking-up-text) - [External data](#external-data) - [Interview logic](#interview-logic) - [Initial blocks](#initial-blocks) - [Special variables](#special-variables) - [Assembling documents](#assembling-documents) - [Groups of things: lists, dictionaries, and sets](#groups-of-things-lists-dictionaries-and-sets) - [Language support](#language-support) - [Roles](#roles) - [Text messaging interface](#text-messaging-interface) - [Accessibility](#accessibility) - [Live help: chat, phone, monitoring](#live-help-chat-phone-monitoring) - [User login system](#user-login-system) - [Custom Front Ends](#custom-front-ends) - [Machine learning](#machine-learning) - [Customizing the user interface](#customizing-the-user-interface) - [Interview developers' playground](#interview-developers-playground) - [Running code behind the scenes](#running-code-behind-the-scenes) - [Overview of the development process](#overview-of-the-development-process) - [Support](#support) - [Debugging](#debugging) - [Package management](#package-management) - [Overview of docassemble administration](#overview-of-docassemble-administration) - [Contributing](#contributing) - [Policies](#policies) - [Security](#security) - [Scalability of docassemble](#scalability-of-docassemble) - [License](#license) - [Migration from Python 2.7 to Python 3](#migration-from-python-2-7-to-python-3) - [Future development ideas](#future-development-ideas) - [The "legal" module and basic-questions.yml](#the-legal-module-and-basic-questions-yml) - [API](#api) - [Overview of docassemble](#overview-of-docassemble) - [System-wide configuration](#system-wide-configuration) - [Installing on Docker](#installing-on-docker) - [Recipes](#recipes) - [Change Log](#change-log) --- # Overview of docassemble [Edit](https://github.com/jhpyle/docassemble/blob/gh-pages/docs.md "Edit this page on GitHub") Overview of docassemble ======================= **docassemble** is a platform for creating mobile-friendly web applications called [Interviews](https://docassemble.org/docs/interviews.html) that ask one question at a time in order to reach an end point. This end point may be the presentation of advice, the creation of a signed document, the submission of an application, or something else. Run the [Demonstration](https://docassemble.org/demo.html) to get an idea for what **docassemble** applications look like. You can run **docassemble** on your laptop, but most people run it “in the cloud” on [Amazon Web Services](https://aws.amazon.com/ec2/) , [Digital Ocean](https://www.digitalocean.com/) , or another hosting service. The [Deploy](https://docassemble.org/deploy.html) page describes a variety of ways you can get your own **docassemble** instance up and running. You can install **docassemble** on a server using [Docker](https://docassemble.org/docs/docker.html) or (if you are an expert) follow the detailed [Installation](https://docassemble.org/docs/installation.html) instructions. For the most part, the [Administration](https://docassemble.org/docs/admin.html) and [Configuration](https://docassemble.org/docs/config.html) of **docassemble** can be handled through the web interface. Introduction to **docassemble** =============================== Interview developers write interviews in [YAML](https://en.wikipedia.org/wiki/YAML) format, a plain-text format that is human-readable but also machine-readable. An interview consists of multiple “blocks.” Blocks are pieces of text separated by `---`, which is a record separator in [YAML](https://en.wikipedia.org/wiki/YAML) . For example: question: Do you like turnips? yesno: likes_turnips --- question: When did you stop idolizing worms? fields: - Date: worm_idolizing_stop_date datatype: date [GitHub](https://github.com/jhpyle/docassemble/blob/master/docassemble_demo/docassemble/demo/data/questions/examples/turnips-worms.yml "Open on GitHub") [![Screenshot of turnips-worms example](https://docassemble.org/img/examples/turnips-worms.png)](https://demo.docassemble.org/interview?i=docassemble.demo:data/questions/examples/turnips-worms.yml&reset=1 "Click to try this interview") You can click the screenshot above to see this interview in action. If you hover over the source code, three dots will appear in the lower-right corner; if you click the three dots, you can see full interview [YAML](https://en.wikipedia.org/wiki/YAML) behind the sample interview. Some blocks are [Question Blocks](https://docassemble.org/docs/questions.html) that represent screens that the user will actually see. (Two examples are above.) The basic structure of question blocks is simple, but there are a lot of possible [Question Modifiers](https://docassemble.org/docs/modifiers.html) that can make your screens do different things. The information gathered from users is stored in “variables,” and the purpose of most question blocks will be [Setting Variables](https://docassemble.org/docs/fields.html) . You can use whatever variable names you want, except you can’t use the names of [Special Variables](https://docassemble.org/docs/special.html) that already have their own meaning. **docassemble** supports [many different types](https://docassemble.org/docs/fields.html#data%20types) of variables – even [file uploads](https://docassemble.org/docs/fields.html#file) and [touchscreen signatures](https://docassemble.org/docs/fields.html#signature) . One of the most powerful features is the ability to store information in a structured way using [Objects](https://docassemble.org/docs/objects.html) . When you want to collect one or more pieces of related information, you can collect the information into [Groups](https://docassemble.org/docs/groups.html) such as [lists](https://docassemble.org/docs/groups.html#gather%20list) and [dictionaries](https://docassemble.org/docs/groups.html#gather%20dictionary) . There are other types of blocks besides [`question`](https://docassemble.org/docs/questions.html#question) blocks. [Initial Blocks](https://docassemble.org/docs/initial.html) set interview-wide options, like the special [features](https://docassemble.org/docs/initial.html#features) of an interview, or the default [screen parts](https://docassemble.org/docs/questions.html#screen%20parts) . [Code](https://docassemble.org/docs/code.html) blocks allow you to set variables through computation. Code is written in [Python](https://en.wikipedia.org/wiki/Python_%28programming_language%29) . To write an interview, you do not need to know much about [Python](https://en.wikipedia.org/wiki/Python_%28programming_language%29) except how to write “if/then/else” statements. code: | if plaintiff.county == defendant.county: jurisdiction_is_proper = True You can even use “fuzzy logic” with **docassemble**’s [Machine Learning](https://docassemble.org/docs/ml.html) feature. **docassemble** decides which questions to ask, and the order in which to ask them, according to the [Interview Logic](https://docassemble.org/docs/logic.html) . You can specify the order of questions with great specificity if you want, or you can just specify an end goal and let **docassemble** figure everything out on its own. A popular use of interviews is the assembly of [Documents](https://docassemble.org/docs/documents.html) (hence the name **docassemble**). You can write document templates in [DOCX](https://docassemble.org/docs/documents.html#docx%20template%20file) or [PDF](https://docassemble.org/docs/documents.html#pdf%20template%20file) formats. You can also write documents the same way you write questions, in plain text using [Markup](https://docassemble.org/docs/markup.html) to indicate formatting. As your interviews become more sophisticated, you will find it useful to invoke [Functions](https://docassemble.org/docs/functions.html) to do things like conjugate verbs, compute differences between dates, or offer the user hyperlinks that perform special [actions](https://docassemble.org/docs/functions.html#actions) . **docassemble** uses a [User Login](https://docassemble.org/docs/users.html) system that allows users to create accounts, save their answers, and resume their interviews at a later date. Since **docassemble** is a free and open-source application, it is designed to be interoperable with other applications. There are a variety of ways to work with [External Data](https://docassemble.org/docs/external.html) ; you can move information easily into and out of a **docassemble** interview session. There is also a full-featured [API](https://docassemble.org/docs/api.html) for interacting with **docassemble** programmatically. You can also design your own [Custom Front Ends](https://docassemble.org/docs/frontend.html) . Developers can prototype and test their interviews in the browser, using the interview developers’ [Playground](https://docassemble.org/docs/playground.html) . Once you get a **docassemble** server [up and running](https://docassemble.org/deploy.html) , go through the [Hello World](https://docassemble.org/docs/helloworld.html) tutorial to learn more about how interviews work. As you become more experienced using the system, you may want to explore using other [Development Workflows](https://docassemble.org/docs/development.html) than just the [Playground](https://docassemble.org/docs/playground.html) . One of **docassemble**’s most powerful features is its ability to operate multi-user interviews through the [Roles](https://docassemble.org/docs/roles.html) feature. For example, a user could fill out an interview and then an attorney could enter the interview to evaluate the information and provide legal advice, which the user would see the next time they log in. Using the [Background Tasks](https://docassemble.org/docs/background.html) features, you can have your interviews do things on the server at times other than when the user presses a button to advance to a new page. Time-intensive tasks can run in the [background](https://docassemble.org/docs/background.html#background) . The interview can [evaluate user input](https://docassemble.org/docs/background.html#check%20in) before the user clicks the Continue button. Interviews can do things [when the user is not logged in](https://docassemble.org/docs/background.html#scheduled) , like send a reminder [e-mail](https://docassemble.org/docs/functions.html#send_email) to a user about a deadline as the date approaches. **docassemble** is a multi-purpose platform, but it is particularly designed for [Legal Applications](https://docassemble.org/docs/legal.html) , and has special functionality for that specific purpose. If you need to make an interview available in more than one language, **docassemble**’s [Language Support](https://docassemble.org/docs/language.html) features can help you manage translations. **docassemble** also has a number of features for [Accessibility](https://docassemble.org/docs/accessibility.html) by persons with disabilities. **docassemble** was built on the model of the open-source software development world. Interviews can be bundled into [Packages](https://docassemble.org/docs/packages.html) , which can be shared on [GitHub](https://github.com/) or moved between servers as ZIP files. The mobile-friendly web interface is the primary way that users will run interviews, but there is also the option of making interviews available via [Text Messaging](https://docassemble.org/docs/sms.html) . When you deploy your interviews, there are a variety of ways you can provide support to your users. The [Live Help](https://docassemble.org/docs/livehelp.html) features allow operators to communicate with users using on-line chat. Operators can see users’ screens and even take control if necessary. If communication by phone is necessary, operators can provide users with a special phone number and code that forwards a call without revealing the operator’s actual phone number. **docassemble** has excellent [Scalability](https://docassemble.org/docs/scalability.html) when deployed in the cloud, so you don’t have to worry about what will happen if your interviews get a lot of traffic. If your interviews will process sensitive information, **docassemble** has a number of [Security](https://docassemble.org/docs/security.html) features to keep that information safe, such as server-side encryption. Developers will invariably make mistakes and encounter [Errors](https://docassemble.org/docs/errors.html) . **docassemble** tries to provide helpful error messages in the browser or in logs stored on the server. If you get stuck, you can seek out [Support](https://docassemble.org/docs/support.html) from the **docassemble** community, in particular by posting a question on the **docassemble** [Slack](https://join.slack.com/t/docassemble/shared_invite/zt-2cspzjo9j-YyE7SrLmi5muAvnPv~Bz~A) . You might also find that there is an example interview in the [Recipes](https://docassemble.org/docs/recipes.html) that will help you solve your problem. **docassemble** is free software available with a highly permissive open-source [License](https://docassemble.org/docs/license.html) . The software is updated frequently, and you can see what new features are available by reading the [Change Log](https://docassemble.org/docs/changelog.html) . Note that if you have been using **docassemble** for a long time, you need learn about the necessity of doing a [Python Upgrade](https://docassemble.org/docs/twotothree.html) . Using the documentation ======================= The **docassemble** documentation is intended more as a reference guide than as a manual that you have to read before getting started. The best way to learn about **docassemble** is to start creating your own interview. Start by following along with the “Hello, world” [tutorial](https://docassemble.org/docs/helloworld.html) that explains how to create a simple interview. Once you get that working, you can experiment with adding more questions to it. The best way to learn about more advanced **docassemble** features is to study working examples. The sections of this documentation site contain a number of side-by-side examples comparing source code to screenshots. You can click on the screenshots to run the interviews. The code next to the screenshots is often only an excerpt of the full interview. To see the full source code of the interview, hover over the source code and click the button that appears in the lower right corner. In addition, while you are developing interviews in the [Playground](https://docassemble.org/docs/playground.html) , you can browse working examples of many of **docassemble**’s features. There is also a full-featured sample interview linked from the [demonstration page](https://docassemble.org/demo.html) . While you are using the interview you can click “Source” in the navigation bar to toggle display of the source code for the question and an explanation of the path **docassemble** took to decide to ask that question. Sections of the documentation ============================= * Tutorial * [Hello World](https://docassemble.org/docs/helloworld.html) * Authoring guide * [Interviews](https://docassemble.org/docs/interviews.html) * [Initial Blocks](https://docassemble.org/docs/initial.html) * [Question Blocks](https://docassemble.org/docs/questions.html) * [Setting Variables](https://docassemble.org/docs/fields.html) * [Question Modifiers](https://docassemble.org/docs/modifiers.html) * [Code](https://docassemble.org/docs/code.html) * [Interview Logic](https://docassemble.org/docs/logic.html) * [Markup](https://docassemble.org/docs/markup.html) * [Documents](https://docassemble.org/docs/documents.html) * [Objects](https://docassemble.org/docs/objects.html) * [Groups](https://docassemble.org/docs/groups.html) * [Functions](https://docassemble.org/docs/functions.html) * [External Data](https://docassemble.org/docs/external.html) * [Legal Applications](https://docassemble.org/docs/legal.html) * [Special Variables](https://docassemble.org/docs/special.html) * Special features * [Language Support](https://docassemble.org/docs/language.html) * [Accessibility](https://docassemble.org/docs/accessibility.html) * [Roles](https://docassemble.org/docs/roles.html) * [Background Code](https://docassemble.org/docs/background.html) * [Machine Learning](https://docassemble.org/docs/ml.html) * [SMS Interface](https://docassemble.org/docs/sms.html) * [API](https://docassemble.org/docs/api.html) * [Custom Front Ends](https://docassemble.org/docs/frontend.html) * Users * [User Login](https://docassemble.org/docs/users.html) * [Live Help](https://docassemble.org/docs/livehelp.html) * Development * [Overview](https://docassemble.org/docs/development.html) * [Playground](https://docassemble.org/docs/playground.html) * [Packages](https://docassemble.org/docs/packages.html) * [UI Customization](https://docassemble.org/docs/ui.html) * [Debugging](https://docassemble.org/docs/errors.html) * [Support](https://docassemble.org/docs/support.html) * [Future](https://docassemble.org/docs/future.html) * [Recipes](https://docassemble.org/docs/recipes.html) * Administration * [Overview](https://docassemble.org/docs/admin.html) * [Installation](https://docassemble.org/docs/installation.html) * [Docker](https://docassemble.org/docs/docker.html) * [Configuration](https://docassemble.org/docs/config.html) * [Scalability](https://docassemble.org/docs/scalability.html) * [Security](https://docassemble.org/docs/security.html) * [Change Log](https://docassemble.org/docs/changelog.html) * [Contributing](https://docassemble.org/docs/contributing.html) * [Policies](https://docassemble.org/docs/policies.html) * [License](https://docassemble.org/docs/license.html) * * * --- # Hello world example [Edit](https://github.com/jhpyle/docassemble/blob/gh-pages/_docs/helloworld.md "Edit this page on GitHub") Hello world example =================== Contents -------- * [1 Adding a question](https://docassemble.org/docs/helloworld.html#tocAnchor-1-1) * [2 Adding some Python code](https://docassemble.org/docs/helloworld.html#tocAnchor-1-2) * [3 Creating a document](https://docassemble.org/docs/helloworld.html#create%20document) * [4 Decorate with an image](https://docassemble.org/docs/helloworld.html#tocAnchor-1-4) * [5 Testing your interview](https://docassemble.org/docs/helloworld.html#testing) * [6 Packaging your interview](https://docassemble.org/docs/helloworld.html#packaging) * [6.1 Storing on PyPI](https://docassemble.org/docs/helloworld.html#pypi) * [6.2 Storing on Github](https://docassemble.org/docs/helloworld.html#github) Here is a simple interview file that says “Hello, world!” to the user. --- question: Hello, world! buttons: - Exit: exit mandatory: True --- To run this, first set up your server using [Docker](https://docassemble.org/docs/docker.html) . To get **docassemble** up and running in your web browser, visit [http://localhost](http://localhost/) if you are running **docassemble** locally (i.e., using Docker Desktop on your computer), or else navigate to your **docassemble** server URL). Once **docassemble** is up and running in your web browser, click “Log in” in the upper right hand corner. The default username and password are: * **E-mail**: admin@example.com * **Password**: password The default password (“password”) will need to be changed. Change it to something that is at least eight characters long with at least one lowercase letter and one number. You should also change the e-mail address by going to [User List](https://docassemble.org/docs/admin.html#user%20list) and clicking “Edit” next to the admin@example.com user. Then, from the menu, select [Playground](https://docassemble.org/docs/playground.html) . The [Playground](https://docassemble.org/docs/playground.html) is a “sandbox” area where you can develop interviews and test them, all inside the web browser. ![Playground](https://docassemble.org/img/menu-selection-playground.png) Then, click the  [Add](javascript:return(0)) button to create a new interview. Call it “hello.yml.” (`.yml` is the file extension for the data format known as [YAML](https://en.wikipedia.org/wiki/YAML) .) ![New interview](https://docassemble.org/img/playground-new-interview.png) Then, copy and paste the interview code above into the editor: ![Code copied into interview](https://docassemble.org/img/playground-new-interview-with-code.png) Then, click the [Save](javascript:return(0)) button, followed by the [Save and Run](javascript:return(0)) button. You should see: ![Hello world interview](https://docassemble.org/img/tutorial-hello-world-interview-01.png) (If you do not have a server yet, you can [try it out here](https://demo.docassemble.org/interview?i=docassemble.demo:data/questions/hello.yml) .) Adding a question ================= Now let’s change the interview so that it asks the user a [question](https://docassemble.org/docs/questions.html) . Edit the interview and change the contents to: --- question: Hello, ${ planet }! buttons: - Exit: exit mandatory: True --- question: | What is your planet's name? fields: - Your Planet: planet --- (If you do not have your own server yet, you can [try it out here](https://demo.docassemble.org/interview?i=docassemble.demo:data/questions/hello2.yml) .) It should now ask you “What is your planet’s name?” and then greet your world by its name. Try clicking in the navigation bar. This toggles the display of information that will help you understand how a question came to be asked. This can be helpful for “debugging” your interview. Information about the readability of your interview question is also displayed. ![Source](https://docassemble.org/img/hello-world-source-code-for-question.png) Note that end users will not see the tab; it will only be shown to users if the interview is in the [Playground](https://docassemble.org/docs/playground.html) , or if the server is [configured as a development server](https://docassemble.org/docs/config.html#debug) . In this example, the information explains that the interview tried to show a [`mandatory`](https://docassemble.org/docs/logic.html#mandatory) question, but couldn’t, because it needed the definition of the variable `planet`. Therefore it looked for a question that offered to define `planet`, and asked that question of the user. Adding some Python code ======================= Now let’s extend the interview by adding a [`code`](https://docassemble.org/docs/code.html) block that makes a calculation based on a number provided by the user. Change the interview code to the following: --- question: Hello, ${ planet }! subquestion: | I surmise that you have no more than ${ inhabitant_count } inhabitants. buttons: - Exit: exit mandatory: True --- question: | What is your planet's name? fields: - Your Planet: planet --- code: | if favorite_number == 42: inhabitant_count = 2 else: inhabitant_count = 2000 + favorite_number * 45 --- question: What is your favorite number? fields: - Number: favorite_number datatype: number --- ([Try it out here](https://demo.docassemble.org/interview?i=docassemble.demo:data/questions/hello3.yml) .) Note that the order in which the [question](https://docassemble.org/docs/questions.html) and [code](https://docassemble.org/docs/code.html) blocks appear in the [YAML](https://en.wikipedia.org/wiki/YAML) does not determine the order in which questions are asked. This is because **docassemble** only asks questions as needed and when needed. The path of this interview is driven by the single [`mandatory`](https://docassemble.org/docs/logic.html#mandatory) question. In order to say “Hello, \_\_\_\_\_\_”, **docassemble** needs to know what `planet` is, so it asks the question “What is your planet’s name?” Then, in order to say “I surmise that you have no more than \_\_\_\_ inhabitants,” **docassemble** needs to know what `inhabitant_count` is, so it runs the [`code`](https://docassemble.org/docs/code.html) that computes `inhabitant_count`. However, in order to compute that, **docassemble** needs to know `favorite_number`, so it asks “What is your favorite number?” Then it knows everything it needs to know in order to display the [`mandatory`](https://docassemble.org/docs/logic.html#mandatory) question. The [`code`](https://docassemble.org/docs/code.html) block contains [Python](https://en.wikipedia.org/wiki/Python_%28programming_language%29) code. The syntax follows the rules of [Python](https://en.wikipedia.org/wiki/Python_%28programming_language%29) . For example, the `==` syntax tests whether the `favorite_number` is 42 or not. The `+` performs addition and the `*` performs multiplication. The `=` sets the value of a variable. Creating a document[¶](https://docassemble.org/docs/helloworld.html#create%20document) ======================================================================================= Now let’s provide the user with a [document](https://docassemble.org/docs/documents.html) by adding an [`attachment`](https://docassemble.org/docs/documents.html#attachment) . --- question: Hello, ${ planet }! subquestion: | I surmise that you have no more than ${ inhabitant_count } inhabitants. attachment: name: A letter for the inhabitants of ${ planet } filename: hello metadata: SingleSpacing: True content: | Dear ${ planet } residents, Hello to all ${ inhabitant_count } of you. Goodbye, Your friend buttons: - Exit: exit mandatory: True --- question: | What is your planet's name? fields: - Your Planet: planet --- code: | if favorite_number == 42: inhabitant_count = 2 else: inhabitant_count = 2000 + favorite_number * 45 --- question: What is your favorite number? fields: - Number: favorite_number datatype: number --- ([Try it out here](https://demo.docassemble.org/interview?i=docassemble.demo:data/questions/hello4.yml) .) This creates a document “from scratch” that is available in PDF or RTF format. The content of the document is contained in the `content` specifier within the [`attachment`](https://docassemble.org/docs/documents.html#attachment) specifier. Let’s also try modifying this interview to use a [DOCX template](https://docassemble.org/docs/documents.html#docx%20template%20file) in order to generate a document that will be available to the user in PDF or DOCX format. To do this, first open a word processing application capable of saving files in DOCX format (e.g., [Microsoft Word](https://en.wikipedia.org/wiki/Microsoft_Word) ). Create a file that looks like the following: ![Word file](https://docassemble.org/img/hello_planet.png) You can format [this file](https://docassemble.org/img/hello_planet.docx) however you like; in this example, we have indented some text and inserted an image. The important thing is that the variable names `planet` and `inhabitant_count` are spelled correctly and are enclosed in double curly brackets. Save the file as a DOCX file (e.g., `hello_planet.docx`). Now you need to make this DOCX file available to your interview by putting the DOCX file in the [Templates](https://docassemble.org/docs/playground.html#templates) folder of your [Playground](https://docassemble.org/docs/playground.html) . To do this, go to the Folders menu and select “Templates.” ![Templates](https://docassemble.org/img/playground-menu-templates.png) Then, go to “Upload a template file” and click “Choose Files.” ![Upload a template file](https://docassemble.org/img/playground-files-upload-template.png) Locate your DOCX file on your computer and select it. Then click [Upload](javascript:return(0)) . Now you should see the DOCX file listed as one of your Templates. ![Template list](https://docassemble.org/img/playground-files-template-listing.png) Then, click [Back](javascript:return(0)) or  [Back to Playground](javascript:return(0)) to go back to the main page of the [Playground](https://docassemble.org/docs/playground.html) . Now you need to edit the interview so that it uses the DOCX file. In the block with the [`attachment`](https://docassemble.org/docs/documents.html#attachment) , replace the `content` specifier with a [`docx template file`](https://docassemble.org/docs/documents.html#docx%20template%20file) specifier that references the file you uploaded. The interview should look like this: --- question: Hello, ${ planet }! subquestion: | I surmise that you have no more than ${ inhabitant_count } inhabitants. attachment: name: A letter for the inhabitants of ${ planet } filename: hello docx template file: hello_planet.docx buttons: - Exit: exit mandatory: True --- question: | What is your planet's name? fields: - Your Planet: planet --- code: | if favorite_number == 42: inhabitant_count = 2 else: inhabitant_count = 2000 + favorite_number * 45 --- question: What is your favorite number? fields: - Number: favorite_number datatype: number --- ([Try it out here](https://demo.docassemble.org/interview?i=docassemble.demo:data/questions/hello6.yml) .) For more information about assembling downloadable documents, see the [documents](https://docassemble.org/docs/documents.html) section. Decorate with an image ====================== Now let’s try [decorating](https://docassemble.org/docs/modifiers.html#decoration) one of the questions with an image. First you need to upload the image you want to use. From the [Playground](https://docassemble.org/docs/playground.html) , go to the Folders menu and select “Static files.” (The files are called “[static](https://docassemble.org/docs/playground.html#static) ” because they do not change, unlike templates, which can produce different files every time.) ![Static files](https://docassemble.org/img/playground-menu-static.png) Then, go to “Upload a static file” and click “Choose Files.” ![Upload a static file](https://docassemble.org/img/playground-files-upload.png) After you select the file (or files) on your computer that you want to upload, click [Upload](javascript:return(0)) . You should now see the file listed as one of the “Static files.” ![File uploaded](https://docassemble.org/img/playground-files-listing.png) In this example, the file is [globe.svg](https://github.com/jhpyle/docassemble/blob/master/docassemble_demo/docassemble/demo/data/static/globe.svg) , a picture of a globe. Now, click [Back](javascript:return(0)) or  [Back to Playground](javascript:return(0)) and add the following to your interview: --- image sets: freepik: images: earth: globe.svg attribution: | Icon made by [Freepik](https://www.flaticon.com/authors/freepik) --- The file [globe.svg](https://github.com/jhpyle/docassemble/blob/master/docassemble_demo/docassemble/demo/data/static/globe.svg) is a copyrighted image obtained from [Freepik](https://www.flaticon.com/authors/freepik) with an attribution-only license. The [`image sets`](https://docassemble.org/docs/initial.html#image%20sets) block facilitates the use of such images. It defines a set of images, called `freepik`, that share a common attribution. All the images you obtain from this source can be added to this image set, and an appropriate attribution line will be added to the screen whenever the image is used. Under `images`, we indicate that the shorthand name we will give our image is `earth`. Now, edit the “What is your planet’s name?” question and add a [`decoration`](https://docassemble.org/docs/modifiers.html#decoration) line referencing `earth`: --- question: | What is your planet's name? fields: - Your Planet: planet decoration: earth --- Now, when you run the interview, you can see that the image “decorates” the question: ![Question with decoration](https://docassemble.org/img/playground-interview-with-image.png) ([Try it out here](https://demo.docassemble.org/interview?i=docassemble.demo:data/questions/hello5.yml) .) For more ideas about how you can extend your interview, check out the examples area of the [Playground](https://docassemble.org/docs/playground.html) . Testing your interview[¶](https://docassemble.org/docs/helloworld.html#testing) ================================================================================ Any time you develop an interview, you will want to test it on multiple devices, and ask other people to test it out and give you feedback. The “Save and Run” button is not the only way to start using an interview in your [Playground](https://docassemble.org/docs/playground.html) . Any interview in the [Playground](https://docassemble.org/docs/playground.html) can be started by visiting its hyperlink. To get this hyperlink, right-click on the [Share](https://docassemble.org/docs/helloworld.html#testing) button and copy the URL to your clipboard. You can share this URL with other people, or bookmark it in your browser. When people visit this URL, they will start an interview session. (Note that this only works if the server you are using is accessible to the user’s device; if you are using a personal computer, your computer’s firewall might prevent other people from accessing it.) Packaging your interview[¶](https://docassemble.org/docs/helloworld.html#packaging) ==================================================================================== So far, we have been running our interview from the [Playground](https://docassemble.org/docs/playground.html) , which is a testing area where we can test things, break things, and “play” with different possibilities. If our interview has reached a point where it is flawless and we want to put it into “production” to that users can use it, we need to move it out of the [Playground](https://docassemble.org/docs/playground.html) and install it in a more “permanent” place. To do this, we bundle our interview into a “package.” Packages can be installed on the same system, or another system, or they can be shared with other developers or posted on [GitHub](https://github.com/) . Go to the Folders menu and select “Packages.” ![Packages menu item](https://docassemble.org/img/playground-menu-packages.png) This will take you to the [“Packages” folder](https://docassemble.org/docs/playground.html#packages) , where you can create and edit packages. ![Packages folder](https://docassemble.org/img/playground-folder-packages.png) If there is an existing package, click the  [Add](javascript:return(0)) button to create a new package. Otherwise, edit the “New” package. Call your new package “helloworld.” ![Package called helloworld](https://docassemble.org/img/playground-packages-example-helloworld.png) On this screen, you can define the characteristics of your package and indicate which resources from the [Playground](https://docassemble.org/docs/playground.html) should be included in the package. Under “Interview files,” select your `hello.yml` file. ![Interview files](https://docassemble.org/img/playground-packages-interview-files.png) Under “Static files,” select your `globe.svg` file. ![Static files](https://docassemble.org/img/playground-packages-static-files.png) Under “Template files,” select your `hello_planet.docx` file. ![Template files](https://docassemble.org/img/playground-packages-template-files.png) If you were creating an actual package for distribution, you would type a careful description of your package and the contents of a “README” file here. But since this is only a tutorial, you can skip that. At the bottom of the screen, you will see some buttons: [Save](javascript:return(0)) [Cancel](javascript:return(0)) Click the [Save](javascript:return(0)) button to save your package. Then, once your package is saved in the system, you will see the following buttons at the top of the screen. ![Buttons](https://docassemble.org/img/playground-packages-buttons-top.png) You will see the following buttons at the bottom of the screen. [Save](javascript:return(0)) [Install](javascript:return(0)) [Download](javascript:return(0)) [Delete](javascript:return(0)) Click the [Install](javascript:return(0)) button. This will take a snapshot of your package, bundle it all up into a [Python](https://en.wikipedia.org/wiki/Python_%28programming_language%29) package, and install that [Python](https://en.wikipedia.org/wiki/Python_%28programming_language%29) package on the computer. Now, users can run the interview using a different URL. If your server is `interview.example.com`, users will be able to run the interview by visiting a URL like: > https://interview.example.com/interview?i=docassemble.helloworld:data/questions/hello.yml Previously, the URL to your interview ended with something like `?i=docassemble.playground1:hello.yml`. That is a link to the “bleeding edge” version of your interview as it exists in the [Playground](https://docassemble.org/docs/playground.html) . The link that ends with `?i=docassemble.helloworld:data/questions/hello.yml` is a link to the snapshot that you installed. This will be the “stable” version of your interview. The “filename” of your interview is `docassemble.helloworld:data/questions/hello.yml`, which tells the server “go into the Python package `docassemble.helloworld`, then go into the `data` directory in that package, then go into the `questions` subdirectory under `data`, and access the file `hello.yml` in that subdirectory.” Alternatively, you can use a more presentable URL, which is like a shorthand version of the above URL: > https://interview.example.com/start/helloworld/hello/ When you run this interview, the URL in the location bar will switch to https://interview.example.com/run/helloworld/hello/. The difference between `start` and `run` is that the `start` URL will always start a new interview, while the `run` version will resume an interview session that has already started. It is also possible to make these URLs even shorter by using the [`dispatch`](https://docassemble.org/docs/config.html#dispatch) Configuration directive. Now that your interview is installed, you can continue to make changes to the [Playground](https://docassemble.org/docs/playground.html) version, while your users are using the snapshot that you installed. When you have made further modifications and you have a new version you want to make available again, you can just click the “Install” button again. For serious deployment of interviews, [it is recommended](https://docassemble.org/docs/development.html) that you use separate “development” and “production” servers. Another thing you can do from the “Packages” folder is click the [Download](javascript:return(0)) button. This will download the package as a ZIP file called `docassemble-helloworld.zip`. If you unpack the contents of the ZIP file, you will have a folder called `docassemble-helloworld`. You can make changes to the files, then re-ZIP the `docassemble-helloworld` folder, and install the revised package on a **docassemble** server using the [Package Management](https://docassemble.org/docs/playground.html) tool. Or, if you want to edit the revised contents of your package in the [Playground](https://docassemble.org/docs/playground.html) again, click the  [Upload](javascript:return(0)) button to upload the contents of your ZIP file into the [Playground](https://docassemble.org/docs/playground.html) . Storing on PyPI[¶](https://docassemble.org/docs/helloworld.html#pypi) ---------------------------------------------------------------------- A **docassemble** package is really just a regular [Python](https://en.wikipedia.org/wiki/Python_%28programming_language%29) package. It follows all of the conventions of [Python](https://en.wikipedia.org/wiki/Python_%28programming_language%29) software package distribution. That means you can share your package on [PyPI](https://pypi.python.org/pypi) , the central repository for [Python](https://en.wikipedia.org/wiki/Python_%28programming_language%29) software. Other people can then install your package on their servers using [pip](https://en.wikipedia.org/wiki/Pip_%28package_manager%29) , just as they would install any [Python](https://en.wikipedia.org/wiki/Python_%28programming_language%29) software. This section of the tutorial will explain how to upload the `docassemble.helloworld` package to [PyPI](https://pypi.python.org/pypi) , but keep in mind that if you try this yourself on a package called `docassemble.helloworld`, you will probably get an error because package names on [PyPI](https://pypi.python.org/pypi) are unique and the `docassemble.helloworld` package has already been uploaded (namely, by me, when I was creating this tutorial). However, these instructions will work if you use a package name of your own invention. First, you need to create an account on [PyPI](https://pypi.python.org/pypi) and obtain an API key. The API key has the form `pypi-` followed by a series of alphanumeric characters. The **docassemble** [configuration](https://docassemble.org/docs/config.html) on your server will need to be set up to allow publishing to [PyPI](https://pypi.python.org/pypi) . To configure this, log in as a user with `admin` [privileges](https://docassemble.org/docs/users.html) , go to “Configuration” on the menu, and add the following to the [configuration](https://docassemble.org/docs/config.html) : pypi: True If this configuration has been made, you can go to “Profile” from the menu and scroll down to the “PyPI Username” and “PyPI Password” fields. Fill in these fields with `__token__` as the username and your API key as the password. (This is how authentication works with [`twine`](https://pypi.org/project/twine/) .) ![PyPI username and password](https://docassemble.org/img/profile-pypi-username-password.png) Then, go to the [“Packages” folder](https://docassemble.org/docs/playground.html#packages) of the **docassemble** [Playground](https://docassemble.org/docs/playground.html) and open your `docassemble-helloworld` package that you created [above](https://docassemble.org/docs/helloworld.html#packaging) . At the bottom of the screen you will see a message about whether the package is published on [PyPI](https://pypi.python.org/pypi) and/or [GitHub](https://github.com/) . ![PyPI Info](https://docassemble.org/img/playground-packages-not-published-yet.png) Press the [PyPI](javascript:return(0)) button to publish the package to [PyPI](https://pypi.python.org/pypi) . When the publishing is done, you will see an informational message with the output of the uploading commands. Check this message to see if there are any errors. If the publishing was successful, then at the bottom of the page describing your package, you should see a message that the package now exists on [PyPI](https://pypi.python.org/pypi) . (However, sometimes the [PyPI](https://pypi.python.org/pypi) server is slow to reflect the existence of the package, so you may need to give it a minute or two.) ![PyPI Info](https://docassemble.org/img/playground-packages-pypi-published.png) If you click the link, you can see what the package looks like on the [PyPI](https://pypi.python.org/pypi) web site. ![PyPI page](https://docassemble.org/img/pypi-helloworld-page.png) Now, on the **docassemble** menu (of this server or another server), you can go to Package Management and [install](https://docassemble.org/docs/packages.html) the package by specifying a “Package on PyPI.” ![PyPI Install](https://docassemble.org/img/update-package-pypi.png) For more information about uploading packages to [PyPI](https://pypi.python.org/pypi) , see the [PyPI subsection](https://docassemble.org/docs/packages.html#pypi) of the [packages](https://docassemble.org/docs/packages.html) section. Storing on Github[¶](https://docassemble.org/docs/helloworld.html#github) -------------------------------------------------------------------------- You can also share your package on [GitHub](https://github.com/) , a popular [version control system](https://en.wikipedia.org/wiki/Version_control) that facilitates collaboration. You will need an account on [GitHub](https://github.com/) . If you do not have one, you can [create one](https://github.com/join) . Your **docassemble** configuration will need to be configured to allow [GitHub](https://github.com/) integration. The instructions for setting that up are [in the installation section](https://docassemble.org/docs/installation.html#github) . Once your server allows [GitHub integration](https://docassemble.org/docs/packages.html#github) , you can go to “Profile” on the menu, open “Other settings,” and click the link for “GitHub integration.” Follow the instructions to connect your [GitHub](https://github.com/) account with your **docassemble** account. Once you have connected your [GitHub](https://github.com/) account with your **docassemble** account, go to the [“Packages” folder](https://docassemble.org/docs/playground.html#packages) of the **docassemble** [Playground](https://docassemble.org/docs/playground.html) and open your `docassemble-helloworld` package that you created [above](https://docassemble.org/docs/helloworld.html#packaging) . At the bottom of the screen you will see a message about whether the package is published on [GitHub](https://github.com/) . ![GitHub Info](https://docassemble.org/img/playground-packages-github-not-published-yet.png) Press the [GitHub](javascript:return(0)) button. You will be asked for a “commit message.” This is a brief, one-line message that describes the changes made to your package since the last time you “committed” changes. Each “commit” is like a snapshot, and the history of “commit” messages is a record of the development of your project. You can give your first commit a simple name: ![Commit](https://docassemble.org/img/playground-packages-github-commit-helloworld.png) However, your subsequent “commits” should have meaningful names that describe succinctly how that snapshot is different from the previous snapshot. You should also use the README text box to describe to other people the history of all of your changes. When you press the “Commit” button, your package will be “pushed” to a “repository” in your [GitHub](https://github.com/) account. If a repository does not already exist on [GitHub](https://github.com/) with the name of your package, a new repository will be created. When the uploading is done, you will see an informational message with the output of the uploading commands. Check this message to see if there are any errors. If the publishing was successful, then at the bottom of the page describing your package, you should see a message that the package now exists on [GitHub](https://github.com/) . ![PyPI Info](https://docassemble.org/img/playground-packages-github-published.png) If you click the link, you can see what the package looks like on [GitHub](https://github.com/) : ![GitHub Repository](https://docassemble.org/img/github-helloworld-repository.png) Now, on the **docassemble** menu, you can go to Package Management and [install](https://docassemble.org/docs/packages.html) the package using its [GitHub](https://github.com/) URL. ![GitHub Install](https://docassemble.org/img/update-package-github.png) For more information about uploading packages to [GitHub](https://github.com/) , see the [GitHub subsection](https://docassemble.org/docs/packages.html#github) of the [packages](https://docassemble.org/docs/packages.html) section. * * * --- # Question blocks [Edit](https://github.com/jhpyle/docassemble/blob/gh-pages/_docs/questions.md "Edit this page on GitHub") Question blocks =============== Contents -------- * [1 The question block](https://docassemble.org/docs/questions.html#question) * [2 The subquestion specifier](https://docassemble.org/docs/questions.html#subquestion) * [3 The under specifier](https://docassemble.org/docs/questions.html#under) * [4 The pre specifier](https://docassemble.org/docs/questions.html#pre) * [5 The post specifier](https://docassemble.org/docs/questions.html#post) * [6 The right specifier](https://docassemble.org/docs/questions.html#right) * [7 The css class specifier](https://docassemble.org/docs/questions.html#css%20class) * [8 The table css class specifier](https://docassemble.org/docs/questions.html#table%20css%20class) * [9 The question metadata specifier](https://docassemble.org/docs/questions.html#question%20metadata) * [10 Using questions to set variables](https://docassemble.org/docs/questions.html#tocAnchor-1-10) * [10.1 True or false: yesno and noyes](https://docassemble.org/docs/questions.html#tocAnchor-1-10-1) * [10.2 Multiple choice: choices or buttons](https://docassemble.org/docs/questions.html#choices) * [10.3 Acknowledgement button: continue button field](https://docassemble.org/docs/questions.html#tocAnchor-1-10-3) * [10.4 One or more fill-in fields: fields](https://docassemble.org/docs/questions.html#tocAnchor-1-10-4) * [10.5 User’s signature: signature](https://docassemble.org/docs/questions.html#tocAnchor-1-10-5) * [11 Ending screens](https://docassemble.org/docs/questions.html#ending%20screens) * [11.1 Special buttons](https://docassemble.org/docs/questions.html#special%20buttons) * [11.2 Mixing special buttons with buttons that set a variable](https://docassemble.org/docs/questions.html#special%20mixed) * [11.3 Special screens: event](https://docassemble.org/docs/questions.html#event) * [12 Include additional buttons on the screen](https://docassemble.org/docs/questions.html#action%20buttons) * [13 Customizing screen parts](https://docassemble.org/docs/questions.html#screen%20parts) In the **docassemble** web app, every screen that a user sees is generated by a [`question`](https://docassemble.org/docs/questions.html#question) block, which is a section of [YAML](https://en.wikipedia.org/wiki/YAML) code that contains a [`question`](https://docassemble.org/docs/questions.html#question) specifier. (Well, you can also generate a screen using the [`message()` function](https://docassemble.org/docs/functions.html#message) , but that is an advanced topic.) All blocks in an interview file must either be [initial blocks](https://docassemble.org/docs/initial.html) , [code blocks](https://docassemble.org/docs/code.html) , or contain a [`question`](https://docassemble.org/docs/questions.html#question) specifier. The `question` block[¶](https://docassemble.org/docs/questions.html#question) ============================================================================== question: | What is the airspeed velocity of an unladen swallow? fields: - Velocity: swallow_velocity [GitHub](https://github.com/jhpyle/docassemble/blob/master/docassemble_base/docassemble/base/data/questions/examples/question.yml "Open on GitHub") [![Screenshot of question example](https://docassemble.org/img/examples/question.png)](https://demo.docassemble.org/interview?i=docassemble.base:data/questions/examples/question.yml&reset=1 "Click to try this interview") By including the above [YAML](https://en.wikipedia.org/wiki/YAML) block in your interview file, you are telling **docassemble** that if it ever needs to know the value of `swallow_velocity`, it should ask the user the question “What is the airspeed velocity of an unladen swallow?” and provide the user with an input box labeled “Velocity” in which the user can type the answer. Like many things in **docassemble**, the `question` specifier can contain [Markdown](https://daringfireball.net/projects/markdown/) and [Mako](https://www.makotemplates.org/) . For example: question: | What is the *airspeed* velocity of an unladen ${ african_or_european } swallow? fields: - Velocity: swallow_velocity [GitHub](https://github.com/jhpyle/docassemble/blob/master/docassemble_base/docassemble/base/data/questions/examples/question-markup.yml "Open on GitHub") [![Screenshot of question-markup example](https://docassemble.org/img/examples/question-markup.png)](https://demo.docassemble.org/interview?i=docassemble.base:data/questions/examples/question-markup.yml&reset=1 "Click to try this interview") In this example, the word “airspeed” is italicized, using the [Markdown](https://daringfireball.net/projects/markdown/) syntax for italics. The type of swallow is given by a variable (`african_or_european`), the value of which (`"African"`) is incorporated using [Mako](https://www.makotemplates.org/) . (One of the features of [Mako](https://www.makotemplates.org/) is that anything enclosed in `${ ... }` is evaluated as [Python](https://en.wikipedia.org/wiki/Python_%28programming_language%29) code.) The `subquestion` specifier[¶](https://docassemble.org/docs/questions.html#subquestion) ======================================================================================== The optional `subquestion` adds text underneath the [`question`](https://docassemble.org/docs/questions.html#question) . It is typically used to explain the question in more detail, if such an explanation is necessary. question: | What is the airspeed velocity of an unladen swallow? subquestion: Be careful how you answer. fields: - Velocity: swallow_velocity [GitHub](https://github.com/jhpyle/docassemble/blob/master/docassemble_base/docassemble/base/data/questions/examples/subquestion.yml "Open on GitHub") [![Screenshot of subquestion example](https://docassemble.org/img/examples/subquestion.png)](https://demo.docassemble.org/interview?i=docassemble.base:data/questions/examples/subquestion.yml&reset=1 "Click to try this interview") The `under` specifier[¶](https://docassemble.org/docs/questions.html#under) ============================================================================ The optional `under` specifier adds text underneath the buttons. question: | What is the airspeed velocity of an unladen swallow? fields: - Velocity: swallow_velocity under: | Note: if you did not catch this movie reference, you need to improve your cultural literacy. [GitHub](https://github.com/jhpyle/docassemble/blob/master/docassemble_base/docassemble/base/data/questions/examples/under.yml "Open on GitHub") [![Screenshot of under example](https://docassemble.org/img/examples/under.png)](https://demo.docassemble.org/interview?i=docassemble.base:data/questions/examples/under.yml&reset=1 "Click to try this interview") The `pre` specifier[¶](https://docassemble.org/docs/questions.html#pre) ======================================================================== The optional `pre` specifier adds text before the `question`. question: | What is the airspeed velocity of an unladen swallow? fields: - Velocity: swallow_velocity pre: | Note: if you do not catch the movie reference in this question, you need to improve your cultural literacy. [GitHub](https://github.com/jhpyle/docassemble/blob/master/docassemble_base/docassemble/base/data/questions/examples/pre.yml "Open on GitHub") [![Screenshot of pre example](https://docassemble.org/img/examples/pre.png)](https://demo.docassemble.org/interview?i=docassemble.base:data/questions/examples/pre.yml&reset=1 "Click to try this interview") The `post` specifier[¶](https://docassemble.org/docs/questions.html#post) ========================================================================== The optional `post` specifier adds text after the `question`. question: | What is the airspeed velocity of an unladen swallow? fields: - Velocity: swallow_velocity under: | Note: if you did not catch this movie reference, you need to improve your cultural literacy. post: | This is the `post`, which comes after `under`. [GitHub](https://github.com/jhpyle/docassemble/blob/master/docassemble_base/docassemble/base/data/questions/examples/post.yml "Open on GitHub") [![Screenshot of post example](https://docassemble.org/img/examples/post.png)](https://demo.docassemble.org/interview?i=docassemble.base:data/questions/examples/post.yml&reset=1 "Click to try this interview") The `right` specifier[¶](https://docassemble.org/docs/questions.html#right) ============================================================================ The optional `right` specifier adds text on the right-hand side of the screen, or below the question on small screens. question: | What is the airspeed velocity of an unladen swallow? fields: - Velocity: swallow_velocity right: | ### Note If you did not catch this movie reference, you need to improve your cultural literacy. [GitHub](https://github.com/jhpyle/docassemble/blob/master/docassemble_base/docassemble/base/data/questions/examples/right-centered.yml "Open on GitHub") [![Screenshot of right-centered example](https://docassemble.org/img/examples/right-centered.png)](https://demo.docassemble.org/interview?i=docassemble.base:data/questions/examples/right-centered.yml&reset=1 "Click to try this interview") If your interview has questions that use the `right` specifier, you might want to set the [`centered`](https://docassemble.org/docs/initial.html#centered) feature to `False` so that the text on the right is wider. features: centered: False --- question: | What is the airspeed velocity of an unladen swallow? fields: - Velocity: swallow_velocity right: | ### Note If you did not catch this movie reference, you need to improve your cultural literacy. [GitHub](https://github.com/jhpyle/docassemble/blob/master/docassemble_base/docassemble/base/data/questions/examples/right.yml "Open on GitHub") [![Screenshot of right example](https://docassemble.org/img/examples/right.png)](https://demo.docassemble.org/interview?i=docassemble.base:data/questions/examples/right.yml&reset=1 "Click to try this interview") The `css class` specifier[¶](https://docassemble.org/docs/questions.html#css%20class) ====================================================================================== The optional `css class` specifier can be used to set a [CSS](https://en.wikipedia.org/wiki/CSS) class for the `` of the screen of a question. css class: first-question mandatory: True question: | View the source and look for the word `first-question`. [GitHub](https://github.com/jhpyle/docassemble/blob/master/docassemble_base/docassemble/base/data/questions/examples/css-class.yml "Open on GitHub") [![Screenshot of css-class example](https://docassemble.org/img/examples/css-class.png)](https://demo.docassemble.org/interview?i=docassemble.base:data/questions/examples/css-class.yml&reset=1 "Click to try this interview") The `table css class` specifier[¶](https://docassemble.org/docs/questions.html#table%20css%20class) ==================================================================================================== The optional `table css class` specifier can be used to set the [CSS](https://en.wikipedia.org/wiki/CSS) class of any [Markdown](https://daringfireball.net/projects/markdown/) \-generated tables that appear in the question. There is no feature in [Markdown](https://daringfireball.net/projects/markdown/) for specifying a class of a table. The class of tables can be customized at the `question` level, or at the interview level with [`default screen parts`](https://docassemble.org/docs/initial.html#default%20screen%20parts) , or you can set a server-wide default with the `table css class` [Configuration](https://docassemble.org/docs/config.html) directive. The `question metadata` specifier[¶](https://docassemble.org/docs/questions.html#question%20metadata) ====================================================================================================== The optional `question metadata` specifier allows you to associate custom metadata with a `question`. You can use any format [YAML](https://en.wikipedia.org/wiki/YAML) will accept, and you can use [Mako](https://www.makotemplates.org/) in text. The metadata will appear in the [JSON](https://en.wikipedia.org/wiki/JSON) representation of the `question`. question: | What is your favorite fruit? fields: - Fruit: favorite_fruit question metadata: inspiration: Sophocles antagonists: - Frozen vegetables - Roasted tree nuts - ${ favorite_automobile } Using questions to set variables ================================ Here is a brief summary of the types of questions that can be asked. More detail about how these question types work is provided in the [next section](https://docassemble.org/docs/fields.html) . True or false: `yesno` and `noyes` ---------------------------------- A [`yesno`](https://docassemble.org/docs/fields.html#yesno) question will set a variable to `True` or `False` when a Yes or No button is pressed. [`noyes`](https://docassemble.org/docs/fields.html#noyes) does the opposite. question: | Are you at least 18 years of age? yesno: over_eighteen [GitHub](https://github.com/jhpyle/docassemble/blob/master/docassemble_base/docassemble/base/data/questions/examples/yesno.yml "Open on GitHub") [![Screenshot of yesno example](https://docassemble.org/img/examples/yesno.png)](https://demo.docassemble.org/interview?i=docassemble.base:data/questions/examples/yesno.yml&reset=1 "Click to try this interview") Multiple choice: `choices` or `buttons`[¶](https://docassemble.org/docs/questions.html#choices) ------------------------------------------------------------------------------------------------ You can ask a multiple-choice question by providing a list of [`choices`](https://docassemble.org/docs/fields.html#field%20with%20choices) : question: | What type of shoes do you wear? field: target_variable choices: - Sneakers - Sandals - Clogs - Other [GitHub](https://github.com/jhpyle/docassemble/blob/master/docassemble_base/docassemble/base/data/questions/examples/choices.yml "Open on GitHub") [![Screenshot of choices example](https://docassemble.org/img/examples/choices.png)](https://demo.docassemble.org/interview?i=docassemble.base:data/questions/examples/choices.yml&reset=1 "Click to try this interview") Or, if you would prefer to use one-click buttons instead of “radio buttons” in combination with a “Continue” button, use can use [`buttons`](https://docassemble.org/docs/fields.html#field%20with%20buttons) instead of [`choices`](https://docassemble.org/docs/fields.html#field%20with%20choices) . question: | What type of belly button do you have? field: target_variable buttons: - Innie - Outie - No belly button [GitHub](https://github.com/jhpyle/docassemble/blob/master/docassemble_base/docassemble/base/data/questions/examples/buttons.yml "Open on GitHub") [![Screenshot of buttons example](https://docassemble.org/img/examples/buttons.png)](https://demo.docassemble.org/interview?i=docassemble.base:data/questions/examples/buttons.yml&reset=1 "Click to try this interview") The variable indicated by [`field`](https://docassemble.org/docs/fields.html#field%20with%20choices) will be set to the value supplied in the [`choices`](https://docassemble.org/docs/fields.html#field%20with%20choices) /[`buttons`](https://docassemble.org/docs/fields.html#field%20with%20buttons) list. Acknowledgement button: `continue button field` ----------------------------------------------- If you simply want the user to acknowledge something by clicking “Continue,” provide a [`continue button field`](https://docassemble.org/docs/fields.html#field%20continue) . The variable indicated by [`continue button field`](https://docassemble.org/docs/fields.html#field%20continue) will be set to `True` when the user clicks “Continue.” continue button field: target_variable question: | Welcome to the interview. subquestion: | When you are ready to begin, press Continue. [GitHub](https://github.com/jhpyle/docassemble/blob/master/docassemble_base/docassemble/base/data/questions/examples/continue.yml "Open on GitHub") [![Screenshot of continue example](https://docassemble.org/img/examples/continue.png)](https://demo.docassemble.org/interview?i=docassemble.base:data/questions/examples/continue.yml&reset=1 "Click to try this interview") One or more fill-in fields: [`fields`](https://docassemble.org/docs/fields.html#fields) ---------------------------------------------------------------------------------------- You can ask the user to fill in multiple fields using [`fields`](https://docassemble.org/docs/fields.html#fields) . question: | What are your favorite things to eat? subquestion: | Please be specific. fields: - Vegetable: target_variable - Fruit: other_target_variable [GitHub](https://github.com/jhpyle/docassemble/blob/master/docassemble_base/docassemble/base/data/questions/examples/text-field.yml "Open on GitHub") [![Screenshot of text-field example](https://docassemble.org/img/examples/text-field.png)](https://demo.docassemble.org/interview?i=docassemble.base:data/questions/examples/text-field.yml&reset=1 "Click to try this interview") There are many other types of input that you can gather with [`fields`](https://docassemble.org/docs/fields.html#fields) , including [large text areas](https://docassemble.org/docs/fields.html#area) , [file uploads](https://docassemble.org/docs/fields.html#file) , [radio buttons](https://docassemble.org/docs/fields.html#radio) , and [checkboxes](https://docassemble.org/docs/fields.html#fields%20checkboxes) . There are a variety of ways you can insert text into the list of fields to help guide the user. If you know [HTML](https://en.wikipedia.org/wiki/HTML) , you can insert arbitrary [HTML](https://docassemble.org/docs/fields.html#html) , [CSS](https://docassemble.org/docs/modifiers.html#css) , and [JavaScript](https://docassemble.org/docs/modifiers.html#script) . Using the [`show if`](https://docassemble.org/docs/fields.html#show%20if) feature, you can cause fields to appear or disappear depending on the values of other fields. User’s signature: `signature` ----------------------------- You can ask the user to write his or her signature using [`signature`](https://docassemble.org/docs/fields.html#signature) : question: | Sign your name subquestion: | By signing your name, you agree to our terms and conditions. signature: target_variable under: | ${ user } [GitHub](https://github.com/jhpyle/docassemble/blob/master/docassemble_base/docassemble/base/data/questions/examples/signature.yml "Open on GitHub") [![Screenshot of signature example](https://docassemble.org/img/examples/signature.png)](https://demo.docassemble.org/interview?i=docassemble.base:data/questions/examples/signature.yml&reset=1 "Click to try this interview") The signature will be stored as an image file in the variable indicated by [`signature`](https://docassemble.org/docs/fields.html#signature) . Ending screens[¶](https://docassemble.org/docs/questions.html#ending%20screens) ================================================================================ Sometimes, the purpose of your [`question`](https://docassemble.org/docs/questions.html#question) is not to gather information but to present an end screen to the user. You can create such “questions” by marking them as [`mandatory`](https://docassemble.org/docs/logic.html#mandatory) : question: | Congratulations! subquestion: | You are all done with the interview. mandatory: True [GitHub](https://github.com/jhpyle/docassemble/blob/master/docassemble_base/docassemble/base/data/questions/examples/terminal-screen.yml "Open on GitHub") [![Screenshot of terminal-screen example](https://docassemble.org/img/examples/terminal-screen.png)](https://demo.docassemble.org/interview?i=docassemble.base:data/questions/examples/terminal-screen.yml&reset=1 "Click to try this interview") If you have more than one possible ending screen in your interview, use the [`event`](https://docassemble.org/docs/questions.html#event) feature described below. Special buttons[¶](https://docassemble.org/docs/questions.html#special%20buttons) ---------------------------------------------------------------------------------- Using the [`buttons`](https://docassemble.org/docs/questions.html#buttons) or [`choices`](https://docassemble.org/docs/questions.html#choices) syntax described above, you can add special buttons to a screen. These buttons are special because they do not set a variable. These buttons are particularly useful on “terminal” screens. question: We are all done. buttons: - Exit: exit - Restart: restart mandatory: True [GitHub](https://github.com/jhpyle/docassemble/blob/master/docassemble_base/docassemble/base/data/questions/examples/exit-buttons.yml "Open on GitHub") [![Screenshot of exit-buttons example](https://docassemble.org/img/examples/exit-buttons.png)](https://demo.docassemble.org/interview?i=docassemble.base:data/questions/examples/exit-buttons.yml&reset=1 "Click to try this interview") The above example allows the user to “exit” the interview (i.e., to be redirected to a different web site) or “restart” the interview (i.e., go back to the beginning, with all of the answers forgotten). There are six special button functions: * `restart` * `new_session` * `exit` * `logout` * `exit_logout` * `leave` * `continue` * `refresh` * `signin` `restart` resets the user’s variable store, except that any parameters that were originally passed through as URL parameters will be used again. The user is redirected to the first question of the interview. `new_session` does not disturb the current interview session, but starts a new session for the same interview, with the same URL parameters and Referer. `exit` means that the user’s variable store will be erased and the user will be redirected either to the URL given by the associated `url` text, or if no `url` is defined, to the [`exit url`](https://docassemble.org/docs/initial.html#exit%20url) defined in the [`metadata`](https://docassemble.org/docs/initial.html#metadata) , or if that does not defined, then to the [`exitpage`](https://docassemble.org/docs/config.html#exitpage) defined in the [configuration](https://docassemble.org/docs/config.html) . If the user tries to come back to the interview again, he will start the interview again, as though it had never been started. Original URL parameters will be lost. For example: question: | Congratulations, you found Nemo! buttons: - Try again: restart - Learn More: exit url: https://en.wikipedia.org/wiki/Amphiprioninae mandatory: True [GitHub](https://github.com/jhpyle/docassemble/blob/master/docassemble_base/docassemble/base/data/questions/examples/exit-url.yml "Open on GitHub") [![Screenshot of exit-url example](https://docassemble.org/img/examples/exit-url.png)](https://demo.docassemble.org/interview?i=docassemble.base:data/questions/examples/exit-url.yml&reset=1 "Click to try this interview") [Mako](https://www.makotemplates.org/) can be used in the `url` text. `logout` logs the user out, if the user is logged in. `exit_logout` does the same thing as `exit`, except that it also logs the user out, if the user is logged in. `leave` works like `exit` except that the user’s variable store will be left intact. This means that if the user comes back to the interview again, he will pick up where he left off. `continue` means that **docassemble** will move on from the question without really doing anything. Here is an example of when it is useful: mandatory: True code: | menu_items = [ action_menu_item('Visit Cow', 'see_cow') ] --- event: see_cow question: | Moo! subquestion: | [FILE cow.jpg] Cow illustration designed by [Freepik](http://www.freepik.com/free-photos-vectors/animal) buttons: - Continue: continue --- question: Welcome to the interview subquestion: | Check out the menu in the upper-right corner. mandatory: True [GitHub](https://github.com/jhpyle/docassemble/blob/master/docassemble_base/docassemble/base/data/questions/examples/menu-item.yml "Open on GitHub") [![Screenshot of menu-item example](https://docassemble.org/img/examples/menu-item.png)](https://demo.docassemble.org/interview?i=docassemble.base:data/questions/examples/menu-item.yml&reset=1 "Click to try this interview") This example uses the [actions](https://docassemble.org/docs/functions.html#actions) feature and the [`menu_items` special variable](https://docassemble.org/docs/special.html#menu_items) to present a special screen that shows a picture. This screen does not set any variable, but the user can click the button to “continue” with the normal course of the interview. The `continue` button can also be used with a `question` that is shown because it is [`mandatory`](https://docassemble.org/docs/logic.html#mandatory) . mandatory: True question: | Please note that this app is only right for you if you are a bear. buttons: - I am not a bear: exit - Continue: continue --- mandatory: True question: | Instructions for bears subquestion: | Grip the doorknob and turn it. Then look for the pantry. That is where they keep the food. [GitHub](https://github.com/jhpyle/docassemble/blob/master/docassemble_base/docassemble/base/data/questions/examples/mandatory-continue.yml "Open on GitHub") [![Screenshot of mandatory-continue example](https://docassemble.org/img/examples/mandatory-continue.png)](https://demo.docassemble.org/interview?i=docassemble.base:data/questions/examples/mandatory-continue.yml&reset=1 "Click to try this interview") While using `continue` can be useful sometimes, it is generally not a good idea to structure interviews around `question`s that use `continue`. These `question`s cannot use the [`generic object` modifier](https://docassemble.org/docs/fields.html#generic) or [index variables](https://docassemble.org/docs/fields.html#index%20variables) . `refresh` re-runs the [interview logic](https://docassemble.org/docs/logic.html) . It has much the same effect as refreshing the page in the browser. It is useful in multi-user interviews when the user is waiting for another user to finish entering information. It can also be useful in interviews that use external data sources. mandatory: True code: | tell_time --- event: tell_time question: | The current time is ${ current_datetime().format_time() }. buttons: - Tell me again: refresh [GitHub](https://github.com/jhpyle/docassemble/blob/master/docassemble_base/docassemble/base/data/questions/examples/refresh.yml "Open on GitHub") [![Screenshot of refresh example](https://docassemble.org/img/examples/refresh.png)](https://demo.docassemble.org/interview?i=docassemble.base:data/questions/examples/refresh.yml&reset=1 "Click to try this interview") `signin` redirects the user to the **docassemble** sign-in page. mandatory: True code: | if user_logged_in(): goodbye_page else: sign_in_page --- question: | Please sign in buttons: - Sign in: signin sets: sign_in_page [GitHub](https://github.com/jhpyle/docassemble/blob/master/docassemble_base/docassemble/base/data/questions/examples/signin.yml "Open on GitHub") [![Screenshot of signin example](https://docassemble.org/img/examples/signin.png)](https://demo.docassemble.org/interview?i=docassemble.base:data/questions/examples/signin.yml&reset=1 "Click to try this interview") Instead of using [`buttons`](https://docassemble.org/docs/questions.html#buttons) , you can use [`choices`](https://docassemble.org/docs/questions.html#choices) to get a radio list instead of a selection of buttons. question: We are all done. choices: - Exit: exit - Restart: restart mandatory: True [GitHub](https://github.com/jhpyle/docassemble/blob/master/docassemble_base/docassemble/base/data/questions/examples/exit-choices.yml "Open on GitHub") [![Screenshot of exit-choices example](https://docassemble.org/img/examples/exit-choices.png)](https://demo.docassemble.org/interview?i=docassemble.base:data/questions/examples/exit-choices.yml&reset=1 "Click to try this interview") The functionality is the same. The [`command()`](https://docassemble.org/docs/functions.html#command) function allows you to do similar things with Python code. In addition, the [`url_of()`](https://docassemble.org/docs/functions.html#url_of) function provides URLs that accomplish a similar purposes. Mixing special buttons with buttons that set a variable[¶](https://docassemble.org/docs/questions.html#special%20mixed) ------------------------------------------------------------------------------------------------------------------------ Note that since “special” buttons do not set a variable, you should not include a [`field`](https://docassemble.org/docs/fields.html#field%20with%20choices) in the [`question`](https://docassemble.org/docs/questions.html#question) . If you include a [`field`](https://docassemble.org/docs/fields.html#field%20with%20choices) in the [`question`](https://docassemble.org/docs/questions.html#question) , **docassemble** will assume you are creating an ordinary [multiple choice question](https://docassemble.org/docs/questions.html#buttons) . If you wish to mix “special” buttons with buttons that set a variable, you can use the [`command()`](https://docassemble.org/docs/functions.html#command) function in [`code`](https://docassemble.org/docs/code.html#code) to trigger the same effects as clicking on a “special” button. The following example uses a [`mandatory`](https://docassemble.org/docs/logic.html#mandatory) [`code`](https://docassemble.org/docs/code.html#code) block to determine the course of the interview. Depending on the answer to an ordinary [multiple choice question](https://docassemble.org/docs/questions.html#buttons) , it either exits from the interview or proceeds to another screen. mandatory: True code: | if user_choice == 'exit': command('exit') elif user_choice == 'proceed': final_screen --- question: | Warning! subquestion: | Proceeding with this interview may result in despair-inducing levels of liability. field: user_choice buttons: - Exit: exit - Keep going: proceed --- event: final_screen question: | Hey, I warned you. [GitHub](https://github.com/jhpyle/docassemble/blob/master/docassemble_base/docassemble/base/data/questions/examples/exit-buttons-mixed-code.yml "Open on GitHub") [![Screenshot of exit-buttons-mixed-code example](https://docassemble.org/img/examples/exit-buttons-mixed-code.png)](https://demo.docassemble.org/interview?i=docassemble.base:data/questions/examples/exit-buttons-mixed-code.yml&reset=1 "Click to try this interview") Another alternative is to use [multiple-choice buttons that run code](https://docassemble.org/docs/fields.html#code%20button) : question: | Warning! subquestion: | Proceeding with this interview may result in despair-inducing levels of liability. buttons: - I understand: code: | attitude = 'careful' - I do not care: code: | attitude = 'reckless' - Get me out of here: exit --- mandatory: true question: | % if attitude == 'reckless': You are foolish! % else: Ok, we are proceeding with caution. % endif [GitHub](https://github.com/jhpyle/docassemble/blob/master/docassemble_base/docassemble/base/data/questions/examples/exit-buttons-mixed.yml "Open on GitHub") [![Screenshot of exit-buttons-mixed example](https://docassemble.org/img/examples/exit-buttons-mixed.png)](https://demo.docassemble.org/interview?i=docassemble.base:data/questions/examples/exit-buttons-mixed.yml&reset=1 "Click to try this interview") Special screens: `event`[¶](https://docassemble.org/docs/questions.html#event) ------------------------------------------------------------------------------- Some screens are shown to the user when a special event occurs. For example, if you have a [multi-user interview](https://docassemble.org/docs/roles.html) and the interview reaches a point where the user cannot proceed until the other interviewee answers a question, the interview will present the user with a [`question`](https://docassemble.org/docs/questions.html#question) that explains why he or she needs to wait. Or, you might want to provide the user with the ability to review his or her answers on a single screen, using the [`review`](https://docassemble.org/docs/fields.html#review) functionality. The [`event`](https://docassemble.org/docs/fields.html#event) specifier advertises to the interview logic that the question should be asked if a special event occurs. question: | This is a special screen. event: show_special_screen [GitHub](https://github.com/jhpyle/docassemble/blob/master/docassemble_base/docassemble/base/data/questions/examples/event-example.yml "Open on GitHub") [![Screenshot of event-example example](https://docassemble.org/img/examples/event-example.png)](https://demo.docassemble.org/interview?i=docassemble.base:data/questions/examples/event-example.yml&reset=1 "Click to try this interview") This specifier can be used to indicate an [ending screen](https://docassemble.org/docs/questions.html#ending%20screens) , where your interview has more than one possible ending screen and you use [interview logic](https://docassemble.org/docs/logic.html) to direct the user to the appropriate screen. question: | Which door do you choose? field: door_choice choices: - Door Number 1 - Door Number 2 --- mandatory: True code: | if door_choice == 'Door Number 1': good_luck if door_choice == 'Door Number 2': bad_luck --- question: | You walk into a field of clover. event: good_luck --- question: | You walk into a stinky swamp. event: bad_luck [GitHub](https://github.com/jhpyle/docassemble/blob/master/docassemble_base/docassemble/base/data/questions/examples/doors.yml "Open on GitHub") [![Screenshot of doors example](https://docassemble.org/img/examples/doors.png)](https://demo.docassemble.org/interview?i=docassemble.base:data/questions/examples/doors.yml&reset=1 "Click to try this interview") In this example, `good_luck` and `bad_luck` are actually names of [Python](https://en.wikipedia.org/wiki/Python_%28programming_language%29) variables. However, they are [Python](https://en.wikipedia.org/wiki/Python_%28programming_language%29) variables that will never be defined. If a reference to these variables is made, as it is in the [`mandatory`](https://docassemble.org/docs/logic.html#mandatory) [`code`](https://docassemble.org/docs/code.html#code) block, **docassemble** will locate the `good_luck` and `bad_luck` questions, just as it looks for questions that offer to define any variable. See [interview logic](https://docassemble.org/docs/logic.html) for more information about how to give direction to your interview by adding [`code`](https://docassemble.org/docs/code.html#code) blocks that are marked with the [`mandatory`](https://docassemble.org/docs/logic.html#mandatory) modifier. The `event` specifier is also used to create screens that the user can reach from the menu or from hyperlinks embedded in question text. For more information, see [`event`](https://docassemble.org/docs/fields.html#event) , [`url_action()`](https://docassemble.org/docs/functions.html#url_action) , [`process_action()`](https://docassemble.org/docs/functions.html#process_action) , [`action_menu_item()`](https://docassemble.org/docs/functions.html#action_menu_item) , and [`menu_items`](https://docassemble.org/docs/special.html#menu_items) . Include additional buttons on the screen[¶](https://docassemble.org/docs/questions.html#action%20buttons) ========================================================================================================== In many [`question`](https://docassemble.org/docs/questions.html#question) s, the only button the user can click is “Continue.” You can set a variable using a [`buttons`](https://docassemble.org/docs/fields.html#field%20with%20buttons) specifier with a `field`. You can also use a [`buttons`](https://docassemble.org/docs/questions.html#buttons) screen that does not set a variable. You can also use [`question back button`](https://docassemble.org/docs/initial.html#question%20back%20button) to move the “Back” button to the buttons area, or [`question help button`](https://docassemble.org/docs/initial.html#question%20help%20button) to move the interview help button to the buttons area. If you want to include additional button choices on a screen, you can use `action buttons`. When the user clicks a button it will run an [action](https://docassemble.org/docs/functions.html#actions) in the interview. question: | I will give you ${ quantity_noun(num_apples, 'apple') }. field: show_quantity action buttons: - label: More action: change_quantity arguments: amount: 1 color: success css class: quantity-up icon: chevron-up - label: Less action: change_quantity arguments: amount: -1 color: danger css class: quantity-down icon: chevron-down --- event: change_quantity code: | num_apples += action_argument('amount') [GitHub](https://github.com/jhpyle/docassemble/blob/master/docassemble_base/docassemble/base/data/questions/examples/action-buttons.yml "Open on GitHub") [![Screenshot of action-buttons example](https://docassemble.org/img/examples/action-buttons.png)](https://demo.docassemble.org/interview?i=docassemble.base:data/questions/examples/action-buttons.yml&reset=1 "Click to try this interview") For each button, the required items are `action` and `label`. You can optionally include `color` to indicate the Bootstrap color of the button (`primary`, `secondary`, `success`, `danger`, `warning`, `info`, `light`, `link`, or `dark`). The default color is `primary`. You can also optionally include `icon` to indicate a Font Awesome icon name to include in the button. If your `action` requires arguments, you can indicate the arguments using `arguments`. To specify that a particular button should have a particular CSS class, you can specify `css class`. You can use [Mako](https://www.makotemplates.org/) templating in any of these elements. If you want to define the buttons programmatically, you can set `action buttons` to a dictionary where the only item is `code`. question: | What is your favorite fruit? fields: - Fruit: favorite_fruit --- question: | Thank you for that information. field: thank_user action buttons: code: | [{'action': 'eat',\ 'arguments': {'fruit': favorite_fruit},\ 'label': 'Eat ' + favorite_fruit,\ 'color': 'secondary',\ 'css class': 'eat-button'}] --- event: eat code: | log('Nom nom nom. That ' + action_argument('fruit') + ' was good.', "info") set_save_status('ignore') [GitHub](https://github.com/jhpyle/docassemble/blob/master/docassemble_base/docassemble/base/data/questions/examples/action-buttons-code.yml "Open on GitHub") [![Screenshot of action-buttons-code example](https://docassemble.org/img/examples/action-buttons-code.png)](https://demo.docassemble.org/interview?i=docassemble.base:data/questions/examples/action-buttons-code.yml&reset=1 "Click to try this interview") When you use `code` to define the `action buttons`, you need to provide a [Python](https://en.wikipedia.org/wiki/Python_%28programming_language%29) expression that evaluates to a list of dictionaries, where each dictionary has the items `action` and `label` at a minimum. By default, the buttons indicated by `action buttons` will be placed after the “Continue” button or any other buttons specified in the `question`, and before the [`question help button`](https://docassemble.org/docs/initial.html#question%20help%20button) (if present). If you want a button to appear before the standard buttons of the `question`, set `placement` to `before`. question: | I will give you ${ quantity_noun(num_apples, 'apple') }. field: show_quantity action buttons: - label: More action: change_quantity arguments: amount: 1 color: success icon: chevron-up placement: before - label: Less action: change_quantity arguments: amount: -1 color: danger icon: chevron-down placement: before --- event: change_quantity code: | num_apples += action_argument('amount') [GitHub](https://github.com/jhpyle/docassemble/blob/master/docassemble_base/docassemble/base/data/questions/examples/action-buttons-before.yml "Open on GitHub") [![Screenshot of action-buttons-before example](https://docassemble.org/img/examples/action-buttons-before.png)](https://demo.docassemble.org/interview?i=docassemble.base:data/questions/examples/action-buttons-before.yml&reset=1 "Click to try this interview") If you set the `action` of an button to a web URL (beginning with `http://`, `https://`, `/`, or `?`) or a [JavaScript](https://en.wikipedia.org/wiki/Javascript) URL (beginning with `javascript:`), then the button will act like a hyperlink with the value of the `action` as the `href`. question: | You may wish to wait until ${ today().plus(weeks=3) } to file your complaint. subquestion: | It is up to you whether you wish to continue with the interview. If you leave, you will be directed back to the web site. field: wishes_to_continue action buttons: - label: Come back later action: https://docassemble.org color: warning icon: sign-out-alt [GitHub](https://github.com/jhpyle/docassemble/blob/master/docassemble_base/docassemble/base/data/questions/examples/action-buttons-http.yml "Open on GitHub") [![Screenshot of action-buttons-http example](https://docassemble.org/img/examples/action-buttons-http.png)](https://demo.docassemble.org/interview?i=docassemble.base:data/questions/examples/action-buttons-http.yml&reset=1 "Click to try this interview") If you want the link to open in another window, use `new window: True`. By default, if the user starts an action and then starts a second action without finishing the first, then when the user finishes the second action, the first action will be resumed. This is sometimes desirable and sometimes not. If you want the action launched by your button to be the only active action, set `forget prior: True` in the action button definition; then all prior actions will be forgotten. If you want a button to be included only conditionally, set `show if` to a Python expression. If the expression evaluates to a false value, the button will not be shown. When you define buttons with `code`, you can include `show if` in a `dict` for a button, and if it is a false value, the button will be omitted. Customizing screen parts[¶](https://docassemble.org/docs/questions.html#screen%20parts) ======================================================================================== When the user looks at a screen in an interview, there are many different “parts” of the screen. Above, you were introduced to the [`question`](https://docassemble.org/docs/questions.html#question) , [`subquestion`](https://docassemble.org/docs/questions.html#subquestion) , [`under`](https://docassemble.org/docs/questions.html#under) , [`right`](https://docassemble.org/docs/questions.html#right) , and [`css class`](https://docassemble.org/docs/questions.html#css%20class) parts. There are other parts of the screen as well, which by default are empty or have a useful default. The following interview demonstrates where each part is located. Try out the interview and look at the results with different screen sizes. metadata: title: Title short title: Short title subtitle: | This is the subtitle part. pre: | This is the pre part. submit: | This is the submit part. post: | This is the post part. under: | This is the under part. right: | This is the right part. exit link: leave exit label: | Exit label help label: | Help label help button color: warning continue button label: | Continue button label continue button color: success resume button label: | Resume button label resume button color: info back button label: | Back button label back button color: danger footer: | This is the footer part. [GitHub](https://github.com/jhpyle/docassemble/blob/master/docassemble_base/docassemble/base/data/questions/examples/metadata-screen-parts.yml "Open on GitHub") [![Screenshot of metadata-screen-parts example](https://docassemble.org/img/examples/metadata-screen-parts.png)](https://demo.docassemble.org/interview?i=docassemble.base:data/questions/examples/metadata-screen-parts.yml&reset=1 "Click to try this interview") * The `title` is the “long title” that appears in the upper-left on a large screen. * The `short title` appears in the upper-left on a small screen. If not provided, the `title` is used in its place. * The `title url` is the URL to which the user will be directed if the user clicks on the title. The default is that clicking the title does nothing. * The `title url opens in other window` can be set to `False` if you do not want the `title url` to open in new window or tab. * The `subtitle` is not visible on the screen, but can be seen in the list of [Available Interviews](https://docassemble.org/docs/admin.html#available%20interviews) . * The `logo`, if set, will replace the `title` and `short title` with custom HTML content, such as an image. This HTML is placed inside of a `` element, so it is important to only use “inline” HTML elements. You can [provide CSS](https://docassemble.org/docs/initial.html#css) to the interview and reference [CSS](https://en.wikipedia.org/wiki/CSS) classes in your `logo`. Ideally the logo should be no taller than 20 pixels. If the `logo` is taller, the navigation bar will expand to fit, and you will need to [adjust the CSS](https://docassemble.org/docs/config.html#bootstrap%20theme) to specify different values for `.da-pad-for-navbar` and `.da-top-for-navbar`. * The `short logo`, if set, will replace the `logo` on a small screen. * The `pre` area is above the [`question`](https://docassemble.org/docs/questions.html#question) . * The `submit` area is above the buttons, if the screen has buttons. * The `under` area is directly below the buttons. * The `right` area is to the right, but if the screen is too small, it wraps and appears under the `under` area. * The `post` area is below everything except for image attributions, which are below the `post` area. * The `footer` area is at the bottom of the screen, in a 60px tall box with the Bootstrap `light` color. If a `global footer` or `main page footer` is defined in the [Configuration](https://docassemble.org/docs/config.html) , you can turn off the default footer by setting the `footer` area to `off`. * The `exit link` is not a visible component, but rather a value that is either `exit` or `leave`. It controls the operation of the exit link in the upper right corner, which is present if [`show login`](https://docassemble.org/docs/initial.html#show%20login) is set to `False`. * The `exit label` is the visible label of the exit link in the upper right corner, which is present if [`show login`](https://docassemble.org/docs/initial.html#show%20login) is set to `False`. * The `exit url` is a URL to which the user will be directed when they click the exit link. * The `help label` is the default label for the “help” tab. It can be overridden by a `label` specifier inside a [`help`](https://docassemble.org/docs/modifiers.html#help) modifier. If you set a [`question help button`](https://docassemble.org/docs/initial.html#question%20help%20button) , the `help label` will be used for the help button, while the label for the help tab will be the less conspicuous word “Help.” * The `help button color` is the [Bootstrap color](https://getbootstrap.com/docs/5.2/customize/color/) of the help button that appears when you set a [`question help button`](https://docassemble.org/docs/initial.html#question%20help%20button) is enabled. This also affects the color of the question mark icon that appears when a choice in a multiple choice list has help text associated with it. * The `continue button label` is the label for the “Continue” button. If the `question` is a [`review`](https://docassemble.org/docs/fields.html#review) question, this is called the `resume button label`. * The `continue button color` is the [Bootstrap color](https://getbootstrap.com/docs/5.2/customize/color/) of the “Continue” button. If the `question` is a [`review`](https://docassemble.org/docs/fields.html#review) question, this is called the `resume button color`. * The `back button label` is the label for the back button that appears within the question itself when [`question back button`](https://docassemble.org/docs/initial.html#question%20back%20button) is enabled. * The `back button color` is the [Bootstrap color](https://getbootstrap.com/docs/5.2/customize/color/) of the back button that appears within the question itself when [`question back button`](https://docassemble.org/docs/initial.html#question%20back%20button) is enabled. * The `corner back button label` is the label for the back button that appears in the upper-left corner. * The `css class` will be added to the classes of the `` of the question. * The `table css class` will be the class of any `` elements created based on [Markdown](https://daringfireball.net/projects/markdown/) tables. You can set this to `table table-bordered` for a Bootstrap “bordered” table. You can also use `table css class` to specify a class for the `` within the table. If you set `table css class` to `table table-bordered, thead-dark`, then the `
` will have the class `table table-bordered` and the `` will have the class `thead-dark`. * The `navigation bar html` lets you add HTML to the navigation bar. The HTML will be inserted into a `