diff --git a/docs/archive/bootcamp.md b/docs/archive/bootcamp.md index 79b58732c..a68d57620 100644 --- a/docs/archive/bootcamp.md +++ b/docs/archive/bootcamp.md @@ -46,7 +46,7 @@ After signing up, you should have received invites to our docassemble server (ht Resources from the session: -* [Running templates through the Weaver](../authoring/weaver_overview.md) +* [Building interviews with the Weaver](../authoring/weaver/overview.md) * [Labeling PDF variables](../authoring/pdf_templates.md) * [Naming Variables Quick Reference](../authoring/doc_vars_reference.md) * [The LIST taxonomy](https://taxonomy.legal/) diff --git a/docs/assets/editor_find_replace.png b/docs/assets/editor_find_replace.png new file mode 100644 index 000000000..97679f581 Binary files /dev/null and b/docs/assets/editor_find_replace.png differ diff --git a/docs/assets/editor_github_publish.png b/docs/assets/editor_github_publish.png new file mode 100644 index 000000000..086155b40 Binary files /dev/null and b/docs/assets/editor_github_publish.png differ diff --git a/docs/assets/editor_main_interview_screen.png b/docs/assets/editor_main_interview_screen.png new file mode 100644 index 000000000..2a7a69a5b Binary files /dev/null and b/docs/assets/editor_main_interview_screen.png differ diff --git a/docs/assets/editor_order_builder.png b/docs/assets/editor_order_builder.png new file mode 100644 index 000000000..f5e3849aa Binary files /dev/null and b/docs/assets/editor_order_builder.png differ diff --git a/docs/assets/editor_project_selector.png b/docs/assets/editor_project_selector.png new file mode 100644 index 000000000..d29ae7c30 Binary files /dev/null and b/docs/assets/editor_project_selector.png differ diff --git a/docs/assets/editor_question_library.png b/docs/assets/editor_question_library.png new file mode 100644 index 000000000..b585893c5 Binary files /dev/null and b/docs/assets/editor_question_library.png differ diff --git a/docs/assets/editor_raw_yaml_view.png b/docs/assets/editor_raw_yaml_view.png new file mode 100644 index 000000000..b5038466a Binary files /dev/null and b/docs/assets/editor_raw_yaml_view.png differ diff --git a/docs/assets/editor_screen_preview.png b/docs/assets/editor_screen_preview.png new file mode 100644 index 000000000..e38a58c5a Binary files /dev/null and b/docs/assets/editor_screen_preview.png differ diff --git a/docs/assets/editor_templates_documents.png b/docs/assets/editor_templates_documents.png new file mode 100644 index 000000000..f3068f9eb Binary files /dev/null and b/docs/assets/editor_templates_documents.png differ diff --git a/docs/assets/editor_validation_drawer.png b/docs/assets/editor_validation_drawer.png new file mode 100644 index 000000000..0d7857bb2 Binary files /dev/null and b/docs/assets/editor_validation_drawer.png differ diff --git a/docs/authoring/ai_checklist_quality_publish.md b/docs/authoring/ai_checklist_quality_publish.md index 743afae33..92cc0aab1 100644 --- a/docs/authoring/ai_checklist_quality_publish.md +++ b/docs/authoring/ai_checklist_quality_publish.md @@ -20,4 +20,4 @@ Related guides (canonical details): - [Coding style for YAML translation](../coding_style/yaml_translation.md) - [Writing good questions](../style_guide/question_style_overview.md) - [Editing your interview](customizing_interview.md) -- [Metadata for publishing generated YAML interviews](weaver_code_anatomy.md#interview-metadata-and-metadata-for-publishing-on-courtformsonline) +- [Metadata and publishing guide](weaver/publishing_and_github.md) diff --git a/docs/authoring/ai_checklist_weaver_editing.md b/docs/authoring/ai_checklist_weaver_editing.md index dc444c7a4..394446919 100644 --- a/docs/authoring/ai_checklist_weaver_editing.md +++ b/docs/authoring/ai_checklist_weaver_editing.md @@ -17,7 +17,8 @@ Use this checklist after labels are ready and you are generating a draft intervi Related guides (canonical details): -- ["Weaving" your form into a draft interview](weaver_overview.md) +- [The Assembly Line Weaver](weaver/overview.md) - [Editing your interview](customizing_interview.md) -- [Writing your own review screen](writing_review_screen.md) +- [Writing a review screen](writing_review_screen.md) +- [Review screen synchronization in the Weaver](weaver/review_screens.md) - [Dynamic phrases based on prior answers](dynamic_phrasing_based_on_values.md) diff --git a/docs/authoring/combining_interviews.md b/docs/authoring/combining_interviews.md index 90c379ab1..f3835f571 100644 --- a/docs/authoring/combining_interviews.md +++ b/docs/authoring/combining_interviews.md @@ -5,11 +5,11 @@ title: Combining multiple interviews # Combining multiple docassemble interviews -When you use the AssemblyLine Weaver to create an interview, it gives you a complete, standalone interview out of the box (like you see in [docassemble-ALWeaver](https://github.com/SuffolkLITLab/docassemble-ALWeaver)). But often, you need to combine several different forms or interviews into one unified, seamless user experience. +When you use the [AssemblyLine Weaver](weaver/overview.md) to create an interview, it gives you a complete, standalone interview out of the box (like you see in [docassemble-ALWeaver](https://github.com/SuffolkLITLab/docassemble-ALWeaver)). But often, you need to combine several different forms or interviews into one unified, seamless user experience. For example, you might want to combine a "Petition for Guardianship" and a "Motion for Temporary Guardian" into a single flow, or bundle multiple housing code complaint forms. -This tutorial walks you through the step-by-step process of taking multiple standalone ALWeaver interviews and combining them. +This tutorial walks you through the step-by-step process of taking multiple standalone Weaver interviews and combining them. ## Key concepts diff --git a/docs/authoring/customizing_interview.md b/docs/authoring/customizing_interview.md index 12ec5e8d3..4e641d944 100644 --- a/docs/authoring/customizing_interview.md +++ b/docs/authoring/customizing_interview.md @@ -5,61 +5,51 @@ sidebar_label: Editing your interview slug: customizing_interview --- -## Edit your completed draft interview in the docassemble playground +## Editing your interview in the Weaver or Playground + +You can edit and refine your interview either visually in the [Assembly Line Weaver](weaver/overview.md) or directly in the Docassemble Playground code editor. + +:::tip Visual editing with the Weaver +The [Assembly Line Weaver](weaver/overview.md) allows you to edit question screens, reorder flow steps, preview screens across devices, configure document bundles, and run safe variable refactorings without manually writing YAML: +* [Designing question screens and fields](weaver/screens_and_fields.md) +* [Live screen previews](weaver/screen_previews.md) +* [Sequencing flow with the interview order builder](weaver/interview_order.md) +* [Configuring document bundles and templates](weaver/document_bundles.md) +* [Review screen synchronization](weaver/review_screens.md) +* [Diagnostics and safe refactoring](weaver/diagnostics_and_refactoring.md) +::: -While the Weaver is a menu-driven, step-by-step process, you'll make further -edits in the Playground. In the playground, you can directly edit the -[YAML](../docassemble_intro/yaml) text to: +If you prefer to edit the raw [YAML](../docassemble_intro/yaml) text directly in the Playground or your local code editor, you can: 1. Change the wording of questions -1. Change the datatype of questions and add show/hide logic -1. Edit the order screens appear in -1. Add conditional and branching logic -1. Add new variables, such as variables calculated by code +2. Change the datatype of questions and add show/hide logic +3. Edit the order screens appear in +4. Add conditional and branching logic +5. Add new variables, such as variables calculated by code -Save your work frequently, and don't be intimidated. For the most part, -many changes can be understood by reading the text and then experimenting. +Save your work frequently, and don't be intimidated. For the most part, many changes can be understood by reading the text and experimenting. -This pages offers information about making some common, simple edits. -You may also want to take this time to read through the materials in -[Introduction to docassemble](../docassemble_intro/introduction-to-docassemble) -about the underlying docassemble platform and how it works. +This page offers information about making common manual YAML edits. You may also want to take this time to read through the materials in [Introduction to docassemble](../docassemble_intro/introduction-to-docassemble) about the underlying Docassemble platform. -## Double-check that you got things right in the Weaver stage +## Double-check that you got things right in the labeling stage -Some common mistakes, like typos in the labels, can lead to a lot of extra work. -If you see "extra" questions appear, it's possible that you didn't get the names -quite right, perhaps something as simple as a typo. +Some common mistakes, like typos in the labels, can lead to a lot of extra work. If you see "extra" questions appear, it's possible that you didn't get the names quite right, perhaps something as simple as a typo. Use the [Weaver diagnostics drawer](weaver/diagnostics_and_refactoring.md) to detect missing or mismatched variables automatically. ## Work towards a readable, usable interview -You should also take this chance to review our guidance about -[writing good questions](../style_guide/question_style_overview.md). While you edit -your interview, work steadily to make it better. - -## Getting the draft into your playground +You should also take this chance to review our guidance about [writing good questions](../style_guide/question_style_overview.md). While you edit your interview, work steadily to make it better. -When you have finished using the Weaver, download your package. This will put a -.zip file in the Downloads folder on your computer. +## Working with Playground projects -:::warning If you are using Safari on a Mac OS computer -Safari, by default, will turn your downloaded package into -a folder on your PC. +The Weaver and Docassemble Playground share the same project files: -Before downloading the package, turn off that behavior: +1. In the Playground or the Weaver project selector, select or create your project. +2. Changes made in the Weaver are saved directly to your Playground files and can be opened in either environment at any time. -1. open Safari -1. click Preferences -1. under the General tab, uncheck the option **Open 'safe' files after downloading** -::: - -First, create a new "Project" in your playground. Using projects will -help you keep your docassemble code organized. +If you are using the legacy wizard or an exported `.zip` package, you can upload it to the Playground's **Packages** folder. ![playground | projects ](../assets/playground_projects.png) -Next, upload this file to the docassemble playground's `Packages` folder. - ![Folders | Packages ](../assets/playground_packages_menu.png) ## How to edit your interview diff --git a/docs/authoring/doc_vars_reference.md b/docs/authoring/doc_vars_reference.md index 6ebb7a700..198095743 100644 --- a/docs/authoring/doc_vars_reference.md +++ b/docs/authoring/doc_vars_reference.md @@ -391,8 +391,9 @@ Getting things right at the beginning can save you a lot of time and effort. However, you can always edit your template later. When you make changes to your template, you do not need to run it through the Weaver again. You can upload -your edited template directly to the docassemble playground's templates folder. +your edited template directly in the [Weaver's Templates tab](weaver/document_bundles.md) or the Docassemble Playground. ## See also +- [The Assembly Line Weaver](weaver/overview.md) - [List of reserved variable names](../components/AssemblyLine/reserved_keywords.md) \ No newline at end of file diff --git a/docs/authoring/pdf_templates.md b/docs/authoring/pdf_templates.md index 15a21577d..eab2db9da 100644 --- a/docs/authoring/pdf_templates.md +++ b/docs/authoring/pdf_templates.md @@ -133,7 +133,7 @@ with the same field names, for example, in a document bundle, you still may have ## Quality control checklist -Many of the below checkbox items can be verified by uploading the PDF to the [Weaver](https://github.com/SuffolkLITLab/docassemble-ALWeaver), +Many of the below checkbox items can be verified by uploading the PDF to the [Weaver](weaver/overview.md), installed on your own docassemble server. When you upload a PDF to the Weaver, it will try filling in all of the PDF's fields with dummy data, allowing for a quick visual inspection. diff --git a/docs/authoring/weaver/authoring_checklist.md b/docs/authoring/weaver/authoring_checklist.md new file mode 100644 index 000000000..6f47c22b1 --- /dev/null +++ b/docs/authoring/weaver/authoring_checklist.md @@ -0,0 +1,67 @@ +--- +id: weaver_authoring_checklist +title: | + Authoring checklist: start to finish +sidebar_label: | + Authoring checklist +slug: authoring_checklist +--- + +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; + +Use this comprehensive pre-flight checklist before handing off your interview for legal review, user testing, or production launch. + +--- + +## 1. Document template preparation + +- [ ] **Labels Verified**: All fields in DOCX and PDF templates are labeled with standard [AssemblyLine variable conventions](../doc_vars_reference.md). +- [ ] **Clean Filenames**: Template files have clean, descriptive names without draft suffixes (e.g. `motion_to_dismiss.docx`). +- [ ] **Overflow Safeguards**: Multi-line narrative text areas in PDF templates have matching overflow addenda or auto-scaling enabled. + +--- + +## 2. Project setup and metadata + +- [ ] **Project Created**: Playground project initialized in the Weaver. +- [ ] **Metadata Defined**: The `metadata:` block includes title, short title, description, author names, and relevant legal topic tags. +- [ ] **Standard Objects Declared**: `ALPeopleList` declared for `users` and `other_parties` with appropriate quantity rules. + +--- + +## 3. Question screens and plain language + +- [ ] **Readable Headings**: Screen titles and subquestions are written in plain, accessible language (5th-to-8th grade reading level). +- [ ] **Input Field Types**: Every field uses the appropriate datatype (e.g., date pickers for dates, currency for dollar amounts, yes/no for booleans). +- [ ] **Required vs Optional**: Required toggles are properly set, and optional fields are wrapped in conditional logic in templates. +- [ ] **Help Text Added**: Unfamiliar legal terms are explained using field help popovers. + +--- + +## 4. Interview order and flow + +- [ ] **Logical Step Hierarchy**: Question screens, loops (`.gather()`), conditional branches (`if/else`), and progress indicators (`set_progress`) are sequenced in the Order Builder. +- [ ] **Off-Ramp Screens**: Exit screens are in place for users who do not qualify or who should not proceed. +- [ ] **Review Screen Enabled**: A `review:` screen allows users to inspect and edit their answers before compiling final documents. + +--- + +## 5. Document bundles and assembly + +- [ ] **Document Bundles Configured**: `ALDocument` and `ALDocumentBundle` definitions are ordered and labeled cleanly. +- [ ] **Conditional Inclusion Tested**: Documents that should only appear under certain conditions (e.g. fee waivers, instructions) have verified conditional expressions. + +--- + +## 6. Diagnostics and quality verification + +- [ ] **Zero Validation Errors**: The **Errors & Warnings** drawer shows no missing IDs, duplicate blocks, or undefined variables. +- [ ] **Live End-to-End Test**: Successfully completed a full test run of the interview using **Open interview**, generating and downloading sample court documents. +- [ ] **Mobile and Desktop Tested**: Screen layouts and touch targets verified in live screen preview on mobile, tablet, and desktop viewports. + +--- + +## 7. Version control and publishing + +- [ ] **Committed to GitHub**: Code pushed to the appropriate GitHub organization repository with a clean commit message. diff --git a/docs/authoring/weaver/diagnostics_and_refactoring.md b/docs/authoring/weaver/diagnostics_and_refactoring.md new file mode 100644 index 000000000..7a05f7fc8 --- /dev/null +++ b/docs/authoring/weaver/diagnostics_and_refactoring.md @@ -0,0 +1,63 @@ +--- +id: weaver_diagnostics_and_refactoring +title: | + Diagnostics, safe refactoring, and YAML code view +sidebar_label: | + Diagnostics and refactoring +slug: diagnostics_and_refactoring +--- + +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; + +The Weaver includes comprehensive static analysis tools, project-wide safe variable refactoring, and an embedded CodeMirror 6 YAML editor to ensure your interview code remains clean, error-free, and maintainable. + +--- + +## Real-time validation and diagnostics + +The bottom **Errors & Warnings** drawer continuously analyzes your interview as you make changes: + +![Validation and Error Diagnostics Drawer](../../assets/editor_validation_drawer.png) + +The linter automatically checks for: +* **Duplicate or Missing Block IDs**: Flags blocks that share an ID or omit an essential `id:` tag. +* **Undefined Variables**: Detects references in questions, review screens, or order logic that have no matching field definitions or object declarations. +* **Template Field Mismatches**: Warns if a variable is used in a DOCX or PDF template but is missing from your question screens. + +For plain-language and style review, use the validation drawer's **Style check** action separately — it is not part of the always-on drawer checks and calls an AI-assisted review of your question wording. + +--- + +## Project-wide find and replace with safe variable refactoring + +Renaming a variable across a complex project with a simple text search-and-replace often causes unintended side effects—corrupting user-facing labels, subquestions, or comments. + +Click the magnifying-glass icon next to the project selector in the left rail to open **Find and replace**: + +![Project-Wide Find and Replace](../../assets/editor_find_replace.png) + +### Safe variable refactoring mode +* **AST & Structure Awareness**: Uses Python Abstract Syntax Tree (AST) parsing and YAML stream analysis to distinguish between actual variable references and identical words in human-facing text. +* **Multi-File Scope**: Finds and updates occurrences across YAML interviews, DOCX Jinja2 templates, and Python modules simultaneously. +* **Selective Replacement**: Displays a list of matches with surrounding context and checkboxes, allowing you to choose exactly which occurrences to replace. + +--- + +## Full raw YAML view + +For power users who prefer to inspect or edit raw code directly, click **More** $\to$ **YAML source**: + +![Full Raw YAML View in CodeMirror 6](../../assets/editor_raw_yaml_view.png) + +The built-in CodeMirror 6 editor provides: +* Full syntax highlighting for Docassemble YAML, Mako templates, and embedded Python expressions. +* Code folding, line numbering, and bracket matching. +* **Two-Way Synchronization**: Any valid edits made in the raw YAML view are parsed and updated in the visual block outline as soon as you return to the block editor. + +--- + +## Next steps + +* Push your interview to GitHub in [Publishing and version control with GitHub](publishing_and_github.md). +* Review the [Authoring checklist](authoring_checklist.md) before publishing. diff --git a/docs/authoring/weaver/document_bundles.md b/docs/authoring/weaver/document_bundles.md new file mode 100644 index 000000000..fdef2bbc2 --- /dev/null +++ b/docs/authoring/weaver/document_bundles.md @@ -0,0 +1,60 @@ +--- +id: weaver_document_bundles +title: | + Configuring document bundles and templates +sidebar_label: | + Document bundles and templates +slug: document_bundles +--- + +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; + +In the **Templates** view of the Weaver, clicking **Document setup** opens the document assembly manager. This interface controls which templates are compiled, how multiple documents are bundled together, and the conditional rules that govern when specific documents are generated. + +![Templates and Document Bundles Setup](../../assets/editor_templates_documents.png) + +--- + +## Working with template files + +You can upload both DOCX and PDF templates into your project: + +1. Click **Upload** in the left sidebar of the Templates tab to add a new labeled DOCX or PDF file. +2. The Weaver analyzes the template's Jinja2 tags or PDF form fields and registers them in the project. + +--- + +## Understanding document bundles (`ALDocumentBundle`) + +An `ALDocumentBundle` combines one or more `ALDocument` items into a unified downloadable packet (such as a single PDF containing a Motion, an Affidavit of Indigency, and a Certificate of Service): + +```yaml +objects: + - motion_to_dismiss_doc: ALDocument.using(title="Motion to Dismiss", filename="motion_to_dismiss.docx", enabled=True) + - instructions_doc: ALDocument.using(title="Filing Instructions", filename="instructions.docx", enabled=include_instructions) + - bundle: ALDocumentBundle.using(title="Main Filing Package", elements=['motion_to_dismiss_doc', 'instructions_doc'], enabled=True) +``` + +--- + +## Document inclusion rules + +For each document in your bundle, you can configure when it should be compiled: + +* **Always**: The document is always generated and included in the final download package. +* **Never**: The document is excluded by default (useful for draft or reference templates). +* **Custom (Condition)**: Enter a Python condition (e.g. `include_instructions` or `user_has_fee_waiver`). The document will only be assembled when this expression evaluates to `True`. + +--- + +## Reordering documents in the bundle + +Use the up () and down () buttons next to each document entry to change the order in which documents are assembled and merged into the final packet. + +--- + +## Next steps + +* Add a summary review screen for user verification in [Review screen synchronization](review_screens.md). +* Check your interview for errors in [Diagnostics, refactoring, and YAML code view](diagnostics_and_refactoring.md). diff --git a/docs/authoring/weaver/interview_order.md b/docs/authoring/weaver/interview_order.md new file mode 100644 index 000000000..e97293123 --- /dev/null +++ b/docs/authoring/weaver/interview_order.md @@ -0,0 +1,88 @@ +--- +id: weaver_interview_order +title: | + Sequencing flow with the interview order builder +sidebar_label: | + Interview order builder +slug: interview_order +--- + +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; + +Docassemble is a goal-directed system that seeks out variables as needed. However, every production AssemblyLine interview relies on a central **Interview Order** block (`mandatory: True`) to ensure that users encounter screens, introductory text, list-gathering loops, and review screens in a logical, guided sequence. + +Click the **Interview order** button in the left navigation rail to open the visual flow builder: + +![Visual Interview Order Builder](../../assets/editor_order_builder.png) + +--- + +## The interview order block + +Behind the scenes, the Order Builder manages a `mandatory: True` code block (by default with `id: interview_order`): + +```yaml +--- +id: interview_order +mandatory: True +code: | + al_intro_screen + set_progress(10) + users.gather() + other_parties.gather() + set_progress(40) + case_information + if user_is_low_income: + fee_waiver_screen + motion_grounds + set_progress(80) + hearing_date_screen + motion_review_screen + motion_download_screen +``` + +--- + +## Types of flow steps + +```mermaid +graph TD + subgraph Interview Flow + S1["al_intro_screen (Screen)"] --> P1["set_progress(10) (Progress)"] + P1 --> G1["users.gather() (Loop)"] + G1 --> G2["other_parties.gather() (Loop)"] + G2 --> S2["case_information (Screen)"] + S2 --> C1{"if user_is_low_income: (Condition)"} + C1 -- Yes --> S3["fee_waiver_screen (Screen)"] + C1 -- No --> S4["motion_grounds (Screen)"] + S3 --> S4 + S4 --> R1["motion_review_screen (Review)"] + R1 --> D1["motion_download_screen (Download)"] + end +``` + +The Order Builder represents each flow element visually with distinct badges and formatting: + +1. **Screen Steps**: Individual question screens (e.g., `al_intro_screen`, `case_information`). +2. **List Gather Steps (`LOOP`)**: Calls `.gather()` on an `ALPeopleList` or list object to trigger iterative questions for all members of the list. +3. **Conditional Branches (`IF/ELSE`)**: Branches that display specific screens only when a condition evaluates to `True`. +4. **Progress Indicators (`PROGRESS`)**: Updates the on-screen progress bar percentage (e.g., `set_progress(50)`). +5. **Section Dividers (`SECTION`)**: Marks the active navigation section in the progress outline (e.g., `nav.set_section('case')`). +6. **Code Steps**: Custom Python expressions or calculations executed silently between screens. + +--- + +## Visual reordering and branching controls + +* **Drag-and-Drop Reordering**: Grab the drag handle () beside any step to move it up or down in the sequence. +* **Wrap selected in if**: Check the selection box next to one or more steps and click this button to nest them inside a conditional branch. +* **Auto-generate**: Infers a draft interview sequence based on your declared question blocks, people lists, and document bundles. +* **Edit YAML**: Switch to inline code view to make manual Python adjustments to the order block. + +--- + +## Next steps + +* Configure template output and bundles in [Document bundles and templates](document_bundles.md). +* Add a summary review block in [Review screens](review_screens.md). diff --git a/docs/authoring/weaver/overview.md b/docs/authoring/weaver/overview.md new file mode 100644 index 000000000..f2cd15bc7 --- /dev/null +++ b/docs/authoring/weaver/overview.md @@ -0,0 +1,128 @@ +--- +id: weaver_overview +title: | + The Assembly Line Weaver +sidebar_label: | + Overview +slug: weaver_overview +--- + +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import { Button } from '/docs/react_components/Button.jsx'; + +The **Assembly Line Weaver** is the official visual authoring environment for Docassemble and the Document Assembly Line. It provides a visual **WYSIWYM** (What You See Is What You Mean) workspace that lets you build, preview, sequence, and refine guided legal interviews—from a freshly labeled DOCX or PDF template all the way to a production-ready application. + +

+ + +

+ +:::info Legacy Weaver wizard +The linear wizard-style Weaver is still available, but is no longer actively maintained. We recommend using the visual Weaver for all new interviews and ongoing maintenance. +::: + +:::tip Playground and Weaver synchronization +The Weaver operates directly on your Docassemble **Playground** projects. Any changes you save in the Weaver are immediately stored in your Playground files and can be run, debugged, or committed to version control. +::: + +--- + +## Why use the Weaver? + +Traditional Docassemble interview creation previously required either writing hundreds of lines of YAML and Python by hand or running a one-time linear wizard. The Weaver combines the speed of automated template scaffolding with the control of a full IDE: + +* **Continuous, non-linear editing**: Modify screen questions, reorder steps, add conditional branching, and adjust template mappings at any point without restarting a wizard. +* **Instant screen previews**: See how each question screen looks in real time using Docassemble's native stylesheets across desktop, tablet, and mobile viewports. +* **Visual interview order builder**: Structure your interview flow, loops, progress bars, and conditional branches with an intuitive drag-and-drop hierarchy. +* **Standard AssemblyLine library integration**: Pull pre-built, plain-language question components for names, addresses, language interpreters, and demographics directly into your interview. +* **Document bundle assembly**: Visually organize multiple DOCX and PDF templates into download packages with conditional inclusion rules. +* **Safe project-wide refactoring**: Rename variables across YAML interviews, DOCX templates, and Python modules with semantic AST awareness that preserves ordinary text and prose. +* **Built-in quality diagnostics**: Catch missing IDs, duplicate blocks, undefined variables, and style warnings before running your interview. +* **Integrated GitHub publishing**: Commit and push changes to GitHub repositories right from the browser. + +--- + +## Start-to-finish workflow overview + +Building an interview with the Weaver follows a streamlined path from initial document preparation to deployment: + +```mermaid +flowchart TD + A["1. Labeled Template (DOCX / PDF)"] --> B["2. Create / Select Project in Weaver"] + B --> C["3. Organize & Edit Question Screens"] + C --> D["4. Test in Live Screen Preview"] + D --> E["5. Add AssemblyLine Question Library Blocks"] + E --> F["6. Sequence Flow in Interview Order Builder"] + F --> G["7. Configure Document Bundles & Rules"] + G --> H["8. Run Diagnostics & Refactor Variables"] + H --> I["9. Commit & Push to GitHub"] + I --> J["10. Test Live Guided Interview"] +``` + +--- + +## Workspace layout and navigation + +When you open the Weaver, you can select an existing Playground project, start a new project, or clone a repository from GitHub. + +![Project Selector and Project Management](../../assets/editor_project_selector.png) + +Once inside a project, the interface is organized into intuitive work areas designed for rapid authoring: + +![Main WYSIWYM Screen Editor Workspace](../../assets/editor_main_interview_screen.png) + +1. **Top navigation bar**: + * **View tabs**: + * **Interview**: Visual block editor and outline for interview screens and code blocks. + * **Templates**: Document template manager and `ALDocumentBundle` setup. + * **Modules**: Python modules and custom business logic. + * **Static**: Static assets (images, stylesheets, custom JS). + * **Sources**: CSV data tables and lookup files. + * **Errors badge**: A live count of validation issues next to the **Errors** button; click it to open the Errors & Warnings drawer. + * **Open interview**: Launches the current interview in a new tab for live runtime testing. + * **Save**: Writes all changes to the server (`Ctrl+S` or `Cmd+S`). + * **Assistant**: Toggles the AI editing assistant panel, when it is enabled on your server. + * **More menu**: Access **YAML source**, **AssemblyLine settings**, **Open in Playground**, **Commit to GitHub**, **Pull changes from GitHub** (once a repo is linked), and **Switch project**. +2. **Left navigation rail**: + * **Project and file selectors**: Switch between Playground projects and between YAML interview files in the project. + * **Find or replace across project**: The magnifying-glass icon next to the project selector opens project-wide find and replace. + * **Show filter**: Filter the outline by block type — question/review screens, code, objects, events, sections, metadata, modules, templates, tables, all blocks, or disabled blocks. + * **Search filter**: Type to filter blocks in the outline by title or variable name. + * **Interview order button**: Opens the visual flow sequencer. + * **Block outline**: Drag-and-drop tree of all blocks in the active file with quick-add (`+`) buttons between blocks. +3. **Central canvas**: + * The active block editor with tabs for **Screen**, **Question options**, and **YAML**, plus a separate **Preview** button. +4. **Bottom drawer**: + * Collapsible **Errors & Warnings** panel displaying static analysis findings. + +--- + +## Explore the Weaver documentation + +Follow the guides below to master each stage of building a guided interview: + +1. [**Question screens and fields**](screens_and_fields.md) — Author interactive question screens, field types, labels, help text, and show-if visibility logic. +2. [**Live screen previews**](screen_previews.md) — Test screen UX in real time across desktop, tablet, and mobile viewports. +3. [**Question library and people**](question_library.md) — Manage `ALPeopleList` objects and insert standardized questions for names, addresses, and accommodations. +4. [**Interview order builder**](interview_order.md) — Visually structure the interview flow, loops, conditional branches, progress bars, and sections. +5. [**Document bundles and templates**](document_bundles.md) — Configure `ALDocument` and `ALDocumentBundle` download packets with conditional inclusion rules. +6. [**Review screens**](review_screens.md) — Synchronize summary review screens with interview questions. +7. [**Diagnostics and refactoring**](diagnostics_and_refactoring.md) — Run static quality checks, refactor variables safely across YAML and DOCX, and edit raw YAML. +8. [**GitHub and publishing**](publishing_and_github.md) — Publish packages, manage branches, and commit to GitHub directly from the Weaver. +9. [**Authoring checklist**](authoring_checklist.md) — Review the start-to-finish quality checklist before deploying your interview. diff --git a/docs/authoring/weaver/publishing_and_github.md b/docs/authoring/weaver/publishing_and_github.md new file mode 100644 index 000000000..792ac9049 --- /dev/null +++ b/docs/authoring/weaver/publishing_and_github.md @@ -0,0 +1,42 @@ +--- +id: weaver_publishing_and_github +title: | + Publishing and version control with GitHub +sidebar_label: | + GitHub and publishing +slug: publishing_and_github +--- + +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; + +When your interview is ready for user testing, peer review, or production deployment, you can commit and push it directly to GitHub without leaving the Weaver. + +Click **More** $\to$ **Commit to GitHub** to open the publishing modal: + +![Commit and Publish to GitHub](../../assets/editor_github_publish.png) + +--- + +## Publishing workflow + +1. **Owner**: Choose your personal GitHub account or an organization account (such as `SuffolkLITLab`) among the ones your Docassemble server's GitHub integration can access. +2. **Repository name**: The `docassemble-` prefix is fixed; type the rest of the name (e.g. `ALMotionToDismiss`). An existing accessible repository with that name is reused, otherwise a new one is created under the selected owner. +3. **Branch**: Defaults to `main`. Type an existing branch name to update it, or a new one to create it. +4. **Commit message**: Defaults to "Update from Weaver" — replace it with a concise, descriptive summary of the changes. +5. **Publish to GitHub**: Every visible file in the project is included. The Weaver creates the commit, pushes it, and shows links to the repository and the commit. + +--- + +## Pulling updates from GitHub + +If collaborating with a team, you can pull remote updates directly into your Playground project: + +1. Click **More** $\to$ **Pull changes from GitHub** (this item only appears once the project is linked to a repository). +2. The Weaver fetches the latest commits from your upstream repository branch and refreshes your visual project files. + +--- + +## Next steps + +* Run through the [Authoring checklist](authoring_checklist.md) to confirm all quality checks before launching. diff --git a/docs/authoring/weaver/question_library.md b/docs/authoring/weaver/question_library.md new file mode 100644 index 000000000..1ba45d568 --- /dev/null +++ b/docs/authoring/weaver/question_library.md @@ -0,0 +1,64 @@ +--- +id: weaver_question_library +title: | + Question library and managing people +sidebar_label: | + Question library and people +slug: question_library +--- + +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; + +The AssemblyLine framework uses standardized object structures (`ALPeopleList` and `ALIndividual`) to represent individuals and parties, such as `users`, `other_parties`, `children`, and `attorneys`. + +The Weaver includes a built-in **Question library** browser that lets you declare people lists and insert pre-built, accessibility-vetted questions directly into your interview. + +![AssemblyLine Question Library Browser](../../assets/editor_question_library.png) + +--- + +## Managing people objects + +When you add someone new from the question library, the Weaver declares the list (or single person) in the `objects:` block and asks you to pick one of four quantity rules, which it writes as keyword arguments to `ALPeopleList.using(...)`: + +```yaml +objects: + - users: ALPeopleList.using(there_are_any=True) + - other_parties: ALPeopleList.using() + - children: ALPeopleList.using(ask_number=True) +``` + +### Quantity rules +* **Ask whether there are any** (`there_are_any=True`) — the default. Asks a preliminary yes/no question (e.g. "Do you have any children?") before gathering details. +* **At least one** — no extra keyword argument. Skips the "are there any?" question and starts by gathering one. +* **Ask how many** (`ask_number=True`) — asks the user for a number first, then gathers that many. +* **Exactly this many** (`target_number=`) — never asks; use this when a form has room for a fixed number of people, such as `target_number=1` for a single party. + +--- + +## Pre-built AssemblyLine questions + +Click a `+` quick-add button in the block outline, then choose **AssemblyLine question library** from the add-a-block menu. For each person object declared in the file, it offers: + +* **Gather questions**: the screens that ask whether there are any, how many, and each person's name (these depend on the quantity rule you picked — see above). +* **Attribute questions**, one block each: Address, Mailing address, Birthdate, Gender, Pronouns, Language, Phone number, Mobile number, and Email address. + +Each entry inserts an editable copy of AssemblyLine's own question wording, already pointed at your object (e.g. `children[i].address`). Editing the copy overrides AssemblyLine's version; deleting it reverts to AssemblyLine's original. Note that name fields for an existing gather loop come from the `name_fields` field type described in [Question screens and fields](screens_and_fields.md), not from this library. + +--- + +## Why use standard question blocks? + +Using standard AssemblyLine question blocks ensures: + +1. **Court Consistency**: Variable names and data structures match what court e-filing systems and standard court forms expect. +2. **Plain Language**: Prompts have been refined and user-tested for accessibility. +3. **Translations**: AssemblyLine's standard question wording has community-contributed translations into multiple languages, which a copied-in block inherits. + +--- + +## Next steps + +* Sequence loops like `users.gather()` in the [Interview order builder](interview_order.md). +* Configure your output documents and templates in [Document bundles](document_bundles.md). diff --git a/docs/authoring/weaver/review_screens.md b/docs/authoring/weaver/review_screens.md new file mode 100644 index 000000000..1bfdc25ed --- /dev/null +++ b/docs/authoring/weaver/review_screens.md @@ -0,0 +1,67 @@ +--- +id: weaver_review_screens +title: | + Review screen synchronization +sidebar_label: | + Review screens +slug: review_screens +--- + +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; + +A **Review Screen** provides a critical checkpoint in a guided interview, allowing users to review a summary of their answers and jump back to edit any mistakes before generating final court documents. + +--- + +## Anatomy of a review block + +In Docassemble and AssemblyLine, review screens are defined using a `review:` block with the `event:` matching the screen ID: + +```yaml +--- +id: motion_review_screen +event: motion_review_screen +question: | + Review your answers +subquestion: | + Please check over your information before creating your court forms. Click **Edit** next to any section you need to change. +review: + - Edit: case_information + button: | + **Case Information**: ${ court_name }, Docket #${ docket_number } + - Edit: motion_grounds + button: | + **Reason for Motion**: ${ motion_grounds } + - Edit: hearing_date_screen + button: | + **Hearing Date**: ${ requested_hearing_date } +``` + +--- + +## Re-drafting a review screen with "Sync from questions" + +Review screens are not kept in sync automatically as you edit — the Weaver drafts one on request: + +1. Open (or add) the review block and click **Sync from questions** (). +2. The Weaver re-reads every question screen the interview asks today — including screens in files it includes — and drafts a new review block from them. +3. A **Sync review screen** modal shows a unified diff of what would change (or the full drafted YAML), along with how many existing entries the draft did not cover and were carried over unchanged. +4. Click **Replace review screen** (or **Add review screen** if none exists yet) to save the result, or **Edit the whole file instead** to hand-edit the draft in the full YAML view before saving. + +This makes re-drafting safe to run again later: if you add new questions to the interview, running **Sync from questions** brings the review screen back in line without you having to hand-edit every row. + +--- + +## Best practices for review screens + +* **Group by Topic**: Keep related fields together under clear, descriptive bold headers (e.g. `**Your Contact Information**`, `**Court Details**`). +* **Format Dates and Currency**: Display human-readable dates (e.g. `requested_hearing_date.format('MMMM d, yyyy')`) and currency values (`currency(filing_fee)`). +* **Handle Optional Answers**: Wrap optional fields in conditional checks or defaults so missing values do not display as blanks or errors. + +--- + +## Next steps + +* Run static lint diagnostics and safe variable refactoring in [Diagnostics, refactoring, and YAML code view](diagnostics_and_refactoring.md). +* Commit and push your interview to GitHub in [Publishing and version control with GitHub](publishing_and_github.md). diff --git a/docs/authoring/weaver/screen_previews.md b/docs/authoring/weaver/screen_previews.md new file mode 100644 index 000000000..73528d46c --- /dev/null +++ b/docs/authoring/weaver/screen_previews.md @@ -0,0 +1,55 @@ +--- +id: weaver_screen_previews +title: | + Live screen previews +sidebar_label: | + Live screen previews +slug: screen_previews +--- + +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; + +To verify how your question screens will look and behave for end users, click the **Preview** button () in the upper right corner of the block editor. + +![Live Screen Preview Modal](../../assets/editor_screen_preview.png) + +--- + +## Real-time rendering with Docassemble stylesheets + +The Weaver renders screen previews using Docassemble's native stylesheets and JavaScript widgets, giving you a high-fidelity view of the actual layout, typography, buttons, and form inputs as they will appear when published. Mako expressions and conditional logic are shown as written, not evaluated — for behavior that depends on prior answers, use **Run the interview** instead. + +--- + +## Responsive viewports + +Users will access your interview from a wide variety of devices. The preview modal includes one-click viewport simulation: + +* **Desktop Viewport** (): Standard widescreen layout for laptops and desktop monitors. +* **Tablet Viewport** (): Medium layout matching iPad and tablet screen dimensions. +* **Phone Viewport** (): Compact mobile layout to test touch targets, vertical spacing, and responsive wrapping. + +--- + +## Visual styling and navigation toggles + +* **Labels**: Choose *Left of the field* (Docassemble's default), *Above the field*, or *Floating* to see how field prompts align. +* **Back button**: Preview the screen with the back button labeled *Undo* (AssemblyLine's default) or *Back*. +* **Dark**: Toggle a dark-mode simulation to verify contrast, icon visibility, and readable color palettes. + +--- + +## Running the live interview + +While the preview modal is great for rapidly testing individual screen layouts, you can launch the entire interactive interview at any time: + +1. Click **Run the interview** from within the preview modal, or click **Open interview** from the top navigation bar. +2. Docassemble will launch the interview in a new browser tab, allowing you to walk through the interview end-to-end, test dynamic logic, and generate completed documents. + +--- + +## Next steps + +* Insert standardized people questions using the [Question library](question_library.md). +* Organize your interview screens and loops in the [Interview order builder](interview_order.md). diff --git a/docs/authoring/weaver/screens_and_fields.md b/docs/authoring/weaver/screens_and_fields.md new file mode 100644 index 000000000..50463f59b --- /dev/null +++ b/docs/authoring/weaver/screens_and_fields.md @@ -0,0 +1,101 @@ +--- +id: weaver_screens_and_fields +title: | + Designing question screens and fields +sidebar_label: | + Question screens and fields +slug: screens_and_fields +--- + +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; + +Every screen presented to an interview user corresponds to a `question` block in Docassemble. The Weaver lets you configure every aspect of these screens visually without writing YAML syntax manually. + +![Main WYSIWYM Screen Editor Workspace](../../assets/editor_main_interview_screen.png) + +--- + +## Screen details and instructions + +When editing a question block in the canvas, the top section defines the screen identity and prompt: + +* **Block ID**: Specify a unique identifier for the screen (e.g. `case_information`). Standard AssemblyLine conventions use descriptive, snake_case identifiers. +* **Question title**: Enter the primary heading displayed at the top of the screen. +* **Subquestion**: Provide user-facing instructions or guidance using the rich formatting toolbar (bold, italics, links, lists, code spans, and headings). + +--- + +## Configuring form fields + +Under the **Fields** section, each row represents an interactive form control: + +| Setting | Description | +| :--- | :--- | +| **Label** | The user-visible prompt displayed beside or above the input field. | +| **Type** | The field data type (see table below). | +| **Variable name** | The Python variable where the user's response is stored (e.g., `court_name`, `user_pro_se`). | +| **Required** | Toggle switch to indicate whether the user must complete the field before continuing. | +| **Field Options ()** | Expand to set **default** (a pre-filled value), **hint** (short placeholder-style text shown inside the field), **help** (expandable help text), **under text** (a caption below the field), and **show if** / **hide if** conditional visibility expressions. | + +### Supported field data types + +The Weaver's field type picker exposes Docassemble's field datatypes, grouped by category. Common ones include: + +* **text** / **area**: Single-line or multiline text input. +* **yesno**, **yesnoradio**, **noyes**: Boolean yes/no questions in different layouts. +* **radio**: Single selection from a list of mutually exclusive choices. +* **dropdown** / **combobox** / **multiselect**: Dropdown selectors for lists of choices. +* **checkboxes**: Multiple selections from a list. +* **date** / **datetime** / **time**: Date and time pickers. +* **number** / **integer** / **currency**: Numeric and currency input. +* **email**: Email address field with format validation. +* **file** / **files** / **camera**: File upload and camera capture controls. +* **note** / **html**: Display-only content embedded within the fields list. + +There is no signature field type in this picker: AssemblyLine collects signatures through its own `basic_questions_signature_flow`, which the Weaver's generated interview order already calls before the download screen when a project needs one. + +--- + +## Conditional field visibility (show if) + +You can conditionally show or hide form fields based on earlier answers by clicking the **Field Options** icon () and adding a **show if** (or **hide if**) expression: + +```python +# Only show this field if the user answered 'Yes' to representing themselves +user_pro_se == True + +# Only show if a previous checkbox was selected +has_children and number_of_children > 0 +``` + +--- + +## Individual field types (name, address, gender, language) + +For a field collecting information about an individual person or party, choose one of the `ALIndividual` helper types from the **Assembly Line person fields** group in the Type picker instead of building each input by hand: + +* **name_fields** — Generates first name, middle name, last name, and suffix inputs. Adds a `- code: users[0].name_fields()` entry (or the equivalent person) to the block's `fields:` list. +* **address_fields** — Generates street address, unit/apartment, city, state, and zip code inputs. +* **gender_fields** — Inserts standard gender identity options. +* **pronoun_fields** — Inserts pronoun selection options. +* **language_fields** — Asks the person's primary language. + +Each of these has its own optional parameters (e.g. `show_suffix`, `required`, `show_if`) that appear once you select it. + +--- + +## AI drafting helpers + +When starting from a new set of labeled variables, you can speed up screen authoring using the built-in AI helpers: + +* **AI draft screen**: Analyzes the active screen's variables and drafts an appropriate plain-language title, explanatory subquestion, and field layout. +* **AI fields**: Suggests sensible field labels, data types, and default values matching legal plain-language standards. + +--- + +## Next steps + +* Learn how to [preview your screens in real time across desktop and mobile](screen_previews.md). +* Add pre-built people questions from the [Question library](question_library.md). +* Sequence the flow of your screens in the [Interview order builder](interview_order.md). diff --git a/docs/authoring/weaver_code_anatomy.md b/docs/authoring/weaver_code_anatomy.md deleted file mode 100644 index 11e125a6e..000000000 --- a/docs/authoring/weaver_code_anatomy.md +++ /dev/null @@ -1,487 +0,0 @@ ---- -id: yaml_anatomy -title: | - Appendix: Understanding the YAML code -sidebar_label: | - Appendix: Understanding the YAML code -slug: generated_yaml ---- - -The [ALWeaver](https://apps-dev.suffolklitlab.org/start/ALWeaver/assembly_line/#/1&new_session=1) generates code that is a starting point. It uses the [labels and variables you added to your documents](doc_vars_reference.md) to make an interview that uses questions and features from the AssemblyLine library. - -This page breaks down what each of these "blocks" (the sections of text that appear between `---`s) -do individually. You don't have to think about every block as you develop your interview, but as -you use more advanced features of [docassemble](https://docassemble.org/docs.html), knowing more about these blocks -will help. - -## Include - -An include block incorporates content (code blocks, questions blocks, etc.) from other YAML files. When you run the interview, docassemble acts as if all of the content in the YAML files listed below was copied and pasted right in this exact spot. -This is described in more detail in the [docassemble documentation](https://docassemble.org/docs/initial.html#include). - -This `include` block includes the AssemblyLine package, giving you access to all of the pre-created questions in AssemblyLine. It also adds the jurisdiction and organization packages that you picked in the Weaver. By default, the jurisdiction package is ALMassachusetts, and the organization package is the MassAccess package. - -```yml -include: - - docassemble.AssemblyLine:al_package.yml - - docassemble.ALMassachusetts:al_massachusetts.yml - - docassemble.MassAccess:massaccess.yml ---- -``` - -## Metadata - -These [metadata block](https://docassemble.org/docs/initial.html#metadata) values control two things: - -1. the text in this interview's browser tab -1. the name of the interview on a user's list of saved interviews if they're logged in - -You can explore some other settings that you can define here in the [docassemble documentation](https://docassemble.org/docs/initial.html#metadata). - -```yml -metadata: - title: | - 209a 258e motion for impoundment - short title: | - 209a 258e motion for impoundment - tags: - - BE-04-00-00-00 ---- -``` - -## Interview metadata and metadata for publishing on CourtFormsOnline - -Current AssemblyLine interviews use an expanded [metadata block](https://docassemble.org/docs/initial.html#metadata) that includes additional fields beyond the basic `title` and `short title`. This expanded metadata helps organizations better categorize, describe, and manage their interviews. - -:::info -The `interview_metadata` variable used in older AssemblyLine interviews is now deprecated. New interviews should include all metadata directly in the `metadata` block as shown below. -::: - -```yml -metadata: - title: | - 209a 258e motion for impoundment - short title: | - 209a 258e motion for impoundment - description: | - This interview helps you fill out a form to ask the court to keep - certain information in your 209A or 258 personal protection order - or restraining order case private (impounded). - authors: - - Jane Doe - - Suffolk LIT Lab - approved_by: - - name: Suffolk LIT Lab - url: https://suffolklitlab.org - logo: https://suffolklitlab.org/assets/logo.png - - name: Massachusetts Trial Court - url: https://www.mass.gov/info-details/trial-court - logo: https://www.mass.gov/files/styles/organization_logo/public/2025-08/Trial-Court-Seal-Final-color.png?itok=tQKsUwsu - can_I_use_this_form: | - You can use this form if you want to ask the court to keep some - information in your restraining order case private. This might include personal - information or details about your case. - before_you_start: | - Before you start, gather information about what specific details - you want the court to keep private and why this is necessary. - when_you_are_finished: | - When you are finished with this form, you need to download and file it with the - court. The court will either let you know when you need to appear to argue - your motion or they may decide based only on the paper that you file. - Either way, you will wait about a week for a letter from the court. - efiling_enabled: False - integrated_efiling: False - integrated_email_filing: False - requires_notarization: False - unlisted: False - landing_page_url: https://courtformsonline.org/ma/forms/209a-258e-motion-for-impoundment - maturity: production - estimated_completion_minutes: 15 - estimated_completion_delta: 5 - languages: - - en - help_page_url: https://www.mass.gov/info-details/impoundment - help_page_title: Information about Impoundment - LIST_topics: - - BE-04-00-00-00 - tags: - - BE-04-00-00-00 - jurisdiction: NAM-US-US+MA - original_form: https://www.mass.gov/forms/motion-for-impoundment - original_form_published_on: 2021-01-01 - review_date: 2024-01-01 - form_titles: - - Motion for Impoundment - form_numbers: - - MPC-123 - fees: - - Filing fee: 0.00 - footer: | - Created by Suffolk LIT Lab and community partners. - update_notes: | - Form created in 2021. Last reviewed 2024 with no changes needed. ---- -``` - -### CourtFormsOnline metadata fields currently used - -CourtFormsOnline currently reads and uses the following `metadata` keys from interview `/list?json=1` responses: - -1. `title` -1. `short title` -1. `description` -1. `can_I_use_this_form` -1. `before_you_start` -1. `help_page_url` -1. `help_page_title` -1. `original_form` -1. `original_form_published_on` -1. `review_date` -1. `form_titles` -1. `form_numbers` -1. `fees` -1. `LIST_topics` -1. `jurisdiction` -1. `maturity` -1. `efiling_enabled` -1. `integrated_efiling` -1. `integrated_email_filing` -1. `requires_notarization` -1. `estimated_completion_minutes` -1. `estimated_completion_delta` -1. `languages` -1. `unlisted` -1. `footer` -1. `update_notes` - -Newly supported metadata fields in CourtFormsOnline include: - -1. `efiling_enabled`: Used for form status labels (for example, e-filing available). -1. `integrated_efiling`: Alternative key for e-filing availability; supported by CourtFormsOnline. -1. `integrated_email_filing`: Alternative key for email-filing availability; supported by CourtFormsOnline. -1. `requires_notarization`: Shows a notary warning and links to the jurisdiction-specific notary guide. -1. `unlisted`: Hides interviews from CourtFormsOnline listings. -1. `footer`: Reserved custom footer text (currently normalized and available to components). - -### Expanded metadata fields - -1. **Basic information fields:** - - `title` and `short title`: Control the interview name in browser tabs and saved interview lists - - `description`: A detailed explanation of what the interview does and helps accomplish - - `can_I_use_this_form`: Helps users determine if this is the right form for their situation. - - `before_you_start`: Information users should gather or consider before beginning - - `when_you_are_finished`: Information users should know when they are finished. Optional; some generic information will be shown if omitted. - - `authors`: A list of people who contributed to the interview. Will be shown in the "about" page of the interview when it runs. - - `approved_by`: A list of organizations who officially approved the interview, will be shown with logo on the landing page to convey authority and promote trust. - -2. **Technical and administrative fields:** - - `maturity`: The development status (`production`, `development`, or `testing`) - - `estimated_completion_minutes`: How long most users take to complete the interview - - `estimated_completion_delta`: The typical variation in completion time (±) - - `languages`: List of language codes for available translations (e.g., `en`, `es`) - - `review_date`: When the interview should next be reviewed for updates - - `efiling_enabled`: Whether e-filing is available (boolean or `"email"` for email filing workflows) - - `integrated_efiling`: Alternative key for e-filing support; accepted by CourtFormsOnline - - `integrated_email_filing`: Alternative key for email filing support; accepted by CourtFormsOnline - - `requires_notarization`: Whether signing the completed form requires notarization - - `unlisted`: If `true`, excludes the interview from CourtFormsOnline listings - - `footer`: Optional custom footer content for downstream display/integrations - -3. **Help and reference fields:** - - `help_page_url`: Link to additional help resources - - `help_page_title`: Display name for the help page link - - `original_form`: URL to the original blank form being automated - - `original_form_published_on`: Publication date of the original form - - `landing_page_url`: URL to the landing page for the form, for help with back links. If it is not a subdomain of courtformsonline.org, the provided landing page will be used - instead of generating a landing page in the CourtFormsOnline.org site. - -4. **Classification and organization:** - - `LIST_topics`: [LIST taxonomy](https://taxonomy.legal/) codes (preferred method) - - `tags`: Fallback taxonomy codes if LIST_topics isn't available - - `jurisdiction`: Geographic scope using SALI/FOLIO jurisdiction codes (see https://openlegalstandard.org/), like NAM-US-US+MA (Usually just need to adjust the last two letters). Can be a list, like `['NAM-US-US+MA', 'NAM-US']` - - `form_titles`: Human-readable names of forms included - - `form_numbers`: Official form numbers, if assigned - - `fees`: Filing fees and other costs - -5. **Maintenance and updates:** - - `update_notes`: Record of changes and review history - -### Syndication tips - -If you would like your state's forms to be syndicated on CourtFormsOnline.org, you should include at least the following metadata: - -1. `title` -1. `short title` -1. `description` -1. `LIST_topics` -1. `jurisdiction` -1. `landing_page_url` - -When `landing_page_url` is provided, we will index your forms on the landing page, an `all forms` page for your jurisdiction, -and then link directly to your landing page from the individual form's card. - -## Main intro page - -Adds this text to the organization's intro page that appears at the beginning of every interview. This lets your user know right away that they have gotten to the right (or wrong) form. Note that this can (and should) be a more direct and detailed call to action, e.g. ("File a \_\_\_\_" or "Ask the court for \_\_\_\_"), rather than a simple short title, like the short title in the [metadata block](#metadata). - -```yml -code: | - interview_short_title = 'File a 209a 258e motion for impoundment' ---- -``` - -## Case type questions - -Changes the wording of AssemblyLine questions depending on its value. It can be either: - -- a court-case type: 'starts_case', 'existing_case', or 'appeal' -- a letter: 'letter' -- other: 'other', 'other_form' - -```yml -code: | - al_form_type = 'existing_case' ---- -``` - -## Navigation - -[`navigation`](https://docassemble.org/docs/initial.html#navigation%20bar) and [`sections`](https://docassemble.org/docs/initial.html#sections) work with [`nav.set_section()`](https://docassemble.org/docs/functions.html#DANav.show_sections) to show the column on the left that lets your users jump to a screen that lets them edit their information in your interview. -This helps users avoid using the 'Back' button which deletes their answers. - -By default, there is a single "Review" section, that covers the whole interview. In longer interviews, adding more sections can show the user a road map of what they will have to do and where they are now. - -```yml -sections: - - review_a_258e_motion_for_impoundment: Review your answers ---- -``` - -## Interview order - -Controls the order in which your screens are shown. - -The full interview order block will look something like this. We'll go over each line individually below. - -```yml -id: interview_order_a_258e_motion_for_impoundment -code: | - # Set the allowed courts for this interview (if needed) - # allowed_courts = ["Probate and Family Court", "District Court"] - nav.set_section("review_a_258e_motion_for_impoundment") - user_role ="plaintiff" - user_ask_role = "plaintiff" - one_of_your_custom_questions - users[0].phone_number - another_of_your_custom_questions - # Set the answer file name. - set_parts(subtitle=str(users)) - set_progress(16.67) - trial_court.division - interview_order_a_258e_motion_for_impoundment = True ---- -``` - -1. `allowed_courts` allows the developer to limit which courts the person filling out the form can pick from, making it easier for them to pick the right court. This is now configured directly in the interview code as shown above, rather than using the deprecated `interview_metadata` approach. This is currently used only in Massachusetts court forms. -1. `nav.set_section()` comes after `al_intro_screen` and `a_258e_motion_for_impoundment_intro` so that the user can't click to edit their answers before they've actually been asked any questions. -1. `user_role` and `user_ask_role` tell AssemblyLine which questions to ask about the main party and opposing parties listed on the form. These should be the same as the `typical role`. However, if `typical role` is `unknown`, then the `user_ask_role` variable will be here instead, and will ask the user what role they have in the case. - -Code for your custom questions comes next. All your questions should be triggered in here. You will probably make major edits to the code here, changing the order and adding branching logic. - -1. `set_parts(subtitle=str(users))` adds to the information a logged in user will see for this interview in their list of interviews. For an attorney, they should see the name of their clients. For a self represented litigant, they should see their name. You can read more about `set_parts` in the [docassemble documentation](https://docassemble.org/docs/functions.html#set_parts). -1. `set_progress()` changes the progress bar shown to the person who's interacting with the form. When they are at the beginning of the form, it should be empty. When they are at the end, other code will make sure it is full. The [ALWeaver](https://apps-dev.suffolklitlab.org/start/ALWeaver/assembly_line/#/1&new_session=1) tries to handle intermediate values between those two places that will make sense to the user. The example interview is short, so intermediate progress is only set once. -1. The final variable in the block (`interview_order_a_258e_motion_for_impoundment` above) is customized for your interview. It lets you trigger all the code in this entire code block. In this generated code, the [main order block](#main-order) triggers it. -If you are including this interview in another interview, remove the main order block. Then you can use this variable if you want to trigger this particular question order. - -## Main Order - -This block controls the order of things that do not need to be customized for your specific interview, like intro screens, signatures, etc. -You shouldn't have to change that code unless you are 🚧 combining multiple interviews together 🚧. - -```yml -mandatory: True -id: main_order_a_258e_motion_for_impoundment -code: | - al_intro_screen - a_258e_motion_for_impoundment_intro - # Interview order block has form-specific logic controlling order/branching - interview_order_a_258e_motion_for_impoundment_intro - signature_date - # Save (anonymized) interview statistics. - store_variables_snapshot(data={'zip': users[0].address.zip}) - a_258e_motion_for_impoundment_preview_question # Pre-canned preview screen - basic_questions_signature_flow - users[0].signature - a_258e_motion_for_impoundment_download ---- -``` - -There is some AssemblyLine code that comes after your own custom interview order code. You will probably leave this code alone as well: - -1. `signature_date` is the date that the user signed the form, and is needed on every form that has a signature. -1. `store_variables_snapshot()` lets you gather data about this interview session. _You should be very thoughtful about what you store, and care must be taken to anonymize it_. Just removing a name is not sufficient. - - If you want to avoid asking the user for their address, you will need to change the information you save here. This code forces the user's address to be asked. - -1. `a_258e_motion_for_impoundment_preview_question` will trigger [the preview screen](#preview). -1. `basic_questions_signature_flow` allows the user to pick what device to sign on. This lets them send the form to a smartphone for signing. -1. `users[0].signature` shows the user the signature screen. - -## Your screens - -These `question` blocks control the screens your clients will see that are specific to your interview. - -### Your interview's intro - -```yml -id: 209a 258e motion for impoundment -continue button field: a_258e_motion_for_impoundment_intro -question: | - 209a 258e motion for impoundment -subquestion: | - 209a 258e motion for impoundment ---- -``` - -### Preview - -Users can see the final form that they will then be signing before they sign it. - -```yml -id: Review your form before you sign it -continue button field: a_258e_motion_for_impoundment_preview_question -question: | - Review your form before you sign it -subquestion: | - Here is a preview of the form you'll sign on the next page. - - ${ al_user_bundle.as_pdf() } - - Remember to come back to this window to continue and sign your form. ---- -``` - -## Your questions - -[Question blocks](https://docassemble.org/docs/questions.html) will show screens with information and questions. You will probably edit these blocks as you identify your needs and the needs of the people using your tools. - -```yml -id: information to be impounded -question: | - Information to be impounded -subquestion: | - Information that you impound will be kept private from... TODO: add explanation. -fields: - - 'Impound personal information': impound_personal_information - datatype: yesno - - 'Impound case record information': impound_case_record_information - datatype: yesno - - 'Case record information to be impounded': case_record_information_to_be_impounded - maxlength: 340 - - 'Impound information ex parte': impound_information_ex_parte - datatype: yesno ---- -``` - -## Download - -Users will be able to download or email the form. They may sometimes be able to submit it to the court. - -```yml -progress: 100 -mandatory: True -id: download -question: | - Your form is ready to download and file -subquestion: | - Thank you ${users}. Your form is ready to download and deliver. - - Below is a preview of your form. - - ${ al_user_bundle.download_list_html() } -need: a_258e_motion_for_impoundment ---- -``` - -## Attachments - -### ALDocument - -Leave this block as it is if possible. Prepares to use this document in the `ALDocumentBundle`. - -Usually you need to make at least two different attachment blocks for a PDF: a preview without a signature and the final document with a signature. -The ALDocument class takes care of that for you. It also contains some nice features like adding addenda if -an interviewee's answers are too long. - -```yml -objects: - - a_258e_motion_for_impoundment_attachment: ALDocument.using(title="209a 258e motion for impoundment", filename="209a_258e_motion_for_impoundment", enabled=True, has_addendum=False) ---- -``` - -### ALDocumentBundle - -Leave this block as it is if possible. Adds your file to two 'bundles' automatically - one for the user and one for the court. - -The ALDocumentBundle class lets you combine files in different ways easily. For example, when sending a packet to the court you might want to add a cover page, but when sending one to the client you might want to include an instruction sheet instead. With the ALDocumentBundle class, this is as simple as adding the new attachment to the -`elements` parameter below. - -```yml -objects: - - al_user_bundle: ALDocumentBundle.using(elements=[a_258e_motion_for_impoundment_attachment], filename="209a_258e_motion_for_impoundment.pdf", title="All forms to download for your records") - - al_court_bundle: ALDocumentBundle.using(elements=[a_258e_motion_for_impoundment_attachment], filename="209a_258e_motion_for_impoundment.pdf", title="All forms to download for your records") ---- -``` - -### Attachment block - -An [attachment block](https://docassemble.org/docs/documents.html#attachment) for a PDF. This is how you will put your user's answers into a PDF's fields. You will have one for every PDF in your form. Its name is based on your PDF file name. - -[How to fill in your PDF fields with docassemble](https://docassemble.org/docs/documents.html#pdf%20template%20file). - -```yml -attachment: - name: 209a 258e motion for impoundment - filename: a-258e-motion-for-impoundment - variable name: a_258e_motion_for_impoundment_attachment[i] - skip undefined: True - pdf template file: 209a_258e_motion_for_impoundment.pdf - fields: - - "signature_date": ${ signature_date } - # It's a signature: test which file version this is; leave empty unless it's the final version - - "user_signature": ${ users[0].signature if i == 'final' else '' } - - "impound_personal_information": ${ impound_personal_information } - - "impound_case_record_information": ${ impound_case_record_information } - - "case_record_information_to_be_impounded": ${ case_record_information_to_be_impounded } - - "impound_information_ex_parte": ${ impound_information_ex_parte } - - "request_based_on": ${ request_based_on } - - "attach_additional_pages": ${ attach_additional_pages } - - "motion_allowed_ex_parte": ${ motion_allowed_ex_parte } - - "motion_allowed_after_hearing": ${ motion_allowed_after_hearing } - - "motion_denied": ${ motion_denied } ---- -``` - -## Review screen - -The 'Back' button deletes answers as the user goes farther back. When they press to continue, they will have to fill in their answers again. The review screen lets them edit their answers without deleting any of them. - -The code generated for this section is just a starting point. You will probably have to make changes to get what you need. - -```yml -id: a_258e_motion_for_impoundment review screen -event: review_a_258e_motion_for_impoundment -question: | - Review Screen -subquestion: | - Edit your answers below -review: - - Edit: impound_personal_information - button: | - **Impound personal information**: - ${ word(yesno(impound_personal_information)) } -``` - -There might be additional blocks that start like `continue button field: users.revisit` or `table: users.table`. -These blocks are used by the review screen to display and edit multiple pieces of information, like plaintiffs -and their contact information. diff --git a/docs/authoring/weaver_overview.md b/docs/authoring/weaver_overview.md deleted file mode 100644 index 0e50e5402..000000000 --- a/docs/authoring/weaver_overview.md +++ /dev/null @@ -1,115 +0,0 @@ ---- -id: alweaver_overview -title: | - "Weaving" your form into a draft interview -sidebar_label: | - "Weaving" your form into a draft interview -slug: generating_code ---- - - - -After your document is fully [labeled](doc_vars_reference.md), the next step is -to automate a draft in the [Document Assembly Line -Weaver](https://apps-dev.suffolklitlab.org/start/ALWeaver/assembly_line?new_session=1) -(ALWeaver). - -## Philosophy - -The Assembly Line Weaver is a tool that helps you create a draft of a guided -interview. You should not spend very much of your time at this stage. - -Use the Weaver to: - -1. make sure you are using Assembly Line conventions -1. get draft text in the right place, so you can easily find and edit it later -1. get a runnable prototype so that you can start getting expert feedback - -We designed the Weaver to produce clean, maintainable code. We do not -intend it to work the way that fully no-code solutions work, which often -are easy to use for simple features but produce code that is challenging -to edit manually. - -### Limits of the Weaver - -The Assembly Line Weaver does allow you to reorder screens. However: -you will not be able to add **any** logic in the Weaver process. - -This is by design. We want you to quickly get to the docassemble playground -to continue editing your code. - -## Before you use the Weaver - -* Make sure you got the [field labels](label_variables) (variable names) right: - * Use the Assembly Line variable names for things like `users` and `other_parties`. - * Double-check the order of word "suffixes" like `name_first` and `address_unit` (they go big to small). - * In PDFs, make sure you used `__1`, `__2` etc at the end of a variable name if you had to repeat it in the same document. -* Rename the document to remove any extra "stuff", like -01, _final, _labeled, etc. The filename will get reused throughout your project. -* Plan to finish using the Weaver in one sitting, most of the time. It is easier to customize in the playground, and harder to go - back to your older Weaver session. - -## What the Weaver does - -The steps that the Weaver will walk you through are as follows: - -1. validate the labels and your template file -1. add some basic information about your form -1. add on-screen prompts for each labeled field -1. choose a datatype for each labeled field (for example: text, number, date) -1. organize the fields onto individual screens with headings and optional additional text -1. download a completed, runnable draft interview - -[Launch the Assembly Line Weaver](https://apps-dev.suffolklitlab.org/start/ALWeaver/assembly_line?new_session=1) - - - -## Information you will be asked - -To prepare to run your form through the Weaver, think about how you will answer -the questions listed below: - -* a short label for your form that is used to build unique variable names, like: - `restraining_order_209A` -* a title for your interview -* a short description -* draft text that orients your user to what they need before they start working - on your form -* whether the user is usually the plaintiff, defendant or could play either role -* the names of authors of your interview (usually, just you!) -* the country and state the form is from -* the category for your form -* the step in a court process that your form is filed: e.g., starting a case, - filed as an appeal -* the list of courts your form can be filed in -* the total number of each kind of "person" that can appear on the form. e.g., - can multiple plaintiffs file at once, or just one? - -New features are regularly added to the Weaver, so the exact list of questions -you will be asked may change. - -## Download your interview at the end - -When you have finished using the Weaver, download your package. This will put a -.zip file in the Downloads folder on your computer. - -Next, upload this file to the docassemble playground's `Packages` folder. - -![Folders | Packages ](../assets/playground_packages_menu.png) - -:::warning If you are using Safari on a Mac OS computer -Safari, by default, will turn your downloaded package into -a folder on your PC. - -Before downloading the package, turn off that behavior: - -1. open Safari -1. click Preferences -1. under the General tab, uncheck the option **Open 'safe' files after downloading** -::: - -## Example of a page in a docassemble interview -A page might look like this: - -![One page of an interview made up of a heading, explanatory text, and the fields](../assets/interview_screen_or_page.png) - -You can see [the ALWeaver docassemble package on GitHub](https://github.com/suffolkLITLab/docassemble-ALWeaver) diff --git a/docs/authoring/writing_review_screen.md b/docs/authoring/writing_review_screen.md index 8b0b33be5..4747edc58 100644 --- a/docs/authoring/writing_review_screen.md +++ b/docs/authoring/writing_review_screen.md @@ -11,6 +11,10 @@ slug: review_screen In docassemble, a review screen is the way that a user can make changes to their answers. A review screen displays one or more of the user's existing answers along with buttons that let the user edit each choice. +:::tip Synchronized review screens in the Weaver +If you are building your interview with the [Assembly Line Weaver](weaver/overview.md), review screens are automatically synchronized with your question blocks. See the [Weaver review screen guide](weaver/review_screens.md) for details on visual editing and jump-back linking. +::: + This page is a step-by-step tutorial on how to write a review screen, and covers: - [Overview](#overview) @@ -178,7 +182,7 @@ There are a few sections of the generated review screen YAML: But your interview might include [objects](https://docassemble.org/docs/objects.html#Individual) and lists of objects, like a list of plaintiffs and another list of defendants. Instead of re-asking every question that someone answered to fill the list, docassemble brings to the user to a `revisit` screen that shows each item in the list to the user, and lets them choose which to edit individually. - If you used the [Weaver](doc_vars_reference.md#standard-roles) to make your interview, your interview might have a few different lists for people, + If you used the [Weaver](weaver/overview.md) to make your interview, your interview might have a few different lists for people, like `users`, `other_parties`, `children`, `debt_collectors`, and `guardians`. 4. The `revisit` screens each show the `table` attribute of the `DAList`. If needed, blocks defining the table for the lists will appear at the end of the generated review file. diff --git a/docs/components/ALToolbox/al_income_expenses.md b/docs/components/ALToolbox/al_income_expenses.md index cd9800e9c..1146f9c5c 100644 --- a/docs/components/ALToolbox/al_income_expenses.md +++ b/docs/components/ALToolbox/al_income_expenses.md @@ -270,4 +270,4 @@ subquestion: | -You'll likely want to display this information in a PDF or word template as well. [This section describing the Attachment block](../../authoring/weaver_code_anatomy.md#attachment-block) will help with displaying information in the PDF, and [this page about working with DOCX files](../../authoring/docx_templates.md) will help DOCX users. +You'll likely want to display this information in a PDF or word template as well. [This page about working with PDF files](../../authoring/pdf_templates.md) will help with displaying information in the PDF, and [this page about working with DOCX files](../../authoring/docx_templates.md) will help DOCX users. diff --git a/docs/components/ALToolbox/al_income_itemizedjobs.md b/docs/components/ALToolbox/al_income_itemizedjobs.md index 97c9621f7..463210477 100644 --- a/docs/components/ALToolbox/al_income_itemizedjobs.md +++ b/docs/components/ALToolbox/al_income_itemizedjobs.md @@ -191,4 +191,4 @@ subquestion: | -You'll likely want to display this information in a PDF or word template as well. [This section describing the Attachment block](../../authoring/weaver_code_anatomy.md#attachment-block) will help with displaying information in the PDF, and [this page about working with DOCX files](../../authoring/docx_templates.md) will help DOCX users. +You'll likely want to display this information in a PDF or word template as well. [This page about working with PDF files](../../authoring/pdf_templates.md) will help with displaying information in the PDF, and [this page about working with DOCX files](../../authoring/docx_templates.md) will help DOCX users. diff --git a/docs/components/ALToolbox/al_income_jobs.md b/docs/components/ALToolbox/al_income_jobs.md index 2800bc130..2bb0528af 100644 --- a/docs/components/ALToolbox/al_income_jobs.md +++ b/docs/components/ALToolbox/al_income_jobs.md @@ -183,4 +183,4 @@ subquestion: | -You'll likely want to display this information in a PDF or word template as well. [This section describing the Attachment block](../../authoring/weaver_code_anatomy.md#attachment-block) will help with displaying information in the PDF, and [this page about working with DOCX files](../../authoring/docx_templates.md) will help DOCX users. +You'll likely want to display this information in a PDF or word template as well. [This page about working with PDF files](../../authoring/pdf_templates.md) will help with displaying information in the PDF, and [this page about working with DOCX files](../../authoring/docx_templates.md) will help DOCX users. diff --git a/docs/components/EFSPIntegration/efiling_case_search.md b/docs/components/EFSPIntegration/efiling_case_search.md index 975217b80..7894c0535 100644 --- a/docs/components/EFSPIntegration/efiling_case_search.md +++ b/docs/components/EFSPIntegration/efiling_case_search.md @@ -119,7 +119,7 @@ from the `case_search.found_case`, the variable for the found case. The `details ### Using case search data in your Assembly Line interview -You are likely using the [ALWeaver](../../authoring/weaver_overview.md) and the rest of the Assembly Line framework +You are likely using the [Weaver](../../authoring/weaver/overview.md) and the rest of the Assembly Line framework in your docassemble interview, and you will want to put this information from the case search into variables that your interview knows about, like `users` and `other_parties`. To do this, we can add some more code to the above example: diff --git a/docs/get_started/al_project_architecture.md b/docs/get_started/al_project_architecture.md index 0b0083e46..e8084c419 100644 --- a/docs/get_started/al_project_architecture.md +++ b/docs/get_started/al_project_architecture.md @@ -16,7 +16,7 @@ Below is a snapshot of the Project's overall architecture as of **June 2022**. W | Component | Description | GitHub Repository | |:----------|:------------|:------------------| | [AssemblyLine](https://github.com/suffolkLITLab/docassemble-AssemblyLine) | Utility library that makes it easier to use certain docassemble features in an interview. | [SuffolkLITLab/docassemble-AssemblyLine](https://github.com/SuffolkLITLab/docassemble-AssemblyLine) | -| [ALWeaver](../authoring/weaver_overview.md) | Helps create a draft interviews from PDF and DOCX forms. | [suffolkLITLab/docassemble-ALWeaver](https://github.com/SuffolkLITLab/docassemble-ALWeaver) | +| [The Weaver](../authoring/weaver/overview.md) | Helps create and visually author interviews from PDF and DOCX forms. | [SuffolkLITLab/docassemble-ALWeaver](https://github.com/SuffolkLITLab/docassemble-ALWeaver) | | [ALToolbox](https://github.com/SuffolkLITLab/docassemble-ALToolbox) | Utility functions and components that are used in AssemblyLine but that can be easily used by docassemble developers who use other platforms. | [SuffolkLITLab/docassemble-ALToolbox](https://github.com/SuffolkLITLab/docassemble-ALToolbox) | | [ALKiln](../components/ALKiln/intro.mdx) | Automated testing framework that acts like a user, following your instructions to do things like fill in fields, upload files, sign in, and check your PDFs for accuracy. | [SuffolkLITLab/ALKiln](https://github.com/SuffolkLITLab/ALKiln) | | [ALDashboard](/docs/components/ALDashboard/overview) | A collection of tools to help administer a docassemble server and debug interviews. | [SuffolkLITLab/docassemble-ALDashboard](https://github.com/SuffolkLITLab/docassemble-ALDashboard) | diff --git a/docs/get_started/installation.md b/docs/get_started/installation.md index b8eb571e5..a7830a31f 100644 --- a/docs/get_started/installation.md +++ b/docs/get_started/installation.md @@ -92,9 +92,9 @@ fork the ALThemeTemplate package as docassemble makes it challenging to rename a package. ::: -### Using your ALThemeTemplate with the ALWeaver +### Using your ALThemeTemplate with the Weaver -If you plan on using the [ALWeaver](../authoring/weaver_overview.md) to create your +If you plan on using the [Weaver](../authoring/weaver/overview.md) to create your interviews, you will want to include your branding package in your weaved interviews. You can do this by adding 2 files to your branding package: diff --git a/docs/get_started/intro.md b/docs/get_started/intro.md index 034e359f3..750c15e2b 100644 --- a/docs/get_started/intro.md +++ b/docs/get_started/intro.md @@ -24,7 +24,7 @@ This short, 3-minute video by David Colarusso and Quinten Steenhuis explains how The LIT Lab gathered more than 200 volunteers from around the world with the goal of making it easier to build online guided interviews with docassemble. The initial tools included: * The core [AssemblyLine tools](https://github.com/SuffolkLITLab/docassemble-AssemblyLine), to make it easier to use key docassemble features -* The [the Weaver](../authoring/weaver_overview.md), a tool for converting existing PDF and DOCX court forms into draft docassemble interviews in as little as one hour +* [The Weaver](../authoring/weaver/overview.md), a visual authoring tool for converting existing PDF and DOCX court forms into production-ready Docassemble interviews * A [question library](../style_guide/question_library/names.md) of pre-built, commonly used, accessible questions, vetted by experts and translated into at least 5 languages * An [open-source, non-profit e-filing service provider (EFSP)](components/EFSPIntegration/efsp_overview.md) for integrating docassemble interviews with e-filing management systems * A [style guide](../style_guide/question_style_overview.md) for interview questions that are easy to read and answer diff --git a/docs/get_started/landing_pages.md b/docs/get_started/landing_pages.md index e4bdb693c..334b2f6a4 100644 --- a/docs/get_started/landing_pages.md +++ b/docs/get_started/landing_pages.md @@ -14,8 +14,8 @@ live. You can build a landing page in a dedicated web application like CourtFormsOnline (we use Next.js), or in a legal help site built on a technology like [Drupal](https://drupal.org) or [WordPress](https://wordpress.org). -The [metadata](../authoring/weaver_code_anatomy.md#interview-metadata-and-metadata-for-publishing-on-courtformsonline) -block in an interview created by the [AssemblyLine Weaver](../authoring/weaver_overview.md) will help you automatically +The [metadata](../authoring/weaver/publishing_and_github.md) +block in an interview created by the [AssemblyLine Weaver](../authoring/weaver/overview.md) will help you automatically create a landing page with relevant content for publishing on CourtFormsOnline. ## Why landing pages matter diff --git a/docs/get_started/plan_interview.md b/docs/get_started/plan_interview.md index dd54333af..fa7c122de 100644 --- a/docs/get_started/plan_interview.md +++ b/docs/get_started/plan_interview.md @@ -203,4 +203,4 @@ Start by learning about the automation process for your template, whether it is: * A [PDF](../authoring/pdf_templates.md), or * A [DOCX](../authoring/docx_templates.md) file. -And then continuing through [labeling](../authoring/doc_vars_reference.md) and running your template through the Weaver(../authoring/weaver_overview.md). +And then continuing through [labeling](../authoring/doc_vars_reference.md) and building your interview with the [Weaver](../authoring/weaver/overview.md). diff --git a/docusaurus.config.js b/docusaurus.config.js index b35da10c7..7917b8117 100644 --- a/docusaurus.config.js +++ b/docusaurus.config.js @@ -12,6 +12,9 @@ module.exports = { favicon: 'img/favicon.ico', organizationName: 'SuffolkLITLab', // the GitHub org name. projectName: 'AssemblyLine-docs', // the repo name. + clientModules: [ + require.resolve('./src/js/gtag-stub.js'), + ], themeConfig: { // Keep for the next LIT Con // announcementBar: { diff --git a/sidebars.js b/sidebars.js index 81c079484..2fbf0a57b 100644 --- a/sidebars.js +++ b/sidebars.js @@ -107,12 +107,27 @@ module.exports = { 'authoring/dynamic_phrasing_based_on_values', 'authoring/document_variables_reference', 'authoring/name_formats', - 'authoring/alweaver_overview', + { + label: 'The Assembly Line Weaver', + type: 'category', + collapsed: false, + items: [ + 'authoring/weaver/weaver_overview', + 'authoring/weaver/weaver_screens_and_fields', + 'authoring/weaver/weaver_screen_previews', + 'authoring/weaver/weaver_question_library', + 'authoring/weaver/weaver_interview_order', + 'authoring/weaver/weaver_document_bundles', + 'authoring/weaver/weaver_review_screens', + 'authoring/weaver/weaver_diagnostics_and_refactoring', + 'authoring/weaver/weaver_publishing_and_github', + 'authoring/weaver/weaver_authoring_checklist', + ], + }, 'authoring/github', 'authoring/customizing_interview', 'authoring/combining-interviews', 'authoring/writing_review_screen', - 'authoring/yaml_anatomy', { label: 'Coding with AI assistance', type: 'category', diff --git a/src/js/gtag-stub.js b/src/js/gtag-stub.js new file mode 100644 index 000000000..0cfd513a2 --- /dev/null +++ b/src/js/gtag-stub.js @@ -0,0 +1,10 @@ +// Ensure window.gtag is always defined as a callable function in development mode +// to prevent @docusaurus/plugin-google-gtag from throwing TypeError on route navigation. +if (typeof window !== 'undefined') { + window.dataLayer = window.dataLayer || []; + if (typeof window.gtag !== 'function') { + window.gtag = function () { + window.dataLayer.push(arguments); + }; + } +}