raw html field type; recipe for inserting Bootstrap accordion using r…

…aw html

_data/example.yml

@@ -13115,6 +13115,20 @@
         step: 10
         default: 10
         scale: logarithmic
+"raw-html":
+  "height": !!int |-
+    188
+  "width": !!int |-
+    488
+  "yaml": |-
+    question: |
+      What is your favorite fruit?
+    fields:
+      - raw html: |
+          <div class="p-4 mb-3 rounded bg-danger">
+      - Favorite fruit: favorite_fruit
+      - raw html: |
+          </div>
 "read-qr":
   "height": !!int |-
     515
@@ -21015,6 +21029,118 @@
         docx template file: tagged.docx
         tagged pdf: True
     mandatory: True
+"testaccordion1":
+  "height": !!int |-
+    450
+  "width": !!int |-
+    488
+  "yaml": |-
+    modules:
+      - docassemble.demo.accordion
+    ---
+    event: review_screen
+    question: |
+      Please review your answers.
+    review:
+      - raw html: |
+          ${ start_accordion('Pets', showing=True) }
+      - Edit: favorite_cat
+        button: |
+          You said your favorite cat was
+          **${ favorite_fruit }**.
+      - Edit: favorite_vegetable
+        button: |
+          You said your favorite dog was
+          **${ favorite_dog }**.
+      - raw html: |
+          ${ next_accordion('Food') }
+      - Edit: favorite_fruit
+        button: |
+          You said your favorite fruit was
+          **${ favorite_fruit }**.
+      - Edit: favorite_vegetable
+        button: |
+          You said your favorite vegetable was
+          **${ favorite_vegetable }**.
+      - raw html: |
+          ${ next_accordion('Aesthetics') }
+      - Edit: fashion_aesthetic
+        button: |
+          You said your fashion aesthetic was
+          **${ fashion_aesthetic }**.
+      - Edit: decor_aesthetic
+        button: |
+          You said your home decor aesthetic was
+          **${ decor_aesthetic }**.
+      - raw html: |
+          ${ end_accordion() }
+"testaccordion2":
+  "height": !!int |-
+    438
+  "width": !!int |-
+    488
+  "yaml": |-
+    modules:
+      - docassemble.demo.accordion
+    ---
+    question: |
+      Tell me about your preferences
+    fields:
+      - raw html: |
+          ${ start_accordion('Pets', showing=True) }
+      - Favorite cat: favorite_cat
+      - Favorite dog: favorite_dog
+      - raw html: |
+          ${ next_accordion('Food') }
+      - Favorite fruit: favorite_fruit
+        required: False
+      - Favorite vegetable: favorite_vegetable
+        required: False
+      - Favorite meat dish: favorite_meat_dish
+        show if:
+          variable: favorite_dog
+          is: spaniel
+      - raw html: |
+          ${ next_accordion('Aesthetics') }
+      - Fashion aesthetic: fashion_aesthetic
+        required: False
+      - Decor aesthetic: decor_aesthetic
+        required: False
+      - raw html: ${ end_accordion() }
+"testaccordion3":
+  "height": !!int |-
+    309
+  "width": !!int |-
+    488
+  "yaml": "modules:\n  - docassemble.demo.accordion\n---\nquestion: |\n  Welcome to\
+    \ the interview.\nsubquestion:\n  This interview will determine a recommended\
+    \ direction\n  for your life.\n  \n  ${ start_accordion('What do I need to know\
+    \ before starting?') }\n\n  Modernipsum dolor sit amet illusionism cubo-futurism\
+    \ international\n  gothic historicism, neo-minimalism divisionism cobra intervention\n\
+    \  art art nouveau. Installation art futurism les nabis academic hudson\n  river\
+    \ school young british artists, romanticism neo-expressionism\n  street art orphism,\
+    \ lyrical abstraction avant-garde remodernism\n  vorticism. Divisionism caravaggisti\
+    \ die br\xFCcke tachisme\n  impressionism, gothic art luminism illusionism op\
+    \ art neoclassicism,\n  street art situationist international neoism. Orphism\
+    \ russian\n  symbolism academic ego-futurism kinetic art neo-dada dada stuckism\n\
+    \  international gr\xFCnderzeit, post-impressionism impressionism\n  postmodernism\
+    \ maximalism precisionism post-painterly\n  abstraction. Russian symbolism superflat\
+    \ new media art jugendstil\n  maximalism illusionism, gr\xFCnderzeit scuola romana\
+    \ merovingian\n  rayonism secularism, existentialism op art action painting lyrical\n\
+    \  abstraction.\n  \n  ${ next_accordion('What do I do after I finish the interview?')\
+    \ }\n\n  Metaphysical art barbizon school carolingian neo-minimalism\n  primitivism\
+    \ superflat neo-minimalism naturalism, der blaue reiter\n  hard-edge painting\
+    \ new media art fluxus superstroke\n  monumentalism. Art deco russian futurism\
+    \ cubo-futurism pop art\n  relational art neo-expressionism, synchromism pre-raphaelites\
+    \ sound\n  art photorealism classicism, surrealism gothic art hudson river\n \
+    \ school scuola romana. Rococo biedermeier cloisonnism secularism\n  hudson river\
+    \ school fluxus, modernism, ego-futurism formalism\n  manierism, gr\xFCnderzeit\
+    \ deformalism abstract expressionism\n  postmodernism. Classicism postminimalism\
+    \ superstroke lowbrow\n  tonalism fauvism color field painting systems art, biedermeier\n\
+    \  post-impressionism hyperrealism structuralism neoclassicism. Dada\n  tachisme\
+    \ luminism manierism surrealism, avant-garde performance art\n  neoclassicism\
+    \ hard-edge painting neo-impressionism, nouveau realisme\n  eclecticism tonalism.\n\
+    \  \n  ${ end_accordion() }\ncontinue button field: intro"
 "testcards":
   "height": !!int |-
     334

_docs/changelog.md

@@ -3,6 +3,14 @@ layout: docs
 title: Change Log
 short_title: Change Log
 ---
+## [1.4.94](https://github.com/jhpyle/docassemble/releases/tag/v1.4.94) - 2024-01-23
+
+
+### Added
+- The `raw html` special field type under `fields` and `review`. This
+  is similar to `html` but allows modification of the structure of the
+  HTML in the list as a whole.
+
 ## [1.4.93](https://github.com/jhpyle/docassemble/releases/tag/v1.4.93) - 2024-01-20
 
 

_docs/fields.md

@@ -2013,6 +2013,24 @@ the HTML will appear after the field:
 
 {% include side-by-side.html demo="side-html" %}
 
+## <a name="raw html"></a>`raw html`
+
+`raw html` is like [`html`](#html), except that the HTML is not placed
+into a `<div>`; it is simply inserted into the page without any
+enclosing elements. This allows you to alter the structure of the HTML
+in the list of fields.
+
+{% include side-by-side.html demo="raw-html" %}
+
+The `help` and `under text` modifiers have no effect on a `raw html`
+field. If `raw html` is used as a modifier for a field, it will act
+just like `html`.
+
+Note that when using the `tabular` form of a `review` list, the `raw
+html` will go into the `<tbody>` of the `<table>`, where a `<tr>`
+would normally be placed. Otherwise, the `raw html` will be inserted
+into the `<form>` element.
+
 ## <a name="no label"></a>`no label`
 
 If you use `no label` as the label for your variable, the label will

_docs/recipes.md

@@ -228,6 +228,50 @@ def prog_disclose(template, classname=None):
 
 This uses the [collapse feature] of [Bootstrap].
 
+# <a name="accordion"></a>Accordion user interface
+
+Helper functions defined in a module file can be useful for inserting
+complex HTML into your `question` blocks without making the `question`
+blocks less readable.
+
+In the [`docassemble.demo`] package, there is a module,
+[`docassemble.demo.accordion`], which demonstrates a set of functions,
+`start_accordion()`, `next_accordion()`, and `end_accordion()`, that
+return HTML.
+
+The following example demonstrates how to use the functions exported
+by [`docassemble.demo.accordion`] to create an accordion interface in
+a `review` screen, using the [accordion feature] of [Bootstrap].
+
+{% include demo-side-by-side.html demo="testaccordion1" %}
+
+The same could be done with a `fields` list.
+
+{% include demo-side-by-side.html demo="testaccordion2" %}
+
+The above two examples make use of the [`raw html`] feature that was
+introduced in version 1.4.94.
+
+The functions in [`docassemble.demo.accordion`] can also be used in
+other parts of a screen, such as the `subquestion`.
+
+{% include demo-side-by-side.html demo="testaccordion3" %}
+
+When using functions like these that change the HTML structure of the
+screen, it is very important not to forget to call the functions that
+insert closing HTML tags, like `end_accordion()` in this example. If
+the correct functions are not called, the HTML of the screen could be
+invalid.
+
+**docassemble** add-on packages could be created that offer user
+interface enhancements invoked through functions. In the examples
+above, the functionality was imported through a `modules` block, but
+it would also be possible to instruct users of an add-on package to
+use an `include` block to activate the functionality. The `include`
+block could point to a file in the `questions` folder of the add-on
+package that contains a `modules` block that imports the functions, as
+well as a `features` block that activates custom JavaScript and CSS.
+
 # <a name="cards"></a>Displaying cards
 
 [Bootstrap] has a component called a [Card] that puts text in a box
@@ -2918,3 +2962,7 @@ class.
 [`background_action()`]: {{ site.baseurl }}/docs/background.html#background_action
 [`celery modules`]: {{ site.baseurl }}/docs/config.html#celery modules
 [`upload-handler.yml`]: https://github.com/jhpyle/docassemble/blob/master/docassemble_demo/docassemble/demo/data/questions/examples/upload-handler.yml
+[`raw html`]: {{ site.baseurl }}/docs/fields.html#raw html
+[accordion feature]: https://getbootstrap.com/docs/5.3/components/accordion/
+[`docassemble.demo`]: https://github.com/jhpyle/docassemble/tree/master/docassemble_demo
+[`docassemble.demo.accordion`]: https://github.com/jhpyle/docassemble/blob/master/docassemble_demo/docassemble/demo/accordion.py