index.html

<!doctype html>
<html>

<head>
	<meta charset="utf-8">
	<meta name="viewport" content="width=device-width, initial-scale=1.0, maximum-scale=1.0, user-scalable=no">

	<title>The Form API Workflow</title>
	<link rel="stylesheet" href="dist/reset.css">
	<link rel="stylesheet" href="dist/reveal.css">
	<link rel="stylesheet" href="dist/theme/white.css">
	<link
		href="https://fonts.googleapis.com/css?family=Montserrat:100,100i,200,200i,300,300i,400,400i,500,500i,600,600i,700,700i,800,800i,900,900i"
		rel="stylesheet">
	<link rel="stylesheet" href="./assets/css/custom.css">

	<!-- Theme used for syntax highlighted code -->
	<link rel="stylesheet" href="plugin/highlight/monokai.css">
</head>

<body>

	<div class="specifi-elems-container">

		<div class="event-logo-container">
			<a href="https://events.drupal.org/prague2022">
				<img src="./assets/images/dcon_03_logo_horizontal.png" class="dcon2022-logo" />
			</a>
		</div>
	</div>


	<div class="reveal">
		<div class="slides">
			<section>

				<div class="r-vstack main-title">
					<p class="logo">
						<img class="" width="20%" src="./assets/images/dcon_07_logo_vertical.png" />
					</p>
					<p>
						<span class="title">The Form API Workflow</span>
					</p>
					<p>
						<span class="author">Ricardo Sanz / tunic</span>
					</p>
					<div class="spacer"></div>
					<div class="spacer"></div>
					<div class="spacer"></div>
				</div>
			</section>


			<section>
				<img src="./assets/images/sanzante.jpg" class="profile-photo">
				<p>
					<span>Ricardo Sanz</span>
					<br>
					<span class="xsmall"><em>Drupal Developer &amp; DevOps</em></span>
					<br>
					<a class="xsmall" href="https://drupal.org/u/tunic" target="_blank">drupal.org/u/tunic</a>
					<br>
					<a class="xsmall" href="https://twitter.com/sanzante" target="_blank">sanzante @ Twitter</a>
				</p>
				<a href="https://metadrop.net"><img src="./assets/images/metadrop-logo.svg" class="metadrop-logo logo"></a>
				<div class="spacer"></div>
				<span class="xxsmall"><em>See <a href="https://rsanzante.github.io/drupalconprague-2022-form-api-workflow/">online presentation</a> for the best experience</em></span>
			</section>


			<section>
				<div class="header">
					<span>Walktrough</span>
				</div>
				<div class="r-hstack">
					<ul class="column">
						<li>The Form API</li>
						<li>Simplified workflow</li>
						<li>Form API stages</li>
					</ul>
					<ul class="column">
						<li>Cache / Persistence</li>
						<li>AJAX requests</li>
						<li>Complete workflow</li>
						<li>Key points</li>
					</ul>
				</div>
			</section>


			<section data-state="chapter" data-background-image="./assets/images/dcon_04_color_background.jpg">
				<div class="chapter-cover">
					<span class="title">The Form API</span>
				</div>
			</section>


			<section>
				<div class="header">
					<span>Form API: What is</span>
				</div>
				<ul>
					<li>An abstraction of HTML forms</li>
					<li>Handles submit, persistence, altering and rendering</li>
					<li>Security!</li>
					<li>Handles AJAX in forms</li>
					<li>Allows alterations</li>
					<li>Safety!</li>
					<li>Build custom forms</li>
				</ul>
			</section>


			<section>
				<div class="header">
					<span>Form API: How?</span>
				</div>
				<ul>
					<li>"form_builder" service handles forms</li>
					<li>Many classes involved: FormBuilder, FormValidator, FormBase, etc.</li>
					<li>A class that implements a form (extends from FormBase)</li>
					<li>A form array (usually <span class="code">$form</span>)</li>
					<li>A form state (usualy <span class="code">$form_state</span>)</li>

				</ul>

			</section>


			<section>
				<div class="header">
					<span>The Form Array</span>
				</div>
				<ul>
					<li>PHP array</li>
					<li>Structure and behavior</li>
					<li>Not exactly a Render Array</li>
					<li>Available during all Form API stages</li>
					<li>It is changed during stages</li>
				</ul>

			</section>


			<section>
				<div class="header">
					<span>The Form State</span>
				</div>
				<ul>
					<li>Usually a <span class="code">FormState</span> instance</li>
					<li>At least a <span class="code">FormStateInterface</span> instance</li>
					<li>Contains state of the form</li>
					<ul>
						<li>Inputs</li>
						<li>Errors</li>
						<li>Flags</li>
					</ul>
					<li>Available during all Form API stages</li>
					<li>It is changed during stages</li>
				</ul>

			</section>


			<section>
				<div class="header">
					<span>Notable values</span>
				</div>
				<ul>
					<li>form_id: the form (like a class)</li>
					<li>form_build_id: the specific form build (like an instance)</li>
					<li>Token: ensures form was previously requested</li>
				</ul>

			</section>


			<section data-state="chapter" data-background-image="./assets/images/dcon_04_color_background.jpg">
				<div class="chapter-cover">
					<span class="title">Simplified Form API workflow diagrams</span>
				</div>
			</section>


      <section>
				<section>
					<div class="header">
						<span>User requests a form</span>
					</div>

					<img class="diagram" src="./assets/illustration/simplified_fapi_diagram_01.png"/>

				</section>
				<section>
					<div class="header">
						<span>User requests a form</span>
					</div>
					<img class="diagram" src="./assets/illustration/01_simple_fapi_workflow.png"/>

				</section>
			</section>


			<section>
				<section>
					<div class="header">
						<span>User submits a form</span>
					</div>

					<img class="diagram" src="./assets/illustration/simplified_fapi_diagram_02.png"/>

				</section>
				<section>
					<div class="header">
						<span>User submits a form</span>
					</div>
					<img class="diagram" src="./assets/illustration/02_simple_fapi_workflow.png"/>

				</section>
			</section>


			<section>
				<div class="header">
					<span>User submits a form that is rebuilt</span>
				</div>

				<img class="diagram" src="./assets/illustration/simplified_fapi_diagram_03.png"/>

			</section>


			<section>
				<section>
					<div class="header">
						<span>Rebuilding loop</span>
					</div>
					<img class="diagram" src="./assets/illustration/05_simple_fapi_workflow.png"/>
				</section>


				<section>
					<div class="header">
						<span>Rebuilding loop</span>
					</div>
					<img class="diagram" src="./assets/illustration/04_simple_fapi_workflow.png"/>


				</section>


			</section>


			<section>
				<div class="header">
					<span>Example of form rebuilding</span>
				</div>
				<div>
					On each request new form element appears
				</div>
				<img class="diagram" src="./assets/illustration/06_simple_fapi_workflow.png"/>


			</section>


			<section>
				<div class="header">
					<span>Form responses</span>
				</div>
			<div class="content">
				Response can be:
			</div>

				<ul>
					<li>Markup</li>
					<li>Redirection</li>
					<li>A rebuilt form</li>
					<li>A form with errors</li>
					<li>Whatever submits decide</li>
				</ul>

			</section>


			<section data-state="chapter" data-background-image="./assets/images/dcon_04_color_background.jpg">
				<div class="chapter-cover">
					<span class="title">Is that simple?</span>
				</div>
			</section>


			<section data-background-image="assets/illustration/fapi_workflow_complete_v2_blur.png" >
				<div class="header">
					<span>Not at all!</span>
				</div>


			</section>


			<section>
				<div class="header">
					<span>What else?</span>
				</div>
					<ul>
						<li>How Drupal handles security?</li>
						<li>How Drupal keeps track of data between requests?</li>
						<li>How is AJAX handled?</li>
						<li>Validation in detail</li>
						<li>Submission in detail</li>
						<li>Rebuilding in detail</li>
						<li>Workflow details</li>
					</ul>

			</section>


			<section data-state="chapter" data-background-image="./assets/images/dcon_04_color_background.jpg">
				<div class="chapter-cover">
					<div class="">Form API stages</div>
					<div class="title">Retrieve and prepare</div>
					<div class="">(1/5)</div>
				</div>
			</section>


			<section>
				<div class="header">
					<span>1A - Retrieve</span>
				</div>

				<ul>
					<li>Form build function</li>
					<li>Dynamic elems depends on $form_state</li>
					<li>On rebuild: form is built again here</li>
				</ul>


			</section>


			<section>
				<div class="header">
					<span>1B - Prepare</span>
				</div>

				<ul>
					<li>Build id added</li>
					<li>Security token added (registered users)</li>
					<li>Alter hooks!</li>
					<li>First place to customize an existing form</li>
				</ul>

			</section>

			<section>
				<div class="header">
					<span>Retrieve and prepare</span>
				</div>

				<img class="diagram" src="./assets/illustration/fapi_stages_01_form_structure.png"/>


			</section>


			<section>
				<div class="header">
					<span>Retrieve and prepare: output</span>
				</div>

				<ul>
					<li>A built form</li>
					<li>All dynamics elements in place</li>
					<li>All altertions in place</li>
					<li>This is the <i>unprocessed</i> form</li>
				</ul>

			</section>


			<section data-state="chapter" data-background-image="./assets/images/dcon_04_color_background.jpg">
				<div class="chapter-cover">
					<div class="">Form API stages</div>
					<div class="title">Recursive building</div>
					<div class="">(2/5)</div>
				</div>
			</section>


			<section>
				<div class="header">
					<span>Recursive building</span>
				</div>
				<ul>
					<li>Goals</li>
					<ul>
						<li>Get a renderable array</li>
						<li>Collect input values (defaults or sent by user)</li>
						<li>Detect triggering button (if any)</li>
						<li>Detect which validate handler to run</li>
					</ul>
					<li>Last chance to modify/tweak the form</li>
					<ul>
						<li>Process callback</li>
						<li>After build callback</li>
					</ul>
					<li>Not standard alters!</li>

				</ul>

			</section>


			<section>
				<div class="header">
					<span>Recursive building</span>
				</div>

				<img class="diagram" src="./assets/illustration/fapi_stages_02_form_building.png"/>


			</section>


			<section>
				<div class="header">
					<span>Process callbacks</span>
				</div>
						<ul>
							<li>Called top-bottom</li>
							<li>Allow for elements to expand to multiple elements	</li>
							<li>More than 100 uses in core</li>
							<li>You may need, specially for custom elems</li>
							<li>Example: adding JS conditionally on field value</li>
						</ul>


			</section>


			<section>
				<div class="header">
					<span>After build callbacks</span>
				</div>
				<ul>
					<li>Called bottom-to-top</li>
					<li>Less than 10 uses in core</li>
					<li>Unlikely you need it</li>
					<li>Example: removing elements after file disk check</li>
				</ul>


			</section>


			<section>
				<div class="header">
					<span>Handler detection</span>
				</div>
				<div class="spacer"></div>
				<div class="r-hstack">
					<div class="r-vstack">
					  <div>Validation</div>
						<div class="spacer-x"></div>
						<ul>
							<li>Button pressed
								<br/>if not then
							</li>
							<li>Form-level validate</li>
						</ul>
					</div>
					<div class="r-vstack">
					  <div>Submit</div>
						<div class="spacer-x"></div>
						<ul>
							<li>Button pressed
								<br/>if not then
							</li>
							<li>Form-level submit</li>
						</ul>
					</div>
			</div>


			</section>


			<section data-state="chapter" data-background-image="./assets/images/dcon_04_color_background.jpg">
				<div class="chapter-cover">
					<div class="">Form API stages</div>
					<div class="title">Validation</div>
					<div class="">(3/5)</div>
				</div>
			</section>


			<section>
				<div class="header">
					<span>Validation</span>
				</div>
				<div>Form is checked (security and valid values)</div>
				<ul>
					<li>Check token (prevents CSRF)</li>
					<li>Validate all elems bottom-to-top</li>
					<li>Call elem's validate, if any</li>
					<li>Validate form (button or form handler)</li>
					<li>Can change $form or $form_state for next rebuild</li>
					<li>Can enable rebuilding</li>
				</ul>

			</section>


			<section>
				<div class="header">
					<span>Validation</span>
				</div>

				<img class="diagram" src="./assets/illustration/fapi_stages_03_validation.png"/>


			</section>


			<section>
				<div class="header">
					<span>Validation errors</span>
				</div>
				<ul>
					<li>Errors are added to rendered form</li>
					<li>Submit handlers are skipped</li>
					<li>Rebuilding is forbidden</li>
				</ul>

			</section>


			<section data-state="chapter" data-background-image="./assets/images/dcon_04_color_background.jpg">
				<div class="chapter-cover">
					<div class="">Form API stages</div>
					<div class="title">Submit</div>
					<div class="">(4/5)</div>
				</div>
			</section>


			<section>
				<div class="header">
					<span>Submit</span>
				</div>
				<div>Form is executed, running any needed actions</div>
				<ul>
					<li>Run submit handlers (button or form)</li>
					<li>Return response, if any</li>
					<li>Usually a redirect or markup is delivered</li>
					<li>Can change $form or $form_state for next rebuild</li>
					<li>Can enable rebuilding</li>
				</ul>

			</section>


			<section>
				<div class="header">
					<span>Submit</span>
				</div>

				<img class="diagram" src="./assets/illustration/fapi_stages_04_submission.png"/>


			</section>


			<section data-state="chapter" data-background-image="./assets/images/dcon_04_color_background.jpg">
				<div class="chapter-cover">
					<div class="">Form API stages</div>
					<div class="title">Rebuild</div>
					<div class="">(5/5)</div>
				</div>
			</section>


			<section>
				<div class="header">
					<span>Rebuild</span>
				</div>
				<div>Rebuilding allows for complex forms</div>
				<ul>
					<li>Multi-step forms</li>
					<li>Dynamic elements (adding, removing, etc)</li>
					<li>AJAX calls that modifies form</li>
					<li>Runs building steps (retrieve, prepare and actual building)</li>
					<li>Changes in $form and $form_state allow form changes when rebuilt</li>
				</ul>

			</section>


			<section>
				<div class="header">
					<span>Rebuild</span>
				</div>

				<img class="diagram" src="./assets/illustration/fapi_stages_05_rebuild.png"/>


			</section>


			<section data-state="chapter" data-background-image="./assets/images/dcon_04_color_background.jpg">
				<div class="chapter-cover">
					<div class="title">Cache / Persistance</div>
				</div>
			</section>


			<section>
				<div class="header">
					<span>Cache / Persistance</span>
				</div>
				<ul>
					<li>Named "cache" but it should be persistance</li>
					<li>Allows for AJAX, mutistep and dynamic elements</li>
					<li>Usually Drupal takes care of it (auto-enabled)</li>
					<li>You may need to deal with it in special cases</li>
				</ul>
			</section>


			<section>
				<div class="header">
					<span>Cache / Persistance: What?</span>
				</div>
				<ul>
					<li>$form and $form_state are saved</li>
					<li>$form_state only given set of properties (see <span class="code">FormState::getCacheableArray</span>)</li>
					<li>Use <span class="code">FormState</span>'s functions to CRUD data that will be cached/persisted</li>
					<ul class="code">
						<li>get</li>
						<li>set</li>
						<li>has</li>
					</ul>

				</ul>
			</section>


			<section data-state="chapter" data-background-image="./assets/images/dcon_04_color_background.jpg">
				<div class="chapter-cover">
					<span class="title">AJAX requests</span>
				</div>
			</section>


			<section>
				<div class="header">
					<span>AJAX requests</span>
				</div>
				<ul>
					<li>They follow the same workflow</li>
					<li>They return what #ajax_callback returns</li>
					<li>They need cache/persistence (auto-enabled)</li>
					<li>They can also return one or more AJAX commands</li>
				</ul>

			</section>


			<section>
				<div class="header">
					<span>AJAX requests: How To</span>
				</div>
					<ul>
						<li>Element triggers an AJAX request</li>
						<li>Form is build, validated and executed</li>
						<li>During submit, some values are changed and rebuild enabled</li>
						<li>During rebuild, those changed values make form get a change (e.g.: more or less elements) </li>
						<li>#ajax_callback returns changed part of the form, the form or AJAX commands</li>
						<li>JS layer takes reponse and processes it (e.g: inserts markup into the HMTL)</li>
					</ul>

			</section>


			<section>
				<div class="header">
					<span>AJAX requests: Don't</span>
				</div>
				<ul>
					<li>Don't change $form during #ajax_callback</li>
					<li>#ajax_callback is not a submit, it is a result gatherer! </li>
					<li>Any change should be done during rebuilding</li>
				</ul>

			</section>


			<section data-state="chapter" data-background-image="./assets/images/dcon_04_color_background.jpg">
				<div class="chapter-cover">
					<span class="title">The complete workflow illustration</span>
				</div>
			</section>


			<section data-background-image="assets/illustration/fapi_workflow_complete_v2.png" data-background-size="contain">


			</section>


			<section>
				<div class="header">
					<span>Simplifications</span>
				</div>
				<div>Not the whole picture</div>
				<ul>
					<li>Batch and programmed forms are not covered</li>
					<li>Details</li>
					<li>How HTML id are handled</li>
					<li>Some edge cases</li>
					<li>Security details</li>
					<li>More details</li>
				</ul>
			</section>


			<section data-state="chapter" data-background-image="./assets/images/dcon_04_color_background.jpg">
				<div class="chapter-cover">
					<span class="title">Key points</span>
				</div>
			</section>


			<section>
				<div class="header">
					<span>Key points</span>
				</div>
				<ul>
					<li>Form's build function and alters for big changes</li>
					<li>Process and after builds callbacks for adjustments and tweaks </li>
					<li>Use the rebuilding loop for dynamic forms</li>
					<li>Use FormSate to store your own variables</li>
					<li>Use #ajax_callback to return response, not to change the form</li>
					<li>Check Drupal Examples module!</li>
				</ul>

			</section>


			<section data-state="no-logo" data-background-image="assets/images/end_01.png">
			</section>


			<section data-state="no-logo" data-background-image="assets/images/end_02.png">
			</section>


			<section data-state="no-logo" data-background-image="./assets/images/end_03.png">
			</section>


		</div>

	</div>

			<div class="color-bar">
			<img src="./assets/images/dcon_02_bottom_bar.png" />
		</div>


	<script src="dist/reveal.js"></script>
	<script src="plugin/notes/notes.js"></script>
	<script src="plugin/markdown/markdown.js"></script>
	<script src="plugin/highlight/highlight.js"></script>
	<script>
		// More info about initialization & config:
		// - https://revealjs.com/initialization/
		// - https://revealjs.com/config/
		Reveal.initialize({
			hash: true,
			showNotes: false,
			slideNumber: false,
			defaultTiming: 33,
			transition: 'slide',

			// Learn about plugins: https://revealjs.com/plugins/
			plugins: [RevealMarkdown, RevealHighlight, RevealNotes]
		});


		// Default background image: set a background image for all slides that
		// doesn't have any defined background.
		for (var slide of document.getElementsByTagName('section')) {
			if (!(slide.getAttribute('data-background') ||
				slide.getAttribute('data-background-video') ||
				slide.getAttribute('data-background-image') ||
				slide.getAttribute('data-background-iframe'))) {
				slide.setAttribute('data-background-image', './assets/images/dcon_05_bandw_background.jpg')
			}
		}

	</script>
</body>

</html>